# プロジェクト API ガイド

プロジェクトの API を組み合わせて、うまくいかなかった実行を見つけ、原因を調べ、工程と配置を直して、直ったかを確かめる流れを説明します。各 API の項目・エラーは、[ユーザー API リファレンス（プロジェクト）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md)を参照してください。

## 始める前に

### トークン

この流れは、アプリケーション（外部ツールでのログイン）のトークンで行います。システム連携のトークンで呼べるプロジェクトの API は、プロジェクト一覧の取得・ワークフローの実行の開始と取得・トリガーの発火・ワークフローの実行の成果物の一覧と中身の取得・ワークフローの実行の中断・サイクルの巡回の実行の停止・実行の結果の取得（状態の項目だけ）だけです。

- 呼べるかどうかは、トークンの利用者のプロジェクトでの役割で決まります。読むのはメンバー、実行を始める・発火するのはメンバーと組織の運用の役割の人、締め切りを決める・確認担当者を付け替える・ほかの人が始めた実行を中断する・プロジェクトを一時停止・再開するのはオーナーと運用担当（組織の運用の役割の人を含む。自分が始めた実行は、始めた本人も中断できます）、ほかのプロジェクトの変更はオーナー、確認依頼を判断するのは確認担当者と期間中の代理人です（[呼べる人と 404・403](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#common-access)）。組織の運用の役割の人は、参加していなくても、読む API の一部と運転の操作を呼べます。
- 長い作業の途中でアクセストークンの期限が切れたら、リフレッシュトークンで更新します（[認証ガイド — Authorization Code フロー](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/auth-guide.md#authorization-code)）。
- マーケットプレイス版ではスコープによる制限はありません。

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

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

```bash
curl "https://<your-domain>/api/v1/projects/$PROJECT_ID/executions?outcome=problems&from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

結果の値と画面の表示は[結果の値](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#execution-outcomes)を参照してください。

## 2. 原因を調べる

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

| 知りたいこと                                          | 読む API                                                                                                                                                                                                         |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 登録 Agent がやり切ったと報告したか、その理由とコメント、最終応答            | 実行の結果（`GET /v1/projects/{projectId}/executions/{executionId}`）の `envelope.completionReport`・`summary`。中身は登録 Agent が報告したものです                                                                                    |
| どのツールを呼び、成功したか・止められたか・何秒かかったか                   | ツールの呼び出しの一覧（`…/executions/{executionId}/operations`）。`cursor` で最後まで読みます                                                                                                                                        |
| 依頼の内容、入口のガードレールで止められたか、Agent からの質問              | 実行の時系列（`…/executions/{executionId}/timeline`）                                                                                                                                                                  |
| ワークフローの実行を始めたときの工程・配置・連携先                       | ワークフローの実行の設定（`GET /v1/projects/{projectId}/runs/{runId}/config`）。cycle には無いので、今の値をプロジェクトの取得で読みます                                                                                                               |
| ワークフローの実行の今の案件設定（配置と工程ごとの入力ファイル・parameters・連携先） | 案件設定の取得（`GET /v1/projects/{projectId}/runs/{runId}/case-config`。[案件設定の取得](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#get-run-case-config)） |
| 今の工程・配置                                         | プロジェクトの取得（`GET /v1/projects/{projectId}`）                                                                                                                                                                      |
| ワークフローの実行の成果物（開始で結んだ入力ファイルと、工程が作った出力）           | 成果物の一覧（`GET /v1/projects/{projectId}/artifacts?run_id=…`）と中身（`…/artifacts/{artifactId}/content`）                                                                                                               |
| 連携先のツールの説明・エージェントカード                            | 連携先の API（`GET /v1/connectors/mcp/{connectionId}`・`GET /v1/connectors/a2a/{connectionId}`）                                                                                                                      |
| cycle の巡回の途中の文章と最終応答の全文                         | 実行の会話（`GET /v1/conversations/{conversationId}/messages`。[実行の会話](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#execution-conversations)）       |

- ツールに渡した引数と返ってきた中身は、記録されていないので読めません。
- cycle では、実行のときに使った工程・配置・連携先は残りません。今の値と比べるしかありません。

## 3. 工程と配置を直す

### 直せるもの

| 直すもの                                                                        | 直し方                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 登録 Agent の中の動き（何をするか・どう答えるか）                                                | プロジェクトの API では直せません。登録 Agent を作った開発者が直し、管理者が登録し直します（[開発](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop.md)）                                                                                   |
| 工程（名前・説明・確認工程の設定・差し戻し先・工程の時刻）                                               | 工程を変える API（`PATCH /v1/projects/{projectId}/steps/{stepId}`）                                                                                                                                                               |
| 工程の並び・数                                                                     | 工程を足す・並べ替える・消す API                                                                                                                                                                                                        |
| 工程に置く登録 Agent                                                               | 下の[登録 Agent を入れ替える](#replace-agent)                                                                                                                                                                                       |
| 配置の担当工程                                                                     | 配置の担当工程を変える API（`PUT …/placements/{placementId}/steps`）                                                                                                                                                                   |
| cycle の巡回                                                                   | 巡回を変える API（`PATCH …/placements/{placementId}/schedule`）                                                                                                                                                                   |
| トリガー（時刻・Webhook の起動）                                                        | トリガーを作る・変える・消す API（`POST …/triggers`・`PATCH`・`DELETE …/triggers/{triggerId}`。[トリガー](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#triggers)）             |
| プロジェクトの Webhook（出来事を外へ知らせる）                                                 | Webhook の API（`POST …/webhooks`・`PATCH`・`DELETE …/webhooks/{webhookId}`。[Webhook](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#webhooks)）               |
| 配置の工程の設定（workflow: 登録 Agent の parameters・接続の枠の連携先・前の工程の出力の受け渡し、cycle: 環境変数） | 工程の設定を書く API（`PUT …/placements/{placementId}/steps/{stepId}/runtime-config`）                                                                                                                                              |
| 確認待ちのワークフローの実行の案件設定（入力ファイル・parameters・連携先）                                  | 案件設定を置き換える API（`PUT …/runs/{runId}/case-config`。確認待ちの間だけ・オーナーだけ。[案件設定を置き換える](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#update-run-case-config)）      |
| プロジェクトの定義を別の環境へ持っていく                                                        | 定義を書き出す API（`GET …/definition`）と、書き出した定義からプロジェクトを作る API（`POST /v1/projects/import`。[取り込み](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#import-project)） |

### 書き換えの流れ

既にあるものを変える API は、次の流れで呼びます（[書き換えと送り直し](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#common-update)）。

1. 取得して、応答の `digest` を控えます。どの取得の `digest` を使うかは、変える API の説明にあります（例: 工程は、プロジェクトの取得の工程の `digest`）。
2. 変える API に、その値を `baseDigest` として送ります。送った項目だけが変わります。ただし、工程の並びと配置の担当工程、配置の工程の設定（`runtime-config`）は、送ったもので丸ごと置き換わります。
3. `409 Conflict`（`stale_base`）が返ったら、取得した後にほかの変更が入っています。取得し直して、変える内容を見直してから送り直します。
4. 続けて同じものを変えるときは、応答の `digest` を使えます。

案件設定を置き換える API だけは、`digest` ではなく版の番号で確かめます。案件設定の取得で読んだ `revision` を `expectedRevision` として送り、ずれていると `409 Conflict`（`revision_conflict`）です。取得し直して、変える内容を見直してから送り直します。

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

```bash
curl -X PATCH "https://<your-domain>/api/v1/projects/$PROJECT_ID/steps/$STEP_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"baseDigest": "<工程の digest>", "description": "<直した説明>"}'
```

作る API は、送り直すともう 1 つ作られます。応答が届かなかったときは、取得で作られたかを確かめてから送り直し、できてしまった余分なものは消します。

### 定義の変更に承認が要るテナント

テナントで定義の変更に承認が要るとき（管理者の設定）、プロジェクト・工程・配置・トリガーを変える API の変更は、すぐには反映されず、承認待ちになります（プロジェクトの名前・説明・タグ・公開するかの変更は、承認待ちにならず、すぐ反映されます）。

- 書く API の答えの `definitionApproval` の `status` が `"pending"` なら、承認待ちです。承認されるまで、実行は前の（承認された）定義で動きます。承認待ちの要約は `GET /v1/projects/{projectId}/definition-approval` で読めます。
- 承認・差し戻しは、承認する人（申請した人ではない、ほかのオーナーか組織の管理者）が製品の画面で行います。API では決められません。
- 承認待ちの変更は、既定の取得には出ません。続けて変えるときは、取得に `definition=pending` を付けて読み、その `digest` を `baseDigest` に送ります（既定の取得の `digest` を送ると `409 Conflict`（`stale_base`）です）。
- 応答が届かなかったとき（時間切れ・途中で切れた）は、`definition=pending` で読んで、変更が入ったかを確かめてから送り直します。作る API（工程・配置・トリガー）を確かめずに送り直すと、承認待ちに同じものが 2 つできます。プロジェクトを作る API は、作られたかもしれないので、プロジェクトの一覧（`GET /v1/projects`）で確かめてから送り直します。
- 承認待ちは、オーナーが取り消せます（`DELETE /v1/projects/{projectId}/definition-approval`。`pendingDigest` に承認待ちの `digest`）。
- プロジェクトを作ると、最初の定義も承認待ちになります。承認されるまで、ワークフローの実行を始められません（`409 Conflict`、`definition_pending`）。

承認が要らないテナントでも、定義が変わる書き込みは、そのたびに定義の版と記録 (証跡) に残ります。プロジェクトを作ったときは最初の版だけで、記録 (証跡) の行は残りません。前の版と同じ内容になる書き込みでは、版も記録 (証跡) も増えません。同じプロジェクトに同時に書くと、時の順によって 1 つの版にまとまることがあり、そのときは先に版を記録した呼び出しの人が記録者になります。間に記録が入れば 2 つの版になります。

### 登録 Agent を入れ替える

工程に置いた登録 Agent を別の登録 Agent に替える専用の API はありません。新しい配置を置いてから、元の配置を外します。

1. 置ける登録 Agent を、置ける Agent の候補の取得（`GET /v1/projects/agent-candidates?project_type=workflow`。cycle は `project_type=cycle`）で探します。workflow のプロジェクトに置けるのは、`certified` が true の登録 Agent だけです。
2. 動いているワークフローの実行が無いときに行います（ワークフローの実行の一覧を `limit=100` で取得し、`status` が `"running"`・`"waiting_gate"` のものが無いことを確かめます）。元の Agent と新しい Agent の両方が動かないようにしたいときは、プロジェクトを一時停止します（`PATCH /v1/projects/{projectId}` で `status` を `"paused"`）。
3. 新しい登録 Agent を、元の配置と同じ担当工程で置きます（`POST /v1/projects/{projectId}/placements` に `marketplaceAgentId` と `stepIds`）。cycle では、巡回も設定します（`PATCH …/placements/{placementId}/schedule`）。
4. 元の配置を起動先にしている Webhook のトリガーは、トリガーを変える API（`PATCH /v1/projects/{projectId}/triggers/{triggerId}` に `placementId`・`stepId`）で新しい配置に付け替えます。Webhook のトリガーの起動先は、プロジェクトの取得の `triggers[].placementId` で分かります。
5. 元の配置を外します（`DELETE /v1/projects/{projectId}/placements/{placementId}`）。
6. 一時停止したときは、プロジェクトを再開します（`status` を `"active"`）。

- 配置の ID が変わります。過去の実行は、元の配置の ID のまま残ります。
- 一時停止しても、動いている実行は止まりません。実行履歴を `outcome=running` で絞って、終わってから置き換えます。
- 一時停止中のプロジェクトでは、途中のワークフローの実行は次の工程に進まず、再開するまで終わりません。一時停止する前に、動いているワークフローの実行を終わらせます。
- ワークフローの実行の一覧に出るのは、新しい方から 100 件までです。それより古いワークフローの実行が確認待ちのまま残っていても、一覧では見つけられません。
- 同じ工程にほかの登録 Agent も置いているときは、新しい配置は最後に動きます。配置を並べ替える API はありません。

## 4. 直ったか確かめる

1. 直した後に、実行を起こします。

   <!-- -->

   - workflow は、ワークフローの実行を始め（`POST /v1/projects/{projectId}/runs`。`Idempotency-Key` ヘッダーが要ります）、ワークフローの実行の取得（`GET /v1/projects/{projectId}/runs/{runId}`）で進み具合を見ます。終わりを待つときは、`status` が `"closed_done"`・`"closed_rejected"`・`"closed_failed"`・`"cancelled"` のどれかになったところで止めます。開始で結んだ入力ファイルと工程が作った成果物は、成果物の一覧と中身で確かめます。やめるときは、ワークフローの実行の中断（`POST /v1/projects/{projectId}/runs/{runId}/cancel`。本文に `commandId` が要ります）を使います。
   - cycle は、Webhook のトリガーを発火し（`POST /v1/projects/{projectId}/triggers/{triggerId}/fire`。本文に、発火ごとに一意な `eventId` が要ります。同じ発火を送り直すときは同じ値を使います）、[発火で動いた実行の見分け方](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#triggers-find-execution)の手順で実行を見つけます。動いている巡回の実行を止めるときは、`POST /v1/projects/{projectId}/executions/{executionId}/cancel` を使います（止まるまで 1 分ほどかかることがあります）。

2. 新しい実行の結果を、直す前の実行と比べます。

3. しばらく動かしたら、実行履歴を直した日の前後の期間で絞って比べます。KPI の期間は直近 7・30・90 日だけで、直した日で区切れません。

何をいつ変えたかは、呼ぶ側で控えてください。
