# プロジェクト API ガイド

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

## 始める前に

### トークン

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

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

### スコープ

することに合わせて、Console でアプリケーションのスコープを選びます（[認証ガイドのスコープ](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/auth-guide.md)）。

| すること                                                                    | スコープ             |
| ----------------------------------------------------------------------- | ---------------- |
| 実行・記録 (証跡)・KPI・プロジェクトの設定・確認依頼・連携先・キュー・プロジェクトのライブラリを読む                   | `project:read`   |
| Agent・プレイブック・スキルを読む                                                     | `assets:read`    |
| 実行の会話（Agent の途中の文章・コマンドの出力など）を読む                                        | `chat:history`   |
| プロジェクト・工程・配置・巡回・トリガー・Webhook と、ワークフローの実行の締め切り・確認担当者、プロジェクトのライブラリを直す     | `project:write`  |
| Agent・プレイブック・スキルを作る・直す・コピーする                                            | `assets:write`   |
| 要らなくなった Agent・プレイブック・スキルを消す                                             | `assets:delete`  |
| ワークフローの実行を始める・トリガーを発火する・失敗した巡回をもう一度動かす・閉じたワークフローの実行を再開する・ワークフローの実行を中断する | `project:run`    |
| 確認依頼を判断する・期限を延ばす                                                        | `project:decide` |

## 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` を付けます（例: `reason_code=guardrail_blocked`。値は大文字と小文字を区別します）。
3. 必要なら、記録 (証跡)（`GET /v1/projects/{projectId}/audit`）で、確認の決定や実行ルール・メンバー・定義の変更を見ます。

```bash
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"
```

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

