call-deployed-crew

デプロイ済みの Crew を呼び出す

独自のコードから CrewAI AMP 上で実行される Crew または flow を呼び出す方法と、呼び出しが正しく機能し続けるように Crew を作成する方法です。

2026-10-01 に crewai 1.15.22 および 1.15.23 で検証済みです。 2026-10-01 に CrewAI AMP と実際の LLM を使ってライブテスト済みです。 まず crewai version を実行してください。メジャーまたはマイナーバージョンが異なる場合は、ask-docs スキルを使ってバージョン依存の項目を再確認してください。

---

1. 契約の概要

各デプロイには固有のベース URL（https://<your-deployment>.crewai.com）とベアラートークンがあり、どちらも AMP ダッシュボードのデプロイページ（Status タブ）に表示されます。crewai deploy status ではどちらも表示されません。すべての呼び出しで Authorization: Bearer <token> を送信します。

呼び出し	本文	成功時のレスポンス（ライブ）	ドキュメント
GET /inputs	-	{"inputs": ["audience", "topic"]}	GET /inputs
POST /kickoff	{"inputs": {"topic": "...", ...}} と省略可能な兄弟フィールド（セクション 4）	{"kickoff_id": "<uuid>"}	POST /kickoff
GET /status/{kickoff_id}	-	実行状態、進捗、結果（セクション 5）	GET /status
POST /resume	セクション 5 を参照してください。本文はデプロイ先で確認してください	{"kickoff_id": "<new uuid>"}	POST /resume

準備状況の確認には GET /inputs を使ってください。GET / は 404 を返す場合があります。

想定されるレスポンス（ドキュメントに記載されたコードも処理してください。API の概要）：

リクエスト	ライブ時のレスポンス
誤ったトークン	401 {"detail":"Invalid or missing authentication credentials"}
Authorization ヘッダーがない	401 {"detail":"Not authenticated"}
Crew のキックオフで必須キーが欠落している場合、{"inputs": {}}、{}、または本文のみ	422 {"detail":"Missing inputs: audience, topic"} - details.missing_inputs ではなく、単なる文字列です
有効な JSON ではない本文	500 Internal Server Error
GET /status/<unknown id>	404 ではなく、"state": "NOT FOUND" を含む 200

export CREWAI_DEPLOYMENT_URL="https://<your-deployment>.crewai.com"
export CREWAI_DEPLOYMENT_TOKEN="<your-bearer-token>"

curl -s -H "Authorization: Bearer $CREWAI_DEPLOYMENT_TOKEN" "$CREWAI_DEPLOYMENT_URL/inputs"

curl -s -X POST "$CREWAI_DEPLOYMENT_URL/kickoff" \
  -H "Authorization: Bearer $CREWAI_DEPLOYMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"topic": "AI agents", "audience": "engineers"}}'

curl -s -H "Authorization: Bearer $CREWAI_DEPLOYMENT_TOKEN" \
  "$CREWAI_DEPLOYMENT_URL/status/<kickoff_id>"

ルール：

• URL とトークンは環境変数またはシークレットストアに保存してください。トークンをハードコードしたり、コミットしたり、Authorization ヘッダーをログに記録したり、ブラウザーに送信したりしないでください。デプロイの呼び出しはバックエンドから行ってください。
• ダッシュボードには、組織レベルの Bearer Token と、より狭い権限を持つ User Bearer Token が表示されます。連携で動作するもののうち、最も権限の狭いトークンを使ってください。

2. 必須入力は {placeholder} トークンから取得します

クルーが必要とするキーは、タスクの description／expected_output およびエージェントの role／goal／backstory に含まれる {name} トークンです。デプロイ済みバージョンのキーは GET /inputs で一覧表示されます。キーは /inputs（またはコード）から取得してください。推測してはいけません。

ローカルでは、Crew.fetch_inputs() が同じフィールドをスキャンします。これは crewai 独自の処理です。

from crewai import Agent, Crew, Task

agent = Agent(role="{topic} researcher", goal="Explain {topic}", backstory="Writes for {audience}.")
task = Task(description="Research {topic} for {audience}.", expected_output="A summary of {topic}.", agent=agent)
print(sorted(Crew(agents=[agent], tasks=[task]).fetch_inputs()))  # ['audience', 'topic']

