{ "schemaVersion": "1.0", "title": "CrewAI connector", "description": "The CrewAI connector exposes deployment-admitted crews as governed AIP capabilities. Use it when a tenant must run, observe, cancel, train, test, query, or reset an identified crew through a durable boundary.", "canonical": "https://getaip.org/docs/connectors/crewai", "route": "/docs/connectors/crewai", "source": "docs/connectors/crewai/README.md", "protocol": "Agent Interoperability Protocol", "protocolVersion": "1.0", "section": "Connectors", "documentType": "Connector", "language": "en", "revision": { "lastReviewedRevision": "97be86e9efedf07ecf1783b03800f683f107fb04", "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb", "basis": "frontmatter" }, "downloads": { "md": "/docs/download/connectors/crewai.md", "txt": "/docs/download/connectors/crewai.txt", "json": "/docs/download/connectors/crewai.json", "pdf": "/docs/download/connectors/crewai.pdf" }, "content": { "format": "text/markdown", "markdown": "---\ntitle: CrewAI connector\ndescription: >-\n Decide whether the CrewAI connector fits an integration and understand its\n admitted-crew, sidecar, execution, and durability boundaries\nkind: overview\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: crewai\n---\n\n# CrewAI connector\n\nThe CrewAI connector exposes deployment-admitted crews as governed AIP\ncapabilities. Use it when a tenant must run, observe, cancel, train, test, query,\nor reset an identified crew through a durable boundary.\n\nThe connector is not a generic Python execution gateway. Crew factories,\noperation policy, sidecar identity, credentials, storage, and provider\ndependencies remain deployment-owned.\n\n## Decide whether it fits\n\n| Requirement | Fit |\n|---|---|\n| Run one pre-admitted CrewAI crew | Yes, through its base capability |\n| Observe durable status and replay ordered events | Yes |\n| Run a bounded input batch or replay from a CrewAI task | Yes, when explicitly allowed |\n| Train or test a crew | Yes, under high or medium risk controls |\n| Query crew knowledge without executing the task graph | Yes |\n| Reset an explicit memory domain | Yes, as a high-risk mutation |\n| Load an arbitrary module or select a crew from Action input | No |\n| Request cancellation for every streamed mutation | The contract advertises it, but provider stop is not guaranteed |\n| Share one sidecar journal across active replicas | No |\n| Use AIP transactions, reconciliation, or rollback | No |\n| Prove compatibility with any CrewAI installation | No; claims bind one exact artifact and upstream revision |\n\nChoose another boundary when callers need dynamic code loading, unrestricted\nPython objects, active-active access to one journal, or automatic rollback.\n\n## Understand the two-component boundary\n\nThe production integration has two separately identified components:\n\n1. `aip-host-crewai`, a Rust process that owns AIP identity, admission,\n routing, policy contracts, durable host state, and sidecar authentication;\n2. `aip-crewai-sidecar`, a Python process that loads approved crew factories,\n executes CrewAI, journals jobs, and publishes bounded results and events.\n\nThe Rust host never imports CrewAI. The Python sidecar never accepts a signed\nAIP envelope or chooses tenant routing.\n\n| Boundary | Owner |\n|---|---|\n| Tenant discovery, approval, Action lifecycle, and route | AIP platform |\n| Crew descriptors and advertised operation policy | Rust connector instance |\n| Python registry and crew construction | Sidecar deployment |\n| Model, tool, memory, knowledge, and provider configuration | Deployment-owned crew code |\n| Job journal, event replay, and training artifacts | One sidecar state volume |\n\nThe host and sidecar policies must agree. Health fails when the sidecar omits a\nconfigured crew or an operation admitted by a host descriptor.\n\n## Admit crew identities explicitly\n\nEach Rust descriptor has a stable ID, name, optional description, and explicit\noperation allowlist. IDs must be unique and valid inside an AIP capability ID.\n\nThe sidecar registry uses `module:attribute` syntax. The attribute must be a\nnon-empty mapping or a zero-argument callable returning one.\n\nRegistry values are zero-argument factories or cloneable Crew instances. A\nfresh factory result or deep clone is used for each run to avoid cross-request\nmutation of CrewAI objects.\n\nThe registry can contain additional crews, but every host-admitted crew must be\npresent. A caller cannot choose a Python import path.\n\n## Read capability IDs\n\nThe `run` operation retains the historical base ID. Every other allowed\noperation uses a suffix.\n\n```text\ncap:crewai:\ncap:crewai::status\ncap:crewai::events\ncap:crewai::cancel\ncap:crewai::batch_run\ncap:crewai::replay\ncap:crewai::train\ncap:crewai::test\ncap:crewai::knowledge_query\ncap:crewai::memory_reset\n```\n\nA crew publishes only its allowed operations. Legacy descriptors without an\nallowlist receive `run`, `status`, `events`, and `cancel`.\n\nThere is no universal manifest count. A fully enabled crew publishes ten\ncapabilities; a legacy-policy crew publishes four.\n\n## Compare the ten operations\n\n| Operation | Kind | Risk | Mutation | Streaming | Advertised cancellation |\n|---|---|---|---:|---:|---:|\n| `run` | Agent | Medium | Yes | Yes | Yes |\n| `status` | Tool | Low | No | No | No |\n| `events` | Tool | Low | No | Yes | No |\n| `cancel` | Tool | Medium | Yes | No | No |\n| `batch_run` | Agent | Medium | Yes | Yes | Yes |\n| `replay` | Agent | Medium | Yes | Yes | Yes |\n| `train` | Workflow | High | Yes | Yes | Yes |\n| `test` | Workflow | Medium | Yes | Yes | Yes |\n| `knowledge_query` | Tool | Low | No | No | No |\n| `memory_reset` | Tool | High | Yes | No | No |\n\nThe published contract marks all five streamed mutations as cancellable.\nReplay, training, and testing still execute synchronous CrewAI methods in\nworker threads, so sidecar cancellation does not prove that provider work\nstopped.\n\n## Apply execution controls\n\n| Surface | Approval | Idempotency key | Retry support |\n|---|---|---|---|\n| Mutating operation | Required | Required | None |\n| `knowledge_query` | Not required | Required | Safe |\n| `status` and `events` | Not required | Optional | Safe |\n\n`knowledge_query` is provider-read-only but creates a durable sidecar job.\nThat job boundary requires a key even though the capability is retry-safe.\n\nThe reviewed Rust error mapper nevertheless marks every concrete connector\nfailure `retryable: false`. Treat the contract classification as capability\nmetadata, not permission to retry a failed request automatically.\n\nKeys use tenant scope, input-hash revalidation, and a 24-hour contract TTL.\nMutation approval uses tenant policy and a 15-minute decision TTL.\n\nEvery operation treats data as confidential, PII-bearing, and\nredaction-required. Mutations publish read, write, external-network, and code-\nexecution side effects.\n\nThe connector publishes no transaction, reconciliation, compensation, or\nprovider rollback support.\n\n## Preserve durable job identity\n\nThe sidecar uses the AIP Action ID as its job identity. It hashes crew,\noperation, input, timeout, and idempotency key before scheduling provider work.\n\nReusing an Action ID with matching material returns the existing record.\nReusing it with different material returns a conflict.\n\nThe idempotency fence is persisted before CrewAI starts. A crash can therefore\nleave an uncertain result, but it must not make an admitted Action disappear.\n\nAt restart, any restored `running` job becomes a terminal failed record with\n`uncertain_outcome: true`. The sidecar never silently restarts it.\n\nOnly one active sidecar process may own a journal. The file lock and state\nvolume form a process fence, not a distributed active-active coordinator.\n\n## Treat streams and cancellation precisely\n\nThe connector validates strict event sequence, normalizes sidecar SSE to AIP\nchunks, and requires a terminal `completed`, `cancelled`, or `failed` event.\n\nThe connector bounds each undelimited SSE frame to 1 MiB, the complete response\nto its configured limit, and one stream to 100,000 events.\n\nAll five streamed mutations can call the sidecar cancellation route. Cancelling\nan event replay only detaches the read-only stream.\n\nFor replay, train, and test, the route cancels the asyncio waiter and persists a\nterminal `cancelled` record while the worker thread can continue. The Rust\nconnector may then report `remote_stop_confirmed: true`; this confirms only the\nsidecar response, not provider termination.\n\n## Respect the principal limits\n\n| Boundary | Reviewed value |\n|---|---:|\n| Sidecar-validated operation input | 1 MiB |\n| Sidecar output | 4 MiB |\n| Connector response, default | 64 MiB |\n| Connector response, maximum | 256 MiB |\n| Sidecar event, default | 256 KiB |\n| Sidecar events per run, default | 1,000 |\n| Connector SSE events | 100,000 |\n| Execution timeout, default | 600,000 ms |\n| Execution timeout, maximum | 3,600,000 ms |\n\nThe sidecar also bounds concurrency, retained runs, journal size, checkpoint\nfrequency, query items, batch inputs, and training iterations.\n\n## Bind the compatibility baseline\n\n| Component | Reviewed identity |\n|---|---|\n| AIP source | `97be86e9efedf07ecf1783b03800f683f107fb04` |\n| Connector profile | `aip.connector.crewai.v1` |\n| Sidecar package | `aip-crewai-sidecar` `1.0.0` |\n| Default product sidecar | locked `crewai`, `crewai-cli`, and `crewai-core` `1.15.5` |\n| Optional source-overlay image | CrewAI distribution from source version `1.15.2`, installed without dependencies |\n| CrewAI source | `bfa652a7be8637562cc9b0833f75d927a64552d1` |\n| Python range | `>=3.10,<3.14` |\n\nThe controlled product Compose path builds the default lockfile-only image. A\nseparate `Dockerfile.upstream` first resolves the same lockfile, then reinstalls\nonly the CrewAI distribution from the pinned source tree without dependencies.\n\nThe source-overlay image therefore has a mixed package baseline. Keep default\nand source-overlay image digests distinct; a source commit or package version\nalone cannot identify either artifact.\n\n## Know what is not guaranteed\n\nThe reviewed source does not establish:\n\n- compatibility with arbitrary CrewAI versions, registries, models, or tools;\n- sandboxing of deployment-authored Crew code inside the Python process;\n- exactly-once effects in models, tools, memory, or external systems;\n- cancellation of synchronous replay, training, or evaluation work;\n- active-active sidecars over one journal or training directory;\n- automatic provider-state reconciliation after uncertain failure;\n- production qualification for the current artifact.\n\nCrew factories and their tools can execute deployment-owned code. Isolate the\nsidecar as a privileged workload and grant only intended provider access.\n\n## Choose the next path\n\nUse the concise legacy page for the earlier high-level contract. Read the AIP\nexecution model before integrating Actions, and use the fleet guide for the\nstandalone topology.\n\nImplement retries only after reading the global error rules. The upstream-\nbaseline page explains how framework source identity is bounded.\n\n## Related documentation\n\n- [Legacy CrewAI connector overview](../crewai.md)\n- [How AIP works](../../getting-started/how-aip-works.md)\n- [Deploy the connector fleet](../../guides/deploy-connector-fleet.md)\n- [Errors and retry decisions](../../reference/errors.md)\n- [Connector upstream baselines](../upstream-baselines.md)\n", "text": "CrewAI connector\n\nThe CrewAI connector exposes deployment-admitted crews as governed AIP\ncapabilities. Use it when a tenant must run, observe, cancel, train, test, query,\nor reset an identified crew through a durable boundary.\n\nThe connector is not a generic Python execution gateway. Crew factories,\noperation policy, sidecar identity, credentials, storage, and provider\ndependencies remain deployment-owned.\n\nDecide whether it fits\n\n| Requirement | Fit |\n\n| Run one pre-admitted CrewAI crew | Yes, through its base capability |\n| Observe durable status and replay ordered events | Yes |\n| Run a bounded input batch or replay from a CrewAI task | Yes, when explicitly allowed |\n| Train or test a crew | Yes, under high or medium risk controls |\n| Query crew knowledge without executing the task graph | Yes |\n| Reset an explicit memory domain | Yes, as a high-risk mutation |\n| Load an arbitrary module or select a crew from Action input | No |\n| Request cancellation for every streamed mutation | The contract advertises it, but provider stop is not guaranteed |\n| Share one sidecar journal across active replicas | No |\n| Use AIP transactions, reconciliation, or rollback | No |\n| Prove compatibility with any CrewAI installation | No; claims bind one exact artifact and upstream revision |\n\nChoose another boundary when callers need dynamic code loading, unrestricted\nPython objects, active-active access to one journal, or automatic rollback.\n\nUnderstand the two-component boundary\n\nThe production integration has two separately identified components:\n1. aip-host-crewai, a Rust process that owns AIP identity, admission,\n routing, policy contracts, durable host state, and sidecar authentication;\n2. aip-crewai-sidecar, a Python process that loads approved crew factories,\n executes CrewAI, journals jobs, and publishes bounded results and events.\n\nThe Rust host never imports CrewAI. The Python sidecar never accepts a signed\nAIP envelope or chooses tenant routing.\n\n| Boundary | Owner |\n\n| Tenant discovery, approval, Action lifecycle, and route | AIP platform |\n| Crew descriptors and advertised operation policy | Rust connector instance |\n| Python registry and crew construction | Sidecar deployment |\n| Model, tool, memory, knowledge, and provider configuration | Deployment-owned crew code |\n| Job journal, event replay, and training artifacts | One sidecar state volume |\n\nThe host and sidecar policies must agree. Health fails when the sidecar omits a\nconfigured crew or an operation admitted by a host descriptor.\n\nAdmit crew identities explicitly\n\nEach Rust descriptor has a stable ID, name, optional description, and explicit\noperation allowlist. IDs must be unique and valid inside an AIP capability ID.\n\nThe sidecar registry uses module:attribute syntax. The attribute must be a\nnon-empty mapping or a zero-argument callable returning one.\n\nRegistry values are zero-argument factories or cloneable Crew instances. A\nfresh factory result or deep clone is used for each run to avoid cross-request\nmutation of CrewAI objects.\n\nThe registry can contain additional crews, but every host-admitted crew must be\npresent. A caller cannot choose a Python import path.\n\nRead capability IDs\n\nThe run operation retains the historical base ID. Every other allowed\noperation uses a suffix.\n\ncap:crewai:\ncap:crewai::status\ncap:crewai::events\ncap:crewai::cancel\ncap:crewai::batchrun\ncap:crewai::replay\ncap:crewai::train\ncap:crewai::test\ncap:crewai::knowledgequery\ncap:crewai::memoryreset\n\nA crew publishes only its allowed operations. Legacy descriptors without an\nallowlist receive run, status, events, and cancel.\n\nThere is no universal manifest count. A fully enabled crew publishes ten\ncapabilities; a legacy-policy crew publishes four.\n\nCompare the ten operations\n\n| Operation | Kind | Risk | Mutation | Streaming | Advertised cancellation |\n\n| run | Agent | Medium | Yes | Yes | Yes |\n| status | Tool | Low | No | No | No |\n| events | Tool | Low | No | Yes | No |\n| cancel | Tool | Medium | Yes | No | No |\n| batchrun | Agent | Medium | Yes | Yes | Yes |\n| replay | Agent | Medium | Yes | Yes | Yes |\n| train | Workflow | High | Yes | Yes | Yes |\n| test | Workflow | Medium | Yes | Yes | Yes |\n| knowledgequery | Tool | Low | No | No | No |\n| memoryreset | Tool | High | Yes | No | No |\n\nThe published contract marks all five streamed mutations as cancellable.\nReplay, training, and testing still execute synchronous CrewAI methods in\nworker threads, so sidecar cancellation does not prove that provider work\nstopped.\n\nApply execution controls\n\n| Surface | Approval | Idempotency key | Retry support |\n\n| Mutating operation | Required | Required | None |\n| knowledgequery | Not required | Required | Safe |\n| status and events | Not required | Optional | Safe |\n\nknowledgequery is provider-read-only but creates a durable sidecar job.\nThat job boundary requires a key even though the capability is retry-safe.\n\nThe reviewed Rust error mapper nevertheless marks every concrete connector\nfailure retryable: false. Treat the contract classification as capability\nmetadata, not permission to retry a failed request automatically.\n\nKeys use tenant scope, input-hash revalidation, and a 24-hour contract TTL.\nMutation approval uses tenant policy and a 15-minute decision TTL.\n\nEvery operation treats data as confidential, PII-bearing, and\nredaction-required. Mutations publish read, write, external-network, and code-\nexecution side effects.\n\nThe connector publishes no transaction, reconciliation, compensation, or\nprovider rollback support.\n\nPreserve durable job identity\n\nThe sidecar uses the AIP Action ID as its job identity. It hashes crew,\noperation, input, timeout, and idempotency key before scheduling provider work.\n\nReusing an Action ID with matching material returns the existing record.\nReusing it with different material returns a conflict.\n\nThe idempotency fence is persisted before CrewAI starts. A crash can therefore\nleave an uncertain result, but it must not make an admitted Action disappear.\n\nAt restart, any restored running job becomes a terminal failed record with\nuncertainoutcome: true. The sidecar never silently restarts it.\n\nOnly one active sidecar process may own a journal. The file lock and state\nvolume form a process fence, not a distributed active-active coordinator.\n\nTreat streams and cancellation precisely\n\nThe connector validates strict event sequence, normalizes sidecar SSE to AIP\nchunks, and requires a terminal completed, cancelled, or failed event.\n\nThe connector bounds each undelimited SSE frame to 1 MiB, the complete response\nto its configured limit, and one stream to 100,000 events.\n\nAll five streamed mutations can call the sidecar cancellation route. Cancelling\nan event replay only detaches the read-only stream.\n\nFor replay, train, and test, the route cancels the asyncio waiter and persists a\nterminal cancelled record while the worker thread can continue. The Rust\nconnector may then report remotestopconfirmed: true; this confirms only the\nsidecar response, not provider termination.\n\nRespect the principal limits\n\n| Boundary | Reviewed value |\n\n| Sidecar-validated operation input | 1 MiB |\n| Sidecar output | 4 MiB |\n| Connector response, default | 64 MiB |\n| Connector response, maximum | 256 MiB |\n| Sidecar event, default | 256 KiB |\n| Sidecar events per run, default | 1,000 |\n| Connector SSE events | 100,000 |\n| Execution timeout, default | 600,000 ms |\n| Execution timeout, maximum | 3,600,000 ms |\n\nThe sidecar also bounds concurrency, retained runs, journal size, checkpoint\nfrequency, query items, batch inputs, and training iterations.\n\nBind the compatibility baseline\n\n| Component | Reviewed identity |\n\n| AIP source | 97be86e9efedf07ecf1783b03800f683f107fb04 |\n| Connector profile | aip.connector.crewai.v1 |\n| Sidecar package | aip-crewai-sidecar 1.0.0 |\n| Default product sidecar | locked crewai, crewai-cli, and crewai-core 1.15.5 |\n| Optional source-overlay image | CrewAI distribution from source version 1.15.2, installed without dependencies |\n| CrewAI source | bfa652a7be8637562cc9b0833f75d927a64552d1 |\n| Python range | >=3.10,<3.14 |\n\nThe controlled product Compose path builds the default lockfile-only image. A\nseparate Dockerfile.upstream first resolves the same lockfile, then reinstalls\nonly the CrewAI distribution from the pinned source tree without dependencies.\n\nThe source-overlay image therefore has a mixed package baseline. Keep default\nand source-overlay image digests distinct; a source commit or package version\nalone cannot identify either artifact.\n\nKnow what is not guaranteed\n\nThe reviewed source does not establish:\n• compatibility with arbitrary CrewAI versions, registries, models, or tools;\n• sandboxing of deployment-authored Crew code inside the Python process;\n• exactly-once effects in models, tools, memory, or external systems;\n• cancellation of synchronous replay, training, or evaluation work;\n• active-active sidecars over one journal or training directory;\n• automatic provider-state reconciliation after uncertain failure;\n• production qualification for the current artifact.\n\nCrew factories and their tools can execute deployment-owned code. Isolate the\nsidecar as a privileged workload and grant only intended provider access.\n\nChoose the next path\n\nUse the concise legacy page for the earlier high-level contract. Read the AIP\nexecution model before integrating Actions, and use the fleet guide for the\nstandalone topology.\n\nImplement retries only after reading the global error rules. The upstream-\nbaseline page explains how framework source identity is bounded.\n\nRelated documentation\n• Legacy CrewAI connector overview (../crewai.md)\n• How AIP works (../../getting-started/how-aip-works.md)\n• Deploy the connector fleet (../../guides/deploy-connector-fleet.md)\n• Errors and retry decisions (../../reference/errors.md)\n• Connector upstream baselines (../upstream-baselines.md)\n" }, "integrity": { "algorithm": "sha256", "sourceDigest": "e5fcf8204d3da28f1a4b51bd5e238561ecb534922a6f5fef88efc21e00f1b1dc" } }