## 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}`）                                                                                                                                        |
| 外部の自動化の工程の送信の結果（宛先・HTTP の状態・かかった時間） | 実行の結果の `automation`（実行履歴の行の `automationHttpStatus`）                                                                                                                                                                              |
| 外部の自動化の工程の宛先と送る本文の形                 | プロジェクトの取得の工程の `automationConfig` と、宛先の一覧（`GET /v1/projects/automation-destinations`）                                                                                                                                             |
| Agent の途中の文章、コマンドとその出力、最終応答の全文      | 実行の会話（`GET /v1/conversations/{conversationId}/messages`）。読めるのは、その実行のときのプロジェクトの持ち主だけです（[実行の会話](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#execution-conversations)） |

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

## 3. 直す

### 直し方を選ぶ

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

| 直し方       | 効く範囲                                                                                                                                         | 変えられるもの                                                                                                                                   | 記録 (証跡)                                                                                                                                                                                            |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ライブラリを直す  | その Agent・プレイブック・スキルを使っているすべての所（ほかのプロジェクトも含みます）。スキルは、バージョンを固定していない Agent とスケジュールだけが新しいバージョンに変わります（公開の承認が有効なテナントで公開中のスキルは、承認されるまで前のバージョンのままです） | 自分の Agent・プレイブック・スキルの項目                                                                                                                   | 残りません                                                                                                                                                                                              |
| プロジェクトを直す | このプロジェクトだけ                                                                                                                                   | プロジェクト・工程・配置（担当工程・記憶・巡回）・トリガー（時刻・Webhook の起動）・プロジェクトの Webhook。定義の書き出しと、書き出した定義の取り込み（新しいプロジェクトを作る）もできます。連携先・メンバー・通知・実行ルール・「メールで起動」は画面で変えます | この方法で変えた、プロジェクトの定義（名前・説明・タグ・上限・レーン・報告先・公開するか）・工程・配置・トリガー・プロジェクトの Webhook の変更が残ります（記録者は変えた人。承認待ちになった変更は、申請が申請した人で、変更が承認した人で残ります）。一時停止・再開、所属組織、公開する組織の範囲の変更は残りません（実行ルール・メンバー・「メールで起動」を画面で変えたときは残ります） |

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

### 書き換えの流れ

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

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

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

```bash
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 は、送り直すともう 1 つ作られます。応答が届かなかったときは、一覧で ID と `createdAt` を見て作られたかを確かめてから送り直し、できてしまった余分なものは消します。コピーする API は、`Idempotency-Key` を付けると、同じキーで送り直しても 1 回目のコピーが返り、もう 1 つは作られません（付けないときは、作る API と同じです）。

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

テナントで定義の変更に承認が要るとき（管理者の設定）、プロジェクト・工程・配置・トリガー・ライブラリの対応づけを変える 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 をコピーすると、中のプレイブック・スキルのうち自分のものでないものは自分のものとして複製され、自分のライブラリに無い入力ファイルは外れます。公開の承認が有効なテナントでは、公開されていないプレイブックと、公開されていないか無効なスキルは複製されずに外れ、応答の `strippedResources` に Agent の名前が入ります（公開されていて有効なスキルは、元のスキルをそのまま指します。[Agent のコピー](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#copy-agent)を参照）。コピーした Agent の `spec` を変えるときは、プレイブックが自分のもの、新しく指すスキルが有効で自分のものか公開されているもの、入力ファイルが自分のものでないと `400` が返ります。すでに指しているスキルが使えなくなっているとき（公開がやめられたときなど）は `400` にならず、そのスキルを外して保存し、外したスキルの ID を応答の `removedSkillIds` で返します。そのスキルを使い続けるときは、自分のものに替えます。
- Agent に付いている入力ファイルは、実行のときにそのまま渡ります。プロジェクトの持ち主のファイルでなくても外れません（持ち主を変更した後も、前の持ち主のファイルは渡ります）。

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

ほかのプロジェクトでも使っている Agent の指示に、このプロジェクトでだけ足すときは、配置の追加の指示（`PATCH …/placements/{placementId}/instruction`）を使います（Agent の指示（goal）の後ろに続けて渡します。Agent 本体は変えません）。足すのではなく、Agent そのもの（指示・ガードレール・スキルなど）をこのプロジェクトでだけ直すための専用の API はありません。新しい Agent を作って置き換えます。

1. 新しい Agent を用意します。

   <!-- -->

   - 元が自分の Agent なら、Agent の取得で読んだ `name`・`description`・`spec` から、Agent を作る API（`POST /v1/agents`）で作ります。自分の Agent はコピーできません（`409 Conflict`、`already_owned`）。
   - 元がほかの利用者の公開されている Agent なら、コピーします（`POST /v1/agents/:agentId/copy`）。

2. 新しい Agent を直します（`PATCH /v1/agents/:agentId`）。

3. 動いているワークフローの実行が無いときに行います（ワークフローの実行の一覧を `limit=100` で取得し、`status` が `"running"`・`"waiting_gate"` のものが無いことを確かめます）。元の Agent と新しい Agent の両方が動かないようにしたいときは、プロジェクトを一時停止します（`PATCH /v1/projects/{projectId}` で `status` を `"paused"`）。一時停止で止まるもの・止まらないものは、[プロジェクト](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#projects)のプロジェクトを変える API の説明を参照してください。

4. 新しい Agent を、元の配置と同じ担当工程で置きます（`POST /v1/projects/{projectId}/placements`）。

5. 元の配置の記憶と追加の指示を、新しい配置に設定します（`PATCH …/placements/{placementId}/memory`・`PATCH …/placements/{placementId}/instruction`）。cycle では、巡回も設定します（`PATCH …/placements/{placementId}/schedule`）。

6. 元の配置を起動先にしている Webhook のトリガーは、トリガーを変える API（`PATCH /v1/projects/{projectId}/triggers/{triggerId}` に `placementId`・`stepId`）で新しい配置に付け替えます。Webhook のトリガーの起動先は、プロジェクトの取得の `triggers[].placementId` で分かります。「メールで起動」は、画面で新しい配置に付け替えます（起動先も画面で確かめます）。

7. 元の配置を外します（`DELETE /v1/projects/{projectId}/placements/{placementId}`）。

8. 一時停止したときは、プロジェクトを再開します（`status` を `"active"`）。

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

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

### スキルを直す

- 文書（`.md`・`.json`・`.yaml`・`.yml`）は、スキルの文書を書き換える API（`PATCH /v1/skills/:skillId/files`）で直せます。ファイルの一覧の取得（`GET /v1/skills/:skillId/files`。`version_id` を省いて読みます）で受け取った `digest` を `baseDigest` として付けて送ります。付けないと `400`、取得の後にスキルが変わっていると `409 Conflict`（`stale_base`）が返ります。
- スクリプトや実行ファイルを含むスキルは、文書も含めて、ファイルを丸ごと入れ替える API（`PUT /v1/skills/:skillId/files`）で直します。今のバージョンをダウンロード（`GET /v1/skills/:skillId/download`）して手元で直し、丸ごと送ります。設定値のファイルなど、文書ではないファイルも、丸ごと入れ替えて直します。丸ごと入れ替えるときも、ファイルの一覧の取得で受け取った `digest` を `baseDigest` として付けます（取得の後にスキルが変わっていると `409 Conflict`（`stale_base`））。
- 前のバージョンのファイルをすべて取り出したいときは、バージョンを指定してスキルをコピーし（`POST /v1/skills/:skillId/copy`）、コピーしたスキルをダウンロードします。
- 機密（設定値のファイルなど）を含むスキルは公開しないでください。公開すると、ほかの利用者もすべてのファイルを読めます。新しいバージョンで機密を消しても、前のバージョンを指定したコピーで取り出せます。

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

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

   <!-- -->

   - workflow は、ワークフローの実行を始め（`POST /v1/projects/{projectId}/runs`。`Idempotency-Key` ヘッダーが要ります）、ワークフローの実行の取得（`GET /v1/projects/{projectId}/runs/{runId}`）で進み具合を見ます。終わりを待つときは、`status` が `"closed_done"`・`"closed_rejected"`・`"closed_failed"`・`"cancelled"` のどれかになったところで止めます。閉じた実行の再開はオーナーか運用担当（組織の運用の役割の人を含む）の操作でしか起きず、自動では起きないので、`"closed_rejected"`・`"closed_failed"` の後に再開まで追うときは、期限を決めて取得し直すか、記録 (証跡) の `run.resumed` を見ます。
   - cycle は、Webhook のトリガーを発火し（`POST /v1/projects/{projectId}/triggers/{triggerId}/fire`。本文に、発火ごとに一意な `eventId` が要ります。同じ発火を送り直すときは同じ値を使います）、[発火で動いた実行の見分け方](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#triggers-find-execution)の手順で実行を見つけます。

2. 新しい実行の結果を、直す前の実行と比べます。スキルを直したときは、実行の結果の `usedSettings` で、新しいバージョンが配られたかを確かめます（公開の承認が有効なテナントで公開中のスキルは、承認されるまで新しいバージョンは配られません）。バージョンを固定している Agent は新しいバージョンに変わらないので、Agent の `spec.skills` の `versionId` を新しいバージョンに替えます。

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

ライブラリ（Agent・プレイブック・スキル）の変更と、この API での一時停止・再開・所属組織・公開する組織の範囲の変更は、記録 (証跡) に残りません。何をいつ変えたかは、呼ぶ側で控えてください。この API でのそのほかのプロジェクトの変更（配置へのプロジェクトのライブラリの対応づけを含みます）は、記録 (証跡) に残ります（記録者は[直し方を選ぶ](#choose)の表と同じです）。