crewai が受け取った入力をどのように扱うか（1.15.22-1.15.23 でローカルに検証済み）：

送信するもの	起きること
すべてのプレースホルダーキー	最初の LLM 呼び出し前に、値がエージェントとタスクのテキストに代入されます
プレースホルダーキーが不足している場合	ValueError: Missing required template variable 'Template variable 'audience' not found in inputs dictionary' in description が発生します。LLM 呼び出し前に例外が送出されます
プレースホルダーのない余分なキー	暗黙に無視され、プロンプトには渡されません
入力なし、または inputs={}	ローカルではエラーになりません。補間がスキップされ、リテラルテキスト {topic} がモデルに渡されます。デプロイ済みクルーでは 422 で拒否されます（セクション 1）
int／float／bool／list／dict の値	ローカルでもライブデプロイでも str() で文字列化されます（"audience": 3 は AUDIENCE=3 になりました）。API ではすべての入力値が文字列として文書化されています。クルーには文字列を送信してください（フローについては下のセクションを参照）

その結果、次の点に注意してください。

• /kickoff を呼び出す前に、クライアントでリクエストを /inputs に照らして検証し、すべてのキーを送信してください。入力が空の実行でエラーになるとは限りません。AMP ではエラーになりますが、自分で kickoff() を呼び出した場合はエラーになりません。
• プロンプト内の JSON の例（Reply like {"title": "..."}）は補間されませんが、fetch_inputs() は "title": "..." を入力名として報告します。波括弧から導出した入力リストでは、その入力が要求されます。テキスト内に JSON のサンプルを記述するのではなく、出力構造を output_pydantic／response_model に指定してください。
• 日付は ISO 8601 文字列として、構造化された値は JSON 文字列として送信し、クルー内で解析してください。

フローは異なります。 デプロイ済みフローの GET /inputs には、その状態モデルが宣言するフィールドが一覧表示されます。id 自体を宣言したテストモデルでは {"inputs": ["topic", "count", "id", "history"]} となります。id を Flow に任せるモデルでは、id は一覧に表示されません（build-flow スキルを参照）。また、いずれのフィールドも必須ではありません。{"inputs": {}} を指定したフローの kickoff は 200 を返し、デフォルト状態で実行されました。設定するフィールドだけを状態モデルの JSON 型で送信してください（リストはリストとして送信します。"[]" を文字列として送信すると実行が FAILED になりました）。id は決して送信しないでください（セクション 3）。

---

3. kickoff の本文：inputs はラッパーです

誤り	正しい
{"topic": "AI agents", "audience": "engineers"}	{"inputs": {"topic": "AI agents", "audience": "engineers"}}
{"inputs": {"topic": "...", "meta": {...}}}	{"inputs": {"topic": "..."}, "meta": {...}}
{"inputs": {"id": "<previous-kickoff-id>", "topic": "..."}}（フロー、非推奨）	{"inputs": {"topic": "..."}, "restoreFromStateId": "<previous-kickoff-id>"}
読み取りタイムアウト後に POST /kickoff を再試行する	「開始した可能性がある」と考え、別の kickoff を送る前に実行状況を確認します

裸の本文を送信した場合、ライブ環境では次のようになります。クルーは 422 {"detail":"Missing inputs: audience, topic"} を返します（入力を送信しない場合と同じです）。フローは 200 を返し、トップレベルのキーを無視してデフォルト状態で実行されます。値が破棄されたことを示すものはありません。

4. inputs の横にあるオプションフィールド

これらはすべて kickoff リクエスト本文のトップレベルに置き、inputs の中には入れません。

フィールド	目的	ドキュメント
meta	自由形式のメタデータ（{"requestId": "..."}）。タスクと crew の Webhook、および /status の last_executed_task.meta で返されます	POST /kickoff
taskWebhookUrl	各タスクの完了後に POST されます	同上
stepWebhookUrl	各エージェントの思考／アクションの後に呼び出されます	同上
crewWebhookUrl	実行の完了時に POST されます	同上
humanInputWebhookUrl	human_input=True のタスクがレビュー待ちになると POST されます（セクション 5）	HITL Workflows
webhooks	イベントストリーミング：{"events": [...], "url": "...", "realtime": false, "authentication": {"strategy": "bearer", "token": "<your-webhook-secret>"}}	Webhook Streaming
restoreFromStateId	@persist を使用するフロー：以前の実行から状態を復元し、新しい実行を記録します	inputs.id deprecation

