{
  "schemaVersion": "1.0",
  "title": "CrewAI run lifecycle and replay capabilities",
  "description": "These six operations start CrewAI work or inspect and control its durable sidecar job. Use one stable AIP Action ID and idempotency key for each start, then target that Action ID from separate status, event, or cancel Actions.",
  "canonical": "https://getaip.org/docs/connectors/crewai/capabilities/run-lifecycle-and-replay",
  "route": "/docs/connectors/crewai/capabilities/run-lifecycle-and-replay",
  "source": "docs/connectors/crewai/capabilities/run-lifecycle-and-replay.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/crewai/capabilities/run-lifecycle-and-replay.md",
    "txt": "/docs/download/connectors/crewai/capabilities/run-lifecycle-and-replay.txt",
    "json": "/docs/download/connectors/crewai/capabilities/run-lifecycle-and-replay.json",
    "pdf": "/docs/download/connectors/crewai/capabilities/run-lifecycle-and-replay.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: CrewAI run lifecycle and replay capabilities\ndescription: >-\n  Use run, status, events, cancel, batch run, and task replay with exact durable\n  identity and cancellation semantics\nkind: capability-reference\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: crewai\ncapabilityIds:\n  - cap:crewai:<crew_id>\n  - cap:crewai:<crew_id>:status\n  - cap:crewai:<crew_id>:events\n  - cap:crewai:<crew_id>:cancel\n  - cap:crewai:<crew_id>:batch_run\n  - cap:crewai:<crew_id>:replay\n---\n\n# CrewAI run lifecycle and replay capabilities\n\nThese six operations start CrewAI work or inspect and control its durable\nsidecar job. Use one stable AIP Action ID and idempotency key for each start,\nthen target that Action ID from separate status, event, or cancel Actions.\n\nTask replay is a new CrewAI execution from a CrewAI task ID. It is not replay\nof an AIP envelope or event cursor.\n\n## Compare the six operations\n\n| Operation | Input focus | Result focus | Stream | Advertised cancel |\n|---|---|---|---:|---:|\n| `run` | Crew kickoff input object | Serialized Crew output | Yes | Yes |\n| `status` | Original run Action ID | Durable job record | No | No |\n| `events` | Original run Action ID and cursor | Ordered journal slice or stream | Yes | No |\n| `cancel` | Original run Action ID and optional reason | Updated durable job record | No | No |\n| `batch_run` | Bounded array of kickoff inputs | Ordered result array and count | Yes | Yes |\n| `replay` | CrewAI task ID and optional inputs | Serialized replay output | Yes | Yes |\n\n`run`, `batch_run`, and `replay` are medium-risk Agent mutations. `cancel` is a\nmedium-risk Tool mutation. `status` and `events` are low-risk Tool reads.\n\n## Preserve the two Action identities\n\nA startable operation uses its own AIP Action ID as the sidecar job ID. The\nsidecar stores that value before scheduling CrewAI work.\n\nControl operations are separate AIP Actions. Their `run_action_id` input names\nthe original job:\n\n```text\nact_run_001       run or batch_run Action and durable sidecar job\nact_status_001    status Action targeting act_run_001\nact_events_001    events Action targeting act_run_001\nact_cancel_001    cancel Action targeting act_run_001\n```\n\nKeep the original ID after a timeout, disconnect, restart, or unknown outcome.\nCreating another start Action changes the durable identity and can duplicate\nmodel or tool effects.\n\n## Run one crew\n\nThe base capability has no `:run` suffix:\n\n```text\ncap:crewai:<crew_id>\n```\n\nIts input is an arbitrary JSON object with at most 512 top-level properties.\nThe encoded input may not exceed 1 MiB.\n\nThe sidecar enforces the byte limit after receiving the request. The pinned\nRust connector has no serialized-request size preflight.\n\n```json\n{\n  \"case_id\": \"CASE-1042\",\n  \"priority\": \"high\",\n  \"facts\": {\n    \"region\": \"emea\"\n  }\n}\n```\n\nThe sidecar creates a fresh Crew instance, enables CrewAI streaming, and calls\n`akickoff(inputs=...)` when available. It falls back to\n`kickoff_async(inputs=...)` at the frozen revision.\n\nThe completed output is a JSON object. The published schema identifies these\nCrewAI fields and permits additional serialized fields:\n\n| Field | Shape |\n|---|---|\n| `raw` | String result |\n| `json_dict` | Object or `null` |\n| `pydantic` | Object or `null` |\n| `tasks_output` | Array of task outputs |\n| `token_usage` | Usage object |\n\nThe sidecar converts other supported CrewAI values into JSON-safe data and\nbounds the complete output to 4 MiB.\n\n## Read durable status\n\nInvoke `cap:crewai:<crew_id>:status` with:\n\n```json\n{\n  \"run_action_id\": \"act_run_001\"\n}\n```\n\nThe identifier must contain 1 through 256 bytes, no control characters, and no\nslash. It must identify a job for the same configured crew.\n\nThe result contains:\n\n```json\n{\n  \"action_id\": \"act_run_001\",\n  \"crew_id\": \"support-primary\",\n  \"operation\": \"run\",\n  \"status\": \"completed\",\n  \"event_count\": 4,\n  \"output\": {}\n}\n```\n\n`status` can be `running`, `completed`, `failed`, or `cancelled`. `output` is\npresent only after successful completion and can otherwise be `null`.\n\nStatus is retry-safe and does not require an idempotency key. It does not prove\nthat every external tool or model effect is reconciled.\n\n## Replay durable events\n\nInvoke `cap:crewai:<crew_id>:events` with the original run ID and an optional\ncursor:\n\n```json\n{\n  \"run_action_id\": \"act_run_001\",\n  \"cursor\": 2\n}\n```\n\nThe published cursor range is `0` through `100000`. The sidecar also requires\nthe cursor to be no greater than the current event count. An omitted cursor\nstarts at zero.\n\nA blocking read returns:\n\n```json\n{\n  \"action_id\": \"act_run_001\",\n  \"cursor\": 2,\n  \"next_cursor\": 4,\n  \"status\": \"completed\",\n  \"events\": [\n    {\n      \"event\": \"chunk\",\n      \"sequence\": 2,\n      \"data\": {}\n    },\n    {\n      \"event\": \"completed\",\n      \"sequence\": 3,\n      \"data\": {}\n    }\n  ]\n}\n```\n\nThe stored sequence is zero-based and monotonic. Persist `next_cursor` only\nafter processing the returned events successfully.\n\nStreaming event replay starts at the supplied provider cursor. The connector\nvalidates every sequence and rebases emitted AIP chunk sequence to zero for the\nnew reader.\n\nCancelling the read detaches that reader. It does not cancel the target job.\n\n## Request cancellation\n\nInvoke `cap:crewai:<crew_id>:cancel` with:\n\n```json\n{\n  \"run_action_id\": \"act_run_001\",\n  \"reason\": \"Operator stopped the governed run\"\n}\n```\n\nThe published schema and sidecar model limit the optional reason to 2,048\ncharacters. The pinned Rust connector forwards the string without its own\ncontrol-character check.\n\nThe cancel Action requires approval and its own idempotency key.\n\nThe reviewed sidecar accepts cancellation for any running job. It closes a\nstreaming result when possible, cancels the asyncio task, records a terminal\n`cancelled` event, and persists the updated record.\n\nA terminal job is returned unchanged. Replay, train, and test run provider\nmethods in worker threads, so cancelling their asyncio task does not stop the\nunderlying call. The durable record can say `cancelled` while that call\ncontinues.\n\nFor a streamed mutation, Rust can return `remote_stop_confirmed: true` after\nthe sidecar route succeeds. Interpret that field as a sidecar acknowledgement,\nnot confirmation from CrewAI or its providers.\n\nThe `cancel` operation itself does not advertise runtime cancellation support.\nIt is one bounded request that targets another job.\n\n## Run a bounded batch\n\nInvoke `cap:crewai:<crew_id>:batch_run` with one through 100 input objects:\n\n```json\n{\n  \"inputs\": [\n    {\n      \"case_id\": \"CASE-1042\"\n    },\n    {\n      \"case_id\": \"CASE-1043\"\n    }\n  ]\n}\n```\n\nEach item has at most 512 top-level properties in the published schema. The\ncomplete encoded operation input still shares the 1 MiB limit.\n\nThe sidecar disables CrewAI streaming for each item. It prefers\n`akickoff_for_each`, falls back to `kickoff_for_each_async`, then runs\n`kickoff_for_each` in a worker thread.\n\nIt records one durable job for the entire batch, not one journal entry per\nitem. Cancellation cannot prove provider stop when the worker-thread fallback\nis active.\n\nThe completed output has this shape:\n\n```json\n{\n  \"results\": [\n    {},\n    {}\n  ],\n  \"count\": 2\n}\n```\n\nOne approval and one idempotency identity cover the complete batch. Review the\nworst permitted item effect before approval.\n\n## Replay from a CrewAI task\n\nInvoke `cap:crewai:<crew_id>:replay` with a CrewAI task ID:\n\n```json\n{\n  \"task_id\": \"task_support_triage\",\n  \"inputs\": {\n    \"case_id\": \"CASE-1042\"\n  }\n}\n```\n\n`task_id` contains 1 through 256 bytes without control characters. `inputs` is\noptional and, when present, must be an object with at most 512 top-level\nproperties in the published schema.\n\nThe sidecar calls `crew.replay(task_id, inputs)` in a worker thread. The\noperation creates a new durable job under the replay Action ID and can produce\nnew model or tool effects.\n\nReplay advertises cancellation support, but its synchronous CrewAI call runs\nin a worker thread. Cancellation ends the waiter and records `cancelled`; it\ndoes not establish provider termination.\n\n## Understand the durable start fence\n\nEvery startable operation requires an idempotency key. The key contains at\nmost 512 bytes and no control characters.\n\nBefore scheduling CrewAI, the sidecar hashes and persists:\n\n- crew ID;\n- Action ID;\n- operation;\n- complete input;\n- optional timeout;\n- idempotency key.\n\nAn exact repeated Action returns the existing job. Reusing the Action ID with\ndifferent material returns a conflict.\n\nThis fence prevents a previously admitted ID from disappearing after an\nexternal effect. It cannot make model, tool, or external-provider behavior\ntransactional.\n\n## Interpret events and terminal outcomes\n\nOne job can record `started`, `chunk`, `completed`, `failed`, or `cancelled`.\nEvery event contains its name, zero-based sequence, and JSON data.\n\nThe connector maps tool-channel chunks to Tool, LLM and message chunks to\nData, other chunks to Progress, completion and cancellation to Done, and\nfailure to Error.\n\nA streaming response must contain a terminal event. Invalid UTF-8, malformed\nJSON, a missing sequence, a gap, an oversized frame, excessive events, an\noversized complete response, or early close fails validation.\n\nAt this revision, the connector checks the accumulated buffer before\nextracting delimited frames. One transport chunk above 1 MiB can therefore be\nrejected even when it contains several individually bounded frames.\n\nIf a streamed mutation fails after admission, the connector attempts sidecar\ncancellation for all five advertised operations. A successful route response\ndoes not prove provider stop for worker-thread execution.\n\n## Apply approval, retry, and recovery rules\n\n| Operation | Approval | Key | Connector retry | Recovery anchor |\n|---|---:|---:|---:|---|\n| `run` | Required | Required | No | Original Action ID, then status and events |\n| `status` | No | Optional | Yes | Repeat the same read |\n| `events` | No | Optional | Yes | Resume from last processed cursor |\n| `cancel` | Required | Required | No | Status and events for target job |\n| `batch_run` | Required | Required | No | Original Action ID, then status and events |\n| `replay` | Required | Required | No | Original replay Action ID, then status and events |\n\nDo not create a replacement mutation because a client timed out. Read the\ndurable job first and reconcile every uncertain external effect.\n\n## Respect bounds and failure decisions\n\n| Boundary | Decision |\n|---|---|\n| Input exceeds 1 MiB | Reduce the complete JSON input before invocation |\n| Key is absent or invalid | Preserve the intent and supply one stable bounded key |\n| Target run is absent | Verify crew, original Action ID, instance, and retained journal |\n| Cursor is beyond event count | Return to the last confirmed cursor |\n| Batch has zero or over 100 items | Split the reviewed intent into bounded batches |\n| Replay task ID is unknown | Correct the CrewAI task identity; do not substitute an AIP Action ID |\n| Thread-backed job reports `cancelled` | Treat provider completion as potentially continuing and reconcile its effects |\n| Journal is full | Archive eligible terminal records only after the retention window |\n| Restored job is failed with uncertain outcome | Reconcile provider state before any new mutation |\n\n## Related documentation\n\n- [CrewAI capability index](README.md)\n- [CrewAI connector overview](../README.md)\n- [CrewAI connector configuration](../reference/configuration.md)\n- [Actions and sessions](../../../concepts/actions-and-sessions.md)\n- [Errors and retry decisions](../../../reference/errors.md)\n",
    "text": "CrewAI run lifecycle and replay capabilities\n\nThese six operations start CrewAI work or inspect and control its durable\nsidecar job. Use one stable AIP Action ID and idempotency key for each start,\nthen target that Action ID from separate status, event, or cancel Actions.\n\nTask replay is a new CrewAI execution from a CrewAI task ID. It is not replay\nof an AIP envelope or event cursor.\n\nCompare the six operations\n\n| Operation | Input focus | Result focus | Stream | Advertised cancel |\n\n| run | Crew kickoff input object | Serialized Crew output | Yes | Yes |\n| status | Original run Action ID | Durable job record | No | No |\n| events | Original run Action ID and cursor | Ordered journal slice or stream | Yes | No |\n| cancel | Original run Action ID and optional reason | Updated durable job record | No | No |\n| batchrun | Bounded array of kickoff inputs | Ordered result array and count | Yes | Yes |\n| replay | CrewAI task ID and optional inputs | Serialized replay output | Yes | Yes |\n\nrun, batchrun, and replay are medium-risk Agent mutations. cancel is a\nmedium-risk Tool mutation. status and events are low-risk Tool reads.\n\nPreserve the two Action identities\n\nA startable operation uses its own AIP Action ID as the sidecar job ID. The\nsidecar stores that value before scheduling CrewAI work.\n\nControl operations are separate AIP Actions. Their runactionid input names\nthe original job:\n\nactrun001       run or batchrun Action and durable sidecar job\nactstatus001    status Action targeting actrun001\nactevents001    events Action targeting actrun001\nactcancel001    cancel Action targeting actrun001\n\nKeep the original ID after a timeout, disconnect, restart, or unknown outcome.\nCreating another start Action changes the durable identity and can duplicate\nmodel or tool effects.\n\nRun one crew\n\nThe base capability has no :run suffix:\n\ncap:crewai:\n\nIts input is an arbitrary JSON object with at most 512 top-level properties.\nThe encoded input may not exceed 1 MiB.\n\nThe sidecar enforces the byte limit after receiving the request. The pinned\nRust connector has no serialized-request size preflight.\n\n{\n  \"caseid\": \"CASE-1042\",\n  \"priority\": \"high\",\n  \"facts\": {\n    \"region\": \"emea\"\n  }\n}\n\nThe sidecar creates a fresh Crew instance, enables CrewAI streaming, and calls\nakickoff(inputs=...) when available. It falls back to\nkickoffasync(inputs=...) at the frozen revision.\n\nThe completed output is a JSON object. The published schema identifies these\nCrewAI fields and permits additional serialized fields:\n\n| Field | Shape |\n\n| raw | String result |\n| jsondict | Object or null |\n| pydantic | Object or null |\n| tasksoutput | Array of task outputs |\n| tokenusage | Usage object |\n\nThe sidecar converts other supported CrewAI values into JSON-safe data and\nbounds the complete output to 4 MiB.\n\nRead durable status\n\nInvoke cap:crewai::status with:\n\n{\n  \"runactionid\": \"actrun001\"\n}\n\nThe identifier must contain 1 through 256 bytes, no control characters, and no\nslash. It must identify a job for the same configured crew.\n\nThe result contains:\n\n{\n  \"actionid\": \"actrun001\",\n  \"crewid\": \"support-primary\",\n  \"operation\": \"run\",\n  \"status\": \"completed\",\n  \"eventcount\": 4,\n  \"output\": {}\n}\n\nstatus can be running, completed, failed, or cancelled. output is\npresent only after successful completion and can otherwise be null.\n\nStatus is retry-safe and does not require an idempotency key. It does not prove\nthat every external tool or model effect is reconciled.\n\nReplay durable events\n\nInvoke cap:crewai::events with the original run ID and an optional\ncursor:\n\n{\n  \"runactionid\": \"actrun001\",\n  \"cursor\": 2\n}\n\nThe published cursor range is 0 through 100000. The sidecar also requires\nthe cursor to be no greater than the current event count. An omitted cursor\nstarts at zero.\n\nA blocking read returns:\n\n{\n  \"actionid\": \"actrun001\",\n  \"cursor\": 2,\n  \"nextcursor\": 4,\n  \"status\": \"completed\",\n  \"events\": [\n    {\n      \"event\": \"chunk\",\n      \"sequence\": 2,\n      \"data\": {}\n    },\n    {\n      \"event\": \"completed\",\n      \"sequence\": 3,\n      \"data\": {}\n    }\n  ]\n}\n\nThe stored sequence is zero-based and monotonic. Persist nextcursor only\nafter processing the returned events successfully.\n\nStreaming event replay starts at the supplied provider cursor. The connector\nvalidates every sequence and rebases emitted AIP chunk sequence to zero for the\nnew reader.\n\nCancelling the read detaches that reader. It does not cancel the target job.\n\nRequest cancellation\n\nInvoke cap:crewai::cancel with:\n\n{\n  \"runactionid\": \"actrun001\",\n  \"reason\": \"Operator stopped the governed run\"\n}\n\nThe published schema and sidecar model limit the optional reason to 2,048\ncharacters. The pinned Rust connector forwards the string without its own\ncontrol-character check.\n\nThe cancel Action requires approval and its own idempotency key.\n\nThe reviewed sidecar accepts cancellation for any running job. It closes a\nstreaming result when possible, cancels the asyncio task, records a terminal\ncancelled event, and persists the updated record.\n\nA terminal job is returned unchanged. Replay, train, and test run provider\nmethods in worker threads, so cancelling their asyncio task does not stop the\nunderlying call. The durable record can say cancelled while that call\ncontinues.\n\nFor a streamed mutation, Rust can return remotestopconfirmed: true after\nthe sidecar route succeeds. Interpret that field as a sidecar acknowledgement,\nnot confirmation from CrewAI or its providers.\n\nThe cancel operation itself does not advertise runtime cancellation support.\nIt is one bounded request that targets another job.\n\nRun a bounded batch\n\nInvoke cap:crewai::batchrun with one through 100 input objects:\n\n{\n  \"inputs\": [\n    {\n      \"caseid\": \"CASE-1042\"\n    },\n    {\n      \"caseid\": \"CASE-1043\"\n    }\n  ]\n}\n\nEach item has at most 512 top-level properties in the published schema. The\ncomplete encoded operation input still shares the 1 MiB limit.\n\nThe sidecar disables CrewAI streaming for each item. It prefers\nakickoffforeach, falls back to kickoffforeachasync, then runs\nkickoffforeach in a worker thread.\n\nIt records one durable job for the entire batch, not one journal entry per\nitem. Cancellation cannot prove provider stop when the worker-thread fallback\nis active.\n\nThe completed output has this shape:\n\n{\n  \"results\": [\n    {},\n    {}\n  ],\n  \"count\": 2\n}\n\nOne approval and one idempotency identity cover the complete batch. Review the\nworst permitted item effect before approval.\n\nReplay from a CrewAI task\n\nInvoke cap:crewai::replay with a CrewAI task ID:\n\n{\n  \"taskid\": \"tasksupporttriage\",\n  \"inputs\": {\n    \"caseid\": \"CASE-1042\"\n  }\n}\n\ntaskid contains 1 through 256 bytes without control characters. inputs is\noptional and, when present, must be an object with at most 512 top-level\nproperties in the published schema.\n\nThe sidecar calls crew.replay(taskid, inputs) in a worker thread. The\noperation creates a new durable job under the replay Action ID and can produce\nnew model or tool effects.\n\nReplay advertises cancellation support, but its synchronous CrewAI call runs\nin a worker thread. Cancellation ends the waiter and records cancelled; it\ndoes not establish provider termination.\n\nUnderstand the durable start fence\n\nEvery startable operation requires an idempotency key. The key contains at\nmost 512 bytes and no control characters.\n\nBefore scheduling CrewAI, the sidecar hashes and persists:\n• crew ID;\n• Action ID;\n• operation;\n• complete input;\n• optional timeout;\n• idempotency key.\n\nAn exact repeated Action returns the existing job. Reusing the Action ID with\ndifferent material returns a conflict.\n\nThis fence prevents a previously admitted ID from disappearing after an\nexternal effect. It cannot make model, tool, or external-provider behavior\ntransactional.\n\nInterpret events and terminal outcomes\n\nOne job can record started, chunk, completed, failed, or cancelled.\nEvery event contains its name, zero-based sequence, and JSON data.\n\nThe connector maps tool-channel chunks to Tool, LLM and message chunks to\nData, other chunks to Progress, completion and cancellation to Done, and\nfailure to Error.\n\nA streaming response must contain a terminal event. Invalid UTF-8, malformed\nJSON, a missing sequence, a gap, an oversized frame, excessive events, an\noversized complete response, or early close fails validation.\n\nAt this revision, the connector checks the accumulated buffer before\nextracting delimited frames. One transport chunk above 1 MiB can therefore be\nrejected even when it contains several individually bounded frames.\n\nIf a streamed mutation fails after admission, the connector attempts sidecar\ncancellation for all five advertised operations. A successful route response\ndoes not prove provider stop for worker-thread execution.\n\nApply approval, retry, and recovery rules\n\n| Operation | Approval | Key | Connector retry | Recovery anchor |\n\n| run | Required | Required | No | Original Action ID, then status and events |\n| status | No | Optional | Yes | Repeat the same read |\n| events | No | Optional | Yes | Resume from last processed cursor |\n| cancel | Required | Required | No | Status and events for target job |\n| batchrun | Required | Required | No | Original Action ID, then status and events |\n| replay | Required | Required | No | Original replay Action ID, then status and events |\n\nDo not create a replacement mutation because a client timed out. Read the\ndurable job first and reconcile every uncertain external effect.\n\nRespect bounds and failure decisions\n\n| Boundary | Decision |\n\n| Input exceeds 1 MiB | Reduce the complete JSON input before invocation |\n| Key is absent or invalid | Preserve the intent and supply one stable bounded key |\n| Target run is absent | Verify crew, original Action ID, instance, and retained journal |\n| Cursor is beyond event count | Return to the last confirmed cursor |\n| Batch has zero or over 100 items | Split the reviewed intent into bounded batches |\n| Replay task ID is unknown | Correct the CrewAI task identity; do not substitute an AIP Action ID |\n| Thread-backed job reports cancelled | Treat provider completion as potentially continuing and reconcile its effects |\n| Journal is full | Archive eligible terminal records only after the retention window |\n| Restored job is failed with uncertain outcome | Reconcile provider state before any new mutation |\n\nRelated documentation\n• CrewAI capability index (README.md)\n• CrewAI connector overview (../README.md)\n• CrewAI connector configuration (../reference/configuration.md)\n• Actions and sessions (../../../concepts/actions-and-sessions.md)\n• Errors and retry decisions (../../../reference/errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "8fc4629c81ff3064a9d7adb85513346d6cfba01d7e0c6fc4c41e403e74ce1075"
  }
}