プロジェクト API ガイド
プロジェクトの API を組み合わせて、うまくいかなかった実行を見つけ、原因を調べ、工程と配置を直して、直ったかを確かめる流れを説明します。各 API の項目・エラーは、ユーザー API リファレンス(プロジェクト)を参照してください。
始める前に
トークン
この流れは、アプリケーション(外部ツールでのログイン)のトークンで行います。システム連携のトークンで呼べるプロジェクトの API は、プロジェクト一覧の取得・ワークフローの実行の開始と取得・トリガーの発火だけで、実行の結果や成果物は読めません。
- 呼べるかどうかは、トークンの利用者のプロジェクトでの役割で決まります。読むのはメンバー、プロジェクトを変える・実行を始める・発火するのはオーナー、確認依頼を判断するのは確認担当者です(呼べる人と 404・403)。
- 長い作業の途中でアクセストークンの期限が切れたら、リフレッシュトークンで更新します(認証ガイド — Authorization Code フロー)。
- マーケットプレイス版ではスコープによる制限はありません。
1. うまくいかなかった実行を見つける
- KPI(
GET /v1/projects/{projectId}/kpi)で、Agent の完遂率と結果ごとの数を見て、増えた失敗の当たりを付けます。期間は直近 7・30・90 日から選びます。 - 実行履歴(
GET /v1/projects/{projectId}/executions)をoutcome=problemsと期間(from・to)で絞って、うまくいかなかった実行を並べます。結果が記録されていない実行はoutcome=missingで並べます。結果の理由(reasonCode)で絞るときは、reason_codeを付けます(値は大文字と小文字を区別します)。 - 必要なら、記録 (証跡)(
GET /v1/projects/{projectId}/audit)で、確認の決定やメンバーの変更を見ます。
curl
curl "https://<your-domain>/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。中身は登録 Agent が報告したものです |
| どのツールを呼び、成功したか・止められたか・何秒かかったか | ツールの呼び出しの一覧(…/executions/{executionId}/operations)。cursor で最後まで読みます |
| 依頼の内容、入口のガードレールで止められたか、Agent からの質問 | 実行の時系列(…/executions/{executionId}/timeline) |
| ワークフローの実行を始めたときの工程・配置・連携先 | ワークフローの実行の設定(GET /v1/projects/{projectId}/runs/{runId}/config)。cycle には無いので、今の値をプロジェクトの取得で読みます |
| 今の工程・配置 | プロジェクトの取得(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。実行の会話) |
- ツールに渡した引数と返ってきた中身は、記録されていないので読めません。
- cycle では、実行のときに使った工程・配置・連携先は残りません。今の値と比べるしかありません。
3. 工程と配置を直す
直せるもの
| 直すもの | 直し方 |
|---|---|
| 登録 Agent の中の動き(何をするか・どう答えるか) | プロジェクトの API では直せません。登録 Agent を作った開発者が直し、管理者が登録し直します(開発) |
| 工程(名前・説明・確認工程の設定・差し戻し先・工程の時刻) | 工程を変える API(PATCH /v1/projects/{projectId}/steps/{stepId}) |
| 工程の並び・数 | 工程を足す・並べ替える・消す API |
| 工程に置く登録 Agent | 下の登録 Agent を入れ替える |
| 配置の担当工程 | 配置の担当工程を変える API(PUT …/placements/{placementId}/steps) |
| cycle の巡回 | 巡回を変える API(PATCH …/placements/{placementId}/schedule) |
書き換えの流れ
既にあるものを変える API は、次の流れで呼びます(書き換えと送り直し)。
- 取得して、応答の
digestを控えます。どの取得のdigestを使うかは、変える API の説明にあります(例: 工程は、プロジェクトの取得の工程のdigest)。 - 変える API に、その値を
baseDigestとして送ります。送った項目だけが変わります。ただし、工程の並びと配置の担当工程は、送ったもので置き換わります。 409 Conflict(stale_base)が返ったら、取得した後にほかの変更が入っています。取得し直して、変える内容を見直してから送り直します。- 続けて同じものを変えるときは、応答の
digestを使えます。
ほぼ同時に届いた 2 つの書き換えは、両方が通ることがあります。同じものを複数の所から変えないようにしてください。
curl
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 つ作られます。応答が届かなかったときは、取得で作られたかを確かめてから送り直し、できてしまった余分なものは消します。
登録 Agent を入れ替える
工程に置いた登録 Agent を別の登録 Agent に替える専用の API はありません。新しい配置を置いてから、元の配置を外します。
- 置ける登録 Agent を、置ける Agent の候補の取得(
GET /v1/projects/agent-candidates?project_type=workflow。cycle はproject_type=cycle)で探します。workflow のプロジェクトに置けるのは、certifiedが true の登録 Agent だけです。 - 動いているワークフローの実行が無いときに行います(ワークフローの実行の一覧を
limit=100で取得し、statusが"running"・"waiting_gate"のものが無いことを確かめます)。元の Agent と新しい Agent の両方が動かないようにしたいときは、プロジェクトを一時停止します(PATCH /v1/projects/{projectId}でstatusを"paused")。 - 新しい登録 Agent を、元の配置と同じ担当工程で置きます(
POST /v1/projects/{projectId}/placementsにmarketplaceAgentIdとstepIds)。cycle では、巡回も設定します(PATCH …/placements/{placementId}/schedule)。 - 元の配置を起動先にしている Webhook のトリガーは、画面で新しい配置に付け替えます。外部 API ではトリガーを変えられません。Webhook のトリガーの起動先は、プロジェクトの取得の
triggers[].placementIdで分かります。 - 元の配置を外します(
DELETE /v1/projects/{projectId}/placements/{placementId})。 - 一時停止したときは、プロジェクトを再開します(
statusを"active")。
- 配置の ID が変わります。過去の実行は、元の配置の ID のまま残ります。
- 一時停止しても、動いている実行は止まりません。実行履歴を
outcome=runningで絞って、終わってから置き換えます。 - 一時停止中のプロジェクトでは、途中のワークフローの実行は次の工程に進まず、再開するまで終わりません。一時停止する前に、動いているワークフローの実行を終わらせます。
- ワークフローの実行の一覧に出るのは、新しい方から 100 件までです。それより古いワークフローの実行が確認待ちのまま残っていても、一覧では見つけられません。
- 同じ工程にほかの登録 Agent も置いているときは、新しい配置は最後に動きます。配置を並べ替える API はありません。
4. 直ったか確かめる
- 直した後に、実行を起こします。
- workflow は、ワークフローの実行を始め(
POST /v1/projects/{projectId}/runs。Idempotency-Keyヘッダーが要ります)、ワークフローの実行の取得(GET /v1/projects/{projectId}/runs/{runId})で進み具合を見ます。終わりを待つときは、statusが"closed_done"・"closed_rejected"・"closed_failed"・"cancelled"のどれかになったところで止めます。工程が作った成果物は、成果物の一覧と中身で確かめます。 - cycle は、Webhook のトリガーを発火し(
POST /v1/projects/{projectId}/triggers/{triggerId}/fire。本文に、発火ごとに一意なeventIdが要ります。同じ発火を送り直すときは同じ値を使います)、発火で動いた実行の見分け方の手順で実行を見つけます。
- workflow は、ワークフローの実行を始め(
- 新しい実行の結果を、直す前の実行と比べます。
- しばらく動かしたら、実行履歴を直した日の前後の期間で絞って比べます。KPI の期間は直近 7・30・90 日だけで、直した日で区切れません。
何をいつ変えたかは、呼ぶ側で控えてください。