ライブテストで受信側に届いた内容：

Webhook	ペイロード	Authorization ヘッダー
taskWebhookUrl	タスクごとに 1 回の POST：name、description、expected_output、agent、output、output_json、summary、kickoff_id、meta	なし
crewWebhookUrl	成功時に 1 回の POST：kickoff_id、meta、result、result_json、token_usage。@before_kickoff で失敗した実行では送信されません	なし
stepWebhookUrl	エージェントにツールがない crew では、何も届きません	-
webhooks（ストリーミング）	{"events": [{id, execution_id, timestamp, type, data}]}。realtime: false では 4 件のイベントが 1 回の POST にまとめられ、realtime: true ではイベントごとに 1 回の POST が送信されました。失敗した実行では crew_kickoff_failed が届きました	Bearer <your-webhook-secret>

• タスク／crew／人間による入力用の Webhook にはシークレットが含まれません。これらは通知として扱い、kickoff_id が発行済みのものと一致するか確認してから、操作を行う前に GET /status で確認してください。
• ストリーミングされたイベントは順不同で届きました（前の task_completed より先に task_started が届きました）。timestamp または data.emission_sequence でソートしてください。execution_id と id の組み合わせで重複を排除してください。ベアラーシークレットがない配信は拒否してください。

/kickoff の応答が返ったらすぐに、kickoff_id を独自のリクエスト ID と一緒に保存してください。これは、その実行を識別する唯一の手段です。

@persist を使用するフローでは、実行の state.id がその kickoff_id になるため、restoreFromStateId には以前の kickoff_id を指定します。ライブテストでは、実行 1 から復元すると、新しい state id のもとで count=2 history=['one','two'] が得られました。不明な ID を指定した場合はエラーなくデフォルト値で実行されました。非推奨の {"inputs": {"id": "<kickoff_id>"}} でも状態は復元されましたが、古い ID のもとに書き戻されました。

---

5. /status/{kickoff_id} のポーリング

稼働中のデプロイでは、Kickoff Crew ガイド の形式が返されます。API リファレンス には別の形式が示されています。どちらも読み取れるクライアントを用意しても、コストはかかりません。

取得元	状態フィールド	値	結果
稼働中（crew と flow）	state。status はメッセージです（"Task is Running"、FAILED の場合は例外テキスト、SUCCESS の場合は null）	確認されている値：PENDING、STARTED、RUNNING、SUCCESS、FAILED、NOT FOUND	result 文字列（完了まで null）、result_json（プレーンテキストの場合は null）
Kickoff Crew ガイド	同上	PAUSED、REVOKED も記載	同上
API リファレンス	status	running、completed、error	result.output、エラーテキストは error

ルール：

1. state を読み取ります。state がない場合に限り、status を代わりに使います。小文字に変換して比較します。
2. 終端状態：成功は success / completed、失敗は failed / error / revoked です。paused は人からのフィードバック待ちです。それ以外はポーリングを続けます。
3. result_json、次に result を読み取ります（文字列、または API リファレンス形式の場合は result.output）。実行が失敗すると result: null になります。理由は status に含まれます（例："ValueError: ..."）。
4. バックオフを使ってポーリングします（約 2 秒から開始し、約 15 秒まで延ばし、ジッターを加えます）。crew の通常の実行時間を基準に、全体の期限を設定します。無制限の while True でポーリングしないでください。
5. 期限に達しても、実行が失敗したわけではありません。kickoff_id とともに期限に達したことを報告し、IDを保持して後で再確認してください。重複してキックオフしないでください。
6. crew は progress.unit: "task" と completed / total を報告します。flow は unit: "step" と total および remaining を null で報告します。completed は件数として表示してください。
7. 不明な ID に対しては、HTTP 200 と state: "NOT FOUND" が返されます（ドキュメントには 404 と記載されています。どちらも処理してください）。IDを発行したデプロイに対してポーリングしていることを確認し、キックオフ直後の数回は許容したうえで、失敗として扱います。人からの入力を待っている crew も NOT FOUND と表示されます（下記参照）。
8. /status が 5xx を返し続ける場合、実行自体が失敗した可能性があります。数回試したらポーリングを止め、期限まで続けるのではなく、デプロイのログを確認してください。

