call-deployed-crew

Call a Deployed Crew

How to call a crew or flow that runs on CrewAI AMP from your own code, and how to write the crew so those calls stay correct.

Verified against crewai 1.15.22 and 1.15.23 on 2026-10-01. Live-tested on CrewAI AMP and real LLMs on 2026-10-01. Run crewai version first; if the major/minor differs, re-check the version-sensitive rows with the ask-docs skill.

1. The contract on one screen

Every deployment has its own base URL (https://<your-deployment>.crewai.com) and bearer token, both shown on the deployment's page in the AMP dashboard (Status tab). crewai deploy status prints neither. All calls send Authorization: Bearer <token>.

Use GET /inputs as the readiness check; GET / may return 404.

Responses to expect (handle the documented codes too - API introduction):

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

Rules:

• Keep the URL and token in environment variables or a secret store. Never hard-code the token, commit it, log the Authorization header, or ship it to a browser - call the deployment from your backend.
• The dashboard shows an organization-level Bearer Token and a User Bearer Token with narrower permissions. Use the narrowest one that works for the integration.

2. Required inputs come from {placeholder} tokens

The keys a crew needs are the {name} tokens in its task description / expected_output and its agent role / goal / backstory. GET /inputs lists them for the deployed version. Read the keys from /inputs (or from your code) - never guess them.

Locally, Crew.fetch_inputs() is crewai's own scan of the same fields:

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']

What crewai does with the inputs it receives (verified locally on 1.15.22-1.15.23):

Consequences:

• Validate the request against /inputs in your client before calling /kickoff, and send every key. Do not rely on an empty-inputs run failing loudly - it does on AMP, not when you call kickoff() yourself.
• A literal JSON example inside a prompt (Reply like {"title": "..."}) is not interpolated, but fetch_inputs() reports "title": "..." as an input name. Any input list derived from braces will ask for it. Put output structure in output_pydantic / response_model instead of a JSON sample in the text.
• Send dates as ISO 8601 strings and structured values as JSON strings, and parse them inside the crew.

Flows are different. A deployed flow's GET /inputs lists the fields its state model declares - {"inputs": ["topic", "count", "id", "history"]} for a test model that declared id itself; a model that leaves id to the Flow does not list it (see the build-flow skill) - and none of them is required: a flow kickoff with {"inputs": {}} returned 200 and ran on default state. Send only the fields you mean to set, with the JSON types of the state model (a list as a list - "[]" as a string made the run FAILED), and never send id (section 3).

3. The kickoff body: inputs is a wrapper

What a bare body does, live: a crew answers 422 {"detail":"Missing inputs: audience, topic"} (the same as sending no inputs). A flow answers 200, ignores the top-level keys and runs on default state - nothing tells you the values were dropped.

4. Optional fields beside inputs

All of these sit at the top level of the kickoff body, never inside inputs:

What arrived at a receiver in a live test:

• The task / crew / human-input webhooks carry no secret. Treat them as a hint: match the kickoff_id against ones you issued, then confirm with GET /status before acting.
• Streamed events arrived out of order (a task_started before the previous task_completed). Sort by timestamp or data.emission_sequence. Deduplicate on execution_id + id. Reject deliveries without your bearer secret.

Store the kickoff_id with your own request id as soon as /kickoff returns. It is the only handle you have on that run.

For a flow with @persist, the run's state.id is its kickoff_id, so restoreFromStateId takes a previous kickoff_id. Live: restoring from run 1 gave count=2 history=['one','two'] under a new state id; an unknown id ran from defaults with no error. The deprecated {"inputs": {"id": "<kickoff_id>"}} also restored the state but wrote it back under the old id.

5. Polling /status/{kickoff_id}

Live deployments return the Kickoff Crew guide shape. The API reference shows another shape; a client that reads both costs nothing:

Rules:

1. Read state; fall back to status only when state is absent. Compare lower-cased.
2. Terminal: success = success / completed; failure = failed / error / revoked; paused = waiting for human feedback. Anything else means keep polling.
3. Read result_json, then result (string, or result.output in the reference shape). A failed run has result: null; the reason is in status (for example "ValueError: ...").
4. Poll with backoff (start around 2 s, grow to about 15 s, add jitter) under an overall deadline you choose from the crew's normal run time. Never poll in an unbounded while True.
5. A deadline is not a failure of the run. Report it with the kickoff_id, keep the id, and check again later - do not kick off a duplicate.
6. Crews report progress.unit: "task" with completed / total. Flows report unit: "step" with total and remaining null; show completed as a count.
7. An unknown id comes back as HTTP 200 with state: "NOT FOUND" (the docs say 404; handle both). Check you are polling the deployment that issued the id; tolerate a few right after kickoff, then fail. A crew waiting for human input also reads NOT FOUND (below).
8. If /status keeps answering 5xx, the run itself may have failed: stop after a few tries and check the deployment's logs instead of polling to the deadline.

Prefer webhooks (section 4) over tight polling when many runs are in flight.

Human input and POST /resume - verify before relying on it

Before building on crew human_input=True over the API, verify the whole cycle on your own deployment: pass humanInputWebhookUrl (it is the only signal that a run is waiting; its body carries execution_id and a UUID task_id), handle NOT FOUND as well as PAUSED from /status while waiting, check which field casing (executionId/taskId or snake_case) your deployment accepts, and confirm the resumed run reaches SUCCESS.

For new work, consider a Flow with @human_feedback (Human Feedback in Flows). The docs say webhook URLs are not carried over to /resume; send them again.

6. The first call

Do not assume the first request answers as fast as the rest, or that it answers 200 on the first try. Design for it:

• Give the first request a generous timeout (minutes, not seconds) and retry 502 / 503 / 504 with backoff, honoring Retry-After.
• Make that first request GET /inputs: it is read-only, so retrying it is always safe, and you need its key list anyway.
• Retry POST /kickoff only when the request provably never reached the server (connection refused / DNS) or got a 503. A read timeout, 502 or 504 may mean the run started: look for it before sending another kickoff.

In the live tests, GET /inputs answered 200 in about 0.1-0.25 s right after each deployment showed Online, and no 5xx was seen. That is one sample, not a promise - keep the defensive settings.

7. A small Python client

The full client (httpx, about 200 lines) is in references/python-client.md. It does sections 2-6: validates inputs against /inputs, wraps them in {"inputs": ...}, stringifies values, retries only what is safe, polls with backoff under a deadline, and raises RunFailed / RunPaused / RunTimeout carrying the kickoff_id.

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()

For a flow, call crew.run(inputs, flow=True): its /inputs lists optional state fields, and its values must keep their JSON types (section 2). All of this was run against live deployments on 2026-10-01: success, RunFailed with the run's exception text, client-side MissingInputsError, server 422, 401 without the token in the message.

A curl polling loop with a deadline is in the same reference.

8. Write the crew so repeated and concurrent calls stay correct

Your deployment serves many kickoffs. Do not assume each one gets fresh Python objects: module globals, class attributes, tool instances and anything cached at import time can outlive a run and be visible to the next run, or to one running at the same time. The first three rows were reproduced locally on 1.15.22-1.15.23 (see references/concurrency-safe-crews.md).

In a live test, 8 concurrent kickoffs to one deployed crew each returned their own inputs in the output and in last_executed_task, with no cross-over. That shows the platform did not mix those runs; it does not make the patterns above safe - keep them.

Stream or chunk large inputs (large files, big dataframes, large knowledge bases) instead of loading them whole, and measure peak memory locally before deploying.

Shared external limits still apply across concurrent runs: enforce per-minute API limits by waiting, and claim any daily quota in shared storage under a lock.

9. Common mistakes

10. Checklist

• [ ] Base URL and token come from env vars / a secret store; the token never reaches logs or a browser
• [ ] Client calls GET /inputs first and refuses to kick off a crew with a missing key (not a flow)
• [ ] Kickoff body is {"inputs": {...}} with string values; meta, webhook fields and restoreFromStateId sit beside inputs
• [ ] Webhook receivers check the bearer secret (streaming) or confirm the kickoff_id with /status (task / crew webhooks carry no secret)
• [ ] kickoff_id is stored with your request id immediately
• [ ] Polling reads state then status, lower-cased, handles success / failure / paused / NOT FOUND / repeated 5xx, uses backoff and an overall deadline
• [ ] A deadline is reported with the kickoff_id, not retried as a new kickoff
• [ ] First request has a long timeout and retries 502/503/504 honoring Retry-After
• [ ] No runtime writes to task or agent text; per-run data flows through inputs
• [ ] Tools and module globals hold no per-run state
• [ ] Large inputs are streamed or chunked, and peak memory was measured locally before deploying

References

• Python client - the full httpx client, usage, and a curl polling loop with a deadline
• API contract - every endpoint, field, state and error with its public doc link
• Concurrency-safe crews - the shared-state failures reproduced locally and the patterns that avoid them

For related skills:

• deploy-to-amp - getting the project onto AMP in the first place
• build-flow - @persist, restore_from_state_id, @human_feedback
• design-task - writing task text with {placeholders}
• test-crewai-project - running crews offline with a stub LLM to test inputs and prompts
• ask-docs - query the live docs when a field here looks out of date