プロジェクト API ガイド

プロジェクトの API とライブラリ（Agent・プレイブック・スキル）の API を組み合わせて、うまくいかなかった実行を見つけ、原因を調べ、直して、直ったかを確かめる流れを説明します。各 API の項目・エラーは、ユーザー API リファレンス（プロジェクト）とユーザー API リファレンス（会話・ライブラリ・組織）を参照してください。

始める前に

トークン

この流れは、アプリケーション（Authorization Code フロー）のトークンで行います。システム連携のトークンで呼べるプロジェクトの API は、プロジェクト一覧の取得・ワークフローの実行の開始と取得・トリガーの発火だけで、実行の結果やライブラリは読めません。

呼べるかどうかは、トークンの利用者のプロジェクトでの役割で決まります。読むのはメンバー、プロジェクトを変える・実行を始める・発火するのはオーナー、確認依頼を判断するのは確認担当者です（呼べる人と 404・403）。
SSO でログインしていない利用者のトークンでは、プロジェクトの API の多くが 403 Forbidden（sso_required）になります。
長い作業の途中でアクセストークンの期限が切れたら、リフレッシュトークンで更新します（認証ガイド）。

スコープ

することに合わせて、Console でアプリケーションのスコープを選びます（認証ガイドのスコープ）。

すること	スコープ
実行・記録 (証跡)・KPI・プロジェクトの設定・確認依頼・連携先を読む	`project:read`
Agent・プレイブック・スキルを読む	`assets:read`
実行の会話（Agent の途中の文章・コマンドの出力など）を読む	`chat:history`
プロジェクト・工程・配置・巡回を直す	`project:write`
Agent・プレイブック・スキルを作る・直す・コピーする	`assets:write`
要らなくなった Agent・プレイブック・スキルを消す	`assets:delete`
ワークフローの実行を始める・トリガーを発火する	`project:run`
確認依頼を判断する	`project:decide`

1. うまくいかなかった実行を見つける

KPI（GET /v1/projects/{projectId}/kpi）で、Agent の完遂率と結果ごとの数を見て、増えた失敗の当たりを付けます。期間は直近 7・30・90 日から選びます。
実行履歴（GET /v1/projects/{projectId}/executions）を outcome=problems と期間（from・to）で絞って、うまくいかなかった実行を並べます。結果が記録されていない実行は outcome=missing で並べます。結果の理由（reasonCode）では絞れないので、取得した一覧を手元で絞ります。
必要なら、記録 (証跡)（GET /v1/projects/{projectId}/audit）で、確認の決定や実行ルール・メンバーの変更を見ます。

curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/$PROJECT_ID/executions?outcome=problems&from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

結果の値と画面の表示は結果の値を参照してください。

2. 原因を調べる

見つけた実行（executionId）について、知りたいことに合わせて読みます。

知りたいこと	読む API
Agent がやり切ったと報告したか、その理由とコメント、最終応答	実行の結果（`GET /v1/projects/{projectId}/executions/{executionId}`）の `envelope.completionReport`・`summary`
どのツールを呼び、成功したか・止められたか・何秒かかったか	ツールの呼び出しの一覧（`…/executions/{executionId}/operations`）。`cursor` で最後まで読みます
つながった MCP と、配ったスキルの版	実行の結果の `usedSettings`
依頼の内容、入口のガードレールで止められたか、Agent からの質問	実行の時系列（`…/executions/{executionId}/timeline`）
ワークフローの実行を始めたときの工程・配置・連携先	ワークフローの実行の設定（`GET /v1/projects/{projectId}/runs/{runId}/config`）。cycle には無いので、今の値をプロジェクトの取得で読みます
今の工程・配置、置いた Agent のゴールとガードレール	プロジェクトの取得（`GET /v1/projects/{projectId}`）。ほかの利用者の非公開の Agent でも、置いてあれば読めます
Agent・プレイブック・スキルの中身	ライブラリの取得。スキルは版の一覧・ファイルの一覧・1 ファイル・ダウンロードで読みます
連携先のツールの説明・エージェントカード	連携先の API（`GET /v1/connectors/mcp/{connectionId}`・`GET /v1/connectors/a2a/{connectionId}`）
Agent の途中の文章、コマンドとその出力、最終応答の全文	実行の会話（`GET /v1/conversations/{conversationId}/messages`）。読めるのはプロジェクトを作った人だけです（実行の会話）

ツールに渡した引数と返ってきた中身は、記録されていないので読めません。
workflow の最終応答（summary）は 2000 文字までです。全文は実行の会話で読みます。
cycle では、実行のときに使った工程・配置・連携先は残りません。今の値と比べるしかありません。