多数の実行が進行中の場合は、頻繁なポーリングよりもウェブフック（セクション 4）を優先してください。

人からの入力と POST /resume — 利用前に検証してください

API 経由で crew の human_input=True を使う場合は、それを前提に構築する前に、自分のデプロイでサイクル全体を検証してください。humanInputWebhookUrl を渡し（実行が待機中であることを示す唯一のシグナルです。本文には execution_id と UUID の task_id が含まれます）、待機中に /status が返す NOT FOUND と PAUSED の両方を処理し、デプロイが受け付けるフィールドの大文字・小文字の形式（executionId/taskId または snake_case）を確認し、再開した実行が SUCCESS に到達することを確かめてください。

新たに作業を始める場合は、@human_feedback を使った Flow を検討してください（Flows における Human Feedback）。ドキュメントによると、ウェブフック URL は /resume に引き継がれません。再度送信してください。

---

6. 最初の呼び出し

最初のリクエストがそれ以降のリクエストと同じ速さで応答する、あるいは最初の試行で 200 が返ると想定しないでください。その前提で設計してください。

• 最初のリクエストには余裕のあるタイムアウト（秒ではなく分単位）を設定し、502 / 503 / 504 が返った場合は、バックオフを使って再試行し、Retry-After に従ってください。
• 最初のリクエストは GET /inputs にします。読み取り専用なので、いつでも安全に再試行でき、いずれにせよキーの一覧が必要です。
• POST /kickoff を再試行するのは、リクエストがサーバーに到達していないことが確実な場合（接続拒否 / DNS）、または 503 が返った場合に限ります。読み取りタイムアウト、502、504 の場合は実行が開始されている可能性があります。別のキックオフを送信する前に、実行の有無を確認してください。

実稼働テストでは、各デプロイに Online が表示された直後でも、GET /inputs は約 0.1〜0.25 秒で 200 を返し、5xx は確認されませんでした。これは一例であり、保証ではありません。引き続き防御的な設定を維持してください。

---

7. 小さな Python クライアント

完全なクライアント（httpx、約 200 行）はreferences/python-client.mdにあります。セクション 2～6 の内容を実装しています。/inputs に照らして入力を検証し、{"inputs": ...} でラップし、値を文字列化し、安全な処理のみを再試行します。また、期限内でバックオフしながらポーリングし、kickoff_id を含む RunFailed／RunPaused／RunTimeout を発生させます。

import os
from deployed_crew_client import DeployedCrew, RunTimeout

crew = DeployedCrew(os.environ["CREWAI_DEPLOYMENT_URL"], os.environ["CREWAI_DEPLOYMENT_TOKEN"])
try:
    result = crew.run({"topic": "AI agents", "audience": "engineers"}, deadline_s=900)
except RunTimeout as e:
    print("still running, check later:", e.kickoff_id)
finally:
    crew.close()

フローでは、crew.run(inputs, flow=True) を呼び出します。フローの /inputs には省略可能な状態フィールドが記載されており、その値は JSON 型を維持する必要があります（セクション 2）。これらはすべて、2026-10-01 に稼働中のデプロイで実行されました。成功、実行時の例外テキストを伴う RunFailed、クライアント側の MissingInputsError、サーバーの 422、メッセージにトークンを含まない 401 を確認しています。

期限を設けた curl のポーリングループも、同じリファレンスにあります。

---

8. 繰り返し呼び出しや同時呼び出しでも正しく動作する Crew を作成する

デプロイ環境では、多数のキックオフが実行されます。それぞれのキックオフで新しい Python オブジェクトが使われるとは限りません。モジュールのグローバル変数、クラス属性、ツールのインスタンス、インポート時にキャッシュされたものは実行後も残り、次の実行から参照できる場合や、同時に実行中のものから参照できる場合があります。最初の 3 行の内容は、1.15.22-1.15.23 でローカルに再現しました（references/concurrency-safe-crews.mdを参照）。

避けること	理由	代わりにすること
実行時に、たとえば @before_kickoff で task.description（またはエージェントの role／goal／backstory）を書き換える	crewai は最初に取得したテキストをテンプレートとして保持し、そこから再度補間します。同じ crew オブジェクトで 2 回実行すると、2 回目のプロンプトに 1 回目の顧客情報が含まれ、2 回目自身の顧客情報は含まれません	実行ごとの値は {placeholders} に入れて inputs として渡します。@before_kickoff では inputs を追加または正規化し、返すことができます
実行ごとのデータをツールのインスタンスに保持する（self.seen、self.customer など）	crew.copy()（kickoff_for_each で使用）は同じツールオブジェクトを再利用するため、2 回目の実行から 1 回目のデータが見えてしまいます	ツールはステートレスにします。実行ごとの値はツールの引数として渡すか、@before_kickoff で設定した contextvars.ContextVar から読み取ります
1 つの Crew オブジェクトで 2 つのキックオフを同時に実行する	akickoff() の呼び出しが重なると、2 回目は RuntimeError: Executor is already running. Cannot invoke the same executor instance concurrently. を発生させました。kickoff_async() の呼び出しが重なった場合は、実行によって発生することも、しないこともありました。	Crew を自分でホストする場合は、リクエストごとに新しい crew を作成します。ResearchCrew().crew().kickoff(inputs=...)
結果、クォータ、「処理済み」フラグをメモリやローカルディスクに保存する	再起動すると失われ、ワーカー間で共有されません	自分で管理するストレージ（データベース、オブジェクトストア）を使い、ID を inputs として渡します
デプロイされた crew で input() を呼び出す	ターミナルで応答する人がいないため、実行を完了できません	@human_feedback を使う Flow を使うか、動作を確認したうえで human_input=True と POST /resume を使います（セクション 5）

実稼働環境でのテストでは、デプロイ済みの 1 つの crew に 8 件のキックオフを同時に実行したところ、それぞれの出力と last_executed_task に個別の inputs が返され、相互に混ざることはありませんでした。これは、プラットフォームがそれらの実行を混同しなかったことを示していますが、上記のパターンが安全になるわけではありません。引き続き避けてください。

大きな入力（大きなファイル、大規模なデータフレーム、大きなナレッジベース）はすべて読み込むのではなく、ストリームまたはチャンクに分けて処理します。また、デプロイ前にローカルでピークメモリを測定します。

同時実行する場合も、外部の共有制限は引き続き適用されます。1 分あたりの API 制限を守るには待機し、日次クォータを共有ストレージでロックを使って確保してください。

---

9. よくある間違い