3. 直す

直し方を選ぶ

直し方は 2 つあります。効く範囲と、記録 (証跡) に残るかが違います。

直し方	効く範囲	変えられるもの	記録 (証跡)
ライブラリを直す	その Agent・プレイブック・スキルを使っているすべての所（ほかのプロジェクトも含みます）。スキルは、版を固定していない Agent とスケジュールだけが新しい版に変わります	自分の Agent・プレイブック・スキルの項目	残りません
プロジェクトを直す	このプロジェクトだけ	プロジェクト・工程・配置（担当工程・記憶・巡回）。トリガー・連携先・メンバー・通知・実行ルールは画面で変えます	この方法で変えられるもののうち、確認担当者と確認方法の変更だけが残ります（実行ルール・メンバー・「メールで起動」を画面で変えたときも残ります）

置いた Agent をほかのプロジェクトでも使っているかは、プロジェクトの取得の配置の exclusiveToThisProject で分かります。false の Agent をライブラリで直すと、ほかのプロジェクトにも効きます。このプロジェクトだけを直したいときは、このプロジェクトだけ Agent を直すの手順で行います。

書き換えの流れ

既にあるものを変える API は、次の流れで呼びます（書き換えと送り直し）。

取得して、応答の digest を控えます。どの取得の digest を使うかは、変える API の説明にあります（例: スキルのファイルはファイルの一覧の digest、スキルの設定はスキルの取得の digest）。
変える API に、その値を baseDigest として送ります。送った項目だけが変わります。ただし、配列や並び（Agent の spec.skills・spec.inputFiles、工程の並び、配置の担当工程）と、スキルのファイルを丸ごと入れ替える API で送ったファイルは、送ったもので置き換わります。
409 Conflict（stale_base）が返ったら、取得した後にほかの変更が入っています。取得し直して、変える内容を見直してから送り直します。
続けて同じものを変えるときは、応答の digest を使えます。応答に無いとき（スキルのファイルを変えた後など）は、取得し直します。

ほぼ同時に届いた 2 つの書き換えは、両方が通ることがあります（スキルの文書の書き換えを除きます）。同じものを複数の所から変えないようにしてください。

curl
curl -X PATCH "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"baseDigest": "<取得の digest>", "spec": {"guardrail": "<直したガードレール>"}}'

作る API とコピーする API は、送り直すともう 1 つ作られます。応答が届かなかったときは、一覧で ID と createdAt を見て作られたかを確かめてから送り直し、できてしまった余分なものは消します。

ほかの利用者の Agent・プレイブック・スキルを直す

ほかの利用者のものは直せません。公開されているものをコピーして、自分のものを直します。非公開のものは、持ち主に頼みます。

Agent をコピーしても、中のプレイブック・スキル・入力ファイルは、元の利用者のものを指したままです。コピーした Agent の spec を変えるときは、プレイブックを自分のものに、スキルを自分のものか公開されているものに、入力ファイルを自分のものに替えます。替えないと 400 が返ります。
Agent の入力ファイルのうち、実行のときに渡るのは、プロジェクトを作った人のファイルだけです。ほかの人のファイルを付けても、エラーにならずに外れます。

このプロジェクトだけ Agent を直す

ほかのプロジェクトでも使っている Agent を、このプロジェクトでだけ直すための専用の API はありません。新しい Agent を作って置き換えます。

新しい Agent を用意します。
- 元が自分の Agent なら、Agent の取得で読んだ name・description・spec から、Agent を作る API（POST /v1/agents）で作ります。自分の Agent はコピーできません（409 Conflict、already_owned）。
- 元がほかの利用者の公開されている Agent なら、コピーします（POST /v1/agents/:agentId/copy）。
新しい Agent を直します（PATCH /v1/agents/:agentId）。
動いているワークフローの実行が無いときに行います（ワークフローの実行の一覧を limit=100 で取得し、status が "running"・"waiting_gate" のものが無いことを確かめます）。元の Agent と新しい Agent の両方が動かないようにしたいときは、プロジェクトを一時停止します（PATCH /v1/projects/{projectId} で status を "paused"）。一時停止で止まるもの・止まらないものは、プロジェクトのプロジェクトを変える API の説明を参照してください。
新しい Agent を、元の配置と同じ担当工程で置きます（POST /v1/projects/{projectId}/placements）。
元の配置の記憶を、新しい配置に設定します（PATCH …/placements/{placementId}/memory）。cycle では、巡回も設定します（PATCH …/placements/{placementId}/schedule）。
元の配置を起動先にしている Webhook のトリガーと「メールで起動」は、画面で新しい配置に付け替えます。外部 API ではトリガーを変えられません。Webhook のトリガーの起動先は、プロジェクトの取得の triggers[].placementId で分かります。「メールで起動」の起動先は画面で確かめます。
元の配置を外します（DELETE /v1/projects/{projectId}/placements/{placementId}）。
一時停止したときは、プロジェクトを再開します（status を "active"）。