症状	原因	対処方法
Crew：すべての呼び出しで 422 {"detail":"Missing inputs: audience, topic"} が返る	リクエストボディが {"topic": ...} で、inputs のラッパーがない	{"inputs": {...}} を送信します
Flow が送信した値を無視し、デフォルト値で実行される	同じくラッパーのないリクエストボディです。Flow はこれを受け付け、200 を返します	{"inputs": {...}} を送信します
422 にキーが1つ表示される	エージェントまたはタスクのテキストにある {placeholder} に対応する入力がありません	GET /inputs のすべてのキーを送信します。タイプミスや余分な波括弧がないか確認します
クライアントが Flow の開始を拒否し、count、history などがないと表示される	Flow の /inputs には、必須ではない宣言済みの状態フィールドがすべて列挙されています	Flow では /inputs の適用を強制しないでください。id は決して送信しないでください
開始時に 500 Internal Server Error が返る	リクエストボディが有効な JSON ではありません	文字列の連結ではなく、JSON ライブラリまたは jq を使ってリクエストボディを作成します
ローカル環境で Missing required template variable '...' in description が表示される	上記と同じ原因で、LLM の呼び出し前に crewai がエラーを発生させています	同上
出力に {topic} がそのまま表示される	入力なし、または空の入力で開始したため、補間がスキップされました。エラーは発生しません	クライアント側で入力を検証します。プレースホルダーを含む Crew に {} を送信しないでください
/inputs に "title": "..." のようなキーが表示される	プロンプト内の JSON サンプルがプレースホルダーとして読み込まれています	プロンプトから JSON サンプルを削除し、output_pydantic／response_model を使います
401 が返る	トークンが間違っているか、別のデプロイメントのトークンです	このデプロイメントの Status タブからトークンをコピーします
ポーリングループが終わらない	API が SUCCESS を返しているのに、完全一致の文字列（"completed"）を待っているか、期限が設定されていません	小文字に変換し、両方の表記を受け入れ、期限を設定します
ポーリングのたびに "state": "NOT FOUND" と表示される	その ID に対してデプロイメント URL が間違っているか、人間からの入力を待っている Crew です	URL を確認します。HITL についてはセクション 5 を参照してください
GET / が 404 を返す	実行中のデプロイメントにルートがありません	ヘルスチェックには GET /inputs を使います
結果が空／None になる	状態が終端状態になる前に result を読み取っているか、result_json を無視しています	成功状態になった後にのみ結果を読み取ります。最初に result_json を確認します
実行が重複する	読み取りタイムアウト、502、または 504 の後に POST /kickoff が再試行されています	接続エラーと 503 の場合にのみ POST /kickoff を再試行します
最初の呼び出しはタイムアウトするが、次の呼び出しは成功する	時間のかかる初回応答に対してクライアントのタイムアウトが短すぎます	初回呼び出しのタイムアウトを長くし、Retry-After に従って再試行します。まず GET /inputs を呼び出します
実行中のプロンプトに別の実行の顧客やトピックが表示される	実行ごとのデータがタスクテキスト、ツールのインスタンス、またはグローバル変数に書き込まれています	セクション 8
Webhook イベントが順不同で届く	HTTP 配信には順序が保証されません	timestamp または data.emission_sequence で並べ替えます
/resume が 422 を返し、"executionId ... Field required" と表示される	フィールドの大文字・小文字がリファレンスページと異なります	セクション 5 を参照し、まず一時停止／再開の一連の処理をテストしてください

---

10. チェックリスト

• ベース URL とトークンは環境変数／シークレットストアから取得します。トークンがログやブラウザーに渡ることはありません
• クライアントは最初に GET /inputs を呼び出し、キーが不足している Crew（Flow ではない）の開始を拒否します
• 開始時のリクエストボディは、文字列値を含む {"inputs": {...}} です。meta、Webhook フィールド、restoreFromStateId は inputs と同じ階層に配置します
• Webhook の受信側は、ベアラーシークレットを検証する（ストリーミングの場合）か、/status で kickoff_id を確認します（タスク／Crew の Webhook にはシークレットがありません）
• kickoff_id は、リクエスト ID とともに直ちに保存されます
• ポーリングでは小文字に変換した state、次に status を読み取り、成功／失敗／一時停止／NOT FOUND／連続する 5xx を処理し、バックオフと全体の期限を適用します
• 期限に達した場合は、新しい開始として再試行せず、kickoff_id とともに報告します
• 初回リクエストには長いタイムアウトを設定し、Retry-After に従って 502／503／504 を再試行します
• 実行時にタスクやエージェントのテキストへ書き込みません。実行ごとのデータは入力を通じて渡します
• ツールやモジュールのグローバル変数に、実行ごとの状態を保持しません
• 大きな入力はストリーミングまたはチャンク化して処理し、デプロイ前にローカル環境でピークメモリを測定します

---

参考資料

• Python クライアント - 完全版の httpx クライアント、使用方法、期限付きの curl ポーリングループ
• API コントラクト - すべてのエンドポイント、フィールド、状態、エラーと、各項目の公開ドキュメントへのリンク
• 並行処理に安全なクルー - ローカルで再現した共有状態に関する問題と、それらを回避するパターン

関連スキル：

• deploy-to-amp - まずプロジェクトを AMP にデプロイする方法
• build-flow - @persist、restore_from_state_id、@human_feedback
• design-task - {placeholders} を含むタスクテキストの作成
• test-crewai-project - スタブ LLM を使ってクルーをオフラインで実行し、入力とプロンプトをテストする方法
• ask-docs - ここに記載されたフィールドが古くなっているように見える場合に、最新のドキュメントを検索する