この方法には、次の制約があります。

元の Agent を読めることが要ります（自分の Agent か、公開されている Agent）。ほかの利用者の非公開の Agent は、持ち主に頼みます。
新しい Agent が指せるのは、自分のプレイブック、自分のものか公開されているスキル、自分の入力ファイルです。元の Agent がほかの利用者のプレイブック・スキルを指していたら、公開されているものはコピーして自分のものにします（スキルは公開されているものをそのまま指せます）。非公開のものは、持ち主に頼みます。
実行のときに渡る入力ファイルは、プロジェクトを作った人のものだけです。そのため、入力ファイルを使う Agent をこの方法で直せるのは、プロジェクトを作った人だけです。
一時停止しても、動いている実行は止まりません。実行履歴を outcome=running で絞って、終わってから置き換えます。
一時停止中のプロジェクトでは、途中のワークフローの実行は次の工程に進まず、再開するまで終わりません。一時停止する前に、動いているワークフローの実行を終わらせます。
ワークフローの実行の一覧に出るのは、新しい方から 100 件までです。それより古いワークフローの実行が確認待ちのまま残っていても、一覧では見つけられません。
一時停止の前に受け付けた発火とメールは、一時停止の後でも、元の Agent で動くことがあります。
同じ工程にほかの Agent も置いているときは、配置を 1 つずつ実行する工程では、新しい配置は最後に動きます（「同時に実行」の工程では、ほかの配置と同時に動きます）。配置を並べ替える API はありません。
配置の ID が変わります。過去の実行は、元の配置の ID のまま残ります。
配置を置く・外すことは記録 (証跡) に残りません（「メールで起動」の付け替えは残ります）。

スキルを直す

文書（.md・.json・.yaml・.yml）は、スキルの文書を書き換える API（PATCH /v1/skills/:skillId/files）で直せます。
スクリプトや実行ファイルを含むスキルは、文書も含めて、ファイルを丸ごと入れ替える API（PUT /v1/skills/:skillId/files）で直します。今の版をダウンロード（GET /v1/skills/:skillId/download）して手元で直し、丸ごと送ります。設定値のファイルなど、文書ではないファイルも、丸ごと入れ替えて直します。
前の版のファイルをすべて取り出したいときは、版を指定してスキルをコピーし（POST /v1/skills/:skillId/copy）、コピーしたスキルをダウンロードします。
機密（設定値のファイルなど）を含むスキルは公開しないでください。公開すると、ほかの利用者もすべてのファイルを読めます。新しい版で機密を消しても、前の版を指定したコピーで取り出せます。

4. 直ったか確かめる

直した後に、実行を起こします。
- workflow は、ワークフローの実行を始め（POST /v1/projects/{projectId}/runs。Idempotency-Key ヘッダーが要ります）、ワークフローの実行の取得（GET /v1/projects/{projectId}/runs/{runId}）で進み具合を見ます。
- cycle は、Webhook のトリガーを発火し（POST /v1/projects/{projectId}/triggers/{triggerId}/fire。本文に、発火ごとに一意な eventId が要ります。同じ発火を送り直すときは同じ値を使います）、発火で動いた実行の見分け方の手順で実行を見つけます。
新しい実行の結果を、直す前の実行と比べます。スキルを直したときは、実行の結果の usedSettings で、新しい版が配られたかを確かめます。版を固定している Agent は新しい版に変わらないので、Agent の spec.skills の versionId を新しい版に替えます。
しばらく動かしたら、実行履歴を直した日の前後の期間で絞って比べます。KPI の期間は直近 7・30・90 日だけで、直した日で区切れません。

ライブラリの変更と、この API でのプロジェクトの変更（確認担当者・確認方法を除きます）は、記録 (証跡) に残りません。何をいつ変えたかは、呼ぶ側で控えてください。

始める前に​

トークン​

スコープ​

1. うまくいかなかった実行を見つける​

2. 原因を調べる​

3. 直す​

直し方を選ぶ​

書き換えの流れ​

ほかの利用者の Agent・プレイブック・スキルを直す​

このプロジェクトだけ Agent を直す​

スキルを直す​

4. 直ったか確かめる​