{
  "schemaVersion": "1.0",
  "title": "Qualify the CrewAI connector",
  "description": "Use this procedure to evaluate one exact CrewAI host and sidecar pair. The result applies only to the recorded artifacts, configuration, topology, CrewAI package set, crew code, and executed cases.",
  "canonical": "https://getaip.org/docs/connectors/crewai/qualification",
  "route": "/docs/connectors/crewai/qualification",
  "source": "docs/connectors/crewai/qualification/README.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/crewai/qualification.md",
    "txt": "/docs/download/connectors/crewai/qualification.txt",
    "json": "/docs/download/connectors/crewai/qualification.json",
    "pdf": "/docs/download/connectors/crewai/qualification.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Qualify the CrewAI connector\ndescription: >-\n  Qualify one exact CrewAI host and sidecar through contract, artifact, durable\n  execution, fleet, recovery, and evidence gates\nkind: qualification\naudience: integrator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: crewai\naliases:\n  - CrewAI connector qualification\n  - CrewAI connector evidence\n  - Qualify aip-host-crewai\n---\n\n# Qualify the CrewAI connector\n\nUse this procedure to evaluate one exact CrewAI host and sidecar pair. The\nresult applies only to the recorded artifacts, configuration, topology,\nCrewAI package set, crew code, and executed cases.\n\nSource inspection is a prerequisite, not a qualification result. Record every\ncase as `PASS`, `FAIL`, or `NOT RUN`; never convert missing evidence into a\npassing claim.\n\n## Define the qualification claim\n\nState one bounded claim before execution:\n\n> The identified CrewAI connector artifacts preserve AIP identity, durable job\n> admission, ordered events, fail-closed routing, and recovery for the executed\n> crew and failure cases in the recorded topology.\n\nDo not expand this claim to external model quality, arbitrary tools, every\nCrewAI feature, active-active sidecar state, provider exactly-once behavior, or\nunexecuted operations.\n\n## Freeze every identity\n\nRecord these values in the run manifest:\n\n| Identity | Required value |\n|---|---|\n| AIP source | Full commit and clean source-tree digest |\n| Rust host | Image digest, OCI labels, SBOM, provenance, signature, and binary version |\n| Python sidecar | Image digest, package version, lockfile digest, SBOM, provenance, and signature |\n| CrewAI | Installed `crewai`, `crewai-core`, and `crewai-cli` versions |\n| Method source | Exact upstream source revision used for contract verification |\n| Crew code | Registry module, crew factory source digest, and admitted descriptor digest |\n| State | Fresh volume identity, filesystem, mount policy, and retention settings |\n| Fleet | Type, version, instance, replica, tenant, assignment, zone, and artifact digest |\n| Credentials | Non-secret provider, revision, scope, and rotation-policy references |\n| Runner | Operating system, architecture, Docker engine, Compose, Rust, Python, and `uv` versions |\n| Time | Run ID, UTC start and completion, and reviewer identity |\n\nUse immutable image digests during execution. A rebuilt image requires a new\nqualification even when source labels are unchanged.\n\n## Prepare a clean evidence directory\n\nCreate a new owner-only directory for each run. The pinned fleet verifier\nrejects an existing evidence directory and records diagnostics on both success\nand failure.\n\nPrepare these evidence groups:\n\n```text\ncrewai-qualification/<run-id>/\n├── identity/\n├── source-tests/\n├── sidecar-tests/\n├── images/\n├── runtime-evidence/\n├── failure-matrix.jsonl\n├── registry/\n├── state/\n├── logs/\n├── summary.json\n└── limitations.md\n```\n\nStore secret-bearing logs under restricted access. Publish only redacted\nderivatives and cryptographic digests.\n\n## Gate 1: verify source and contracts\n\nAt the reviewed AIP revision, verify:\n\n- the operation enum contains exactly ten unique operations;\n- seven operations create durable sidecar jobs;\n- `status`, `events`, and `cancel` are control operations;\n- every descriptor allowlist maps to a unique capability ID;\n- idempotency is required for all operations except status and events;\n- streaming and cancellation flags match the implementation paths;\n- the sidecar and Rust operation sets are identical;\n- the pinned CrewAI method signatures still match adapter calls;\n- public configuration and capability assets match generated values.\n\nFail this gate on any drift. Do not continue with a documentation or manifest\noverride that hides code disagreement.\n\n## Gate 2: run Rust connector tests\n\nThe package test gate is:\n\n```sh\ncargo test --locked -p aip-connector-crewai\n```\n\nRetain command, environment, exit status, and complete output. Confirm the six\nordinary tests cover:\n\n1. stable Action identity across run and cancel;\n2. one frozen job route and replay headers for seven startable operations;\n3. streaming contract advertisement;\n4. unique ten-operation catalogue and idempotency metadata;\n5. required SSE ordering metadata;\n6. preservation of cancellation reason.\n\nOne exact-sidecar test is ignored by the ordinary package run. Record it as\n`NOT RUN` until the qualification sidecar is supplied and the ignored test is\nexecuted deliberately.\n\nMock-sidecar tests establish Rust mapping behavior. They do not establish real\nCrewAI execution or journal durability.\n\n## Gate 3: run sidecar runtime tests\n\nResolve the frozen sidecar environment with its test extra, then execute the\npinned test directory:\n\n```sh\nuv sync --frozen --extra test\nuv run pytest\n```\n\nThe eleven async cases cover:\n\n- idempotent ordered streaming;\n- bounded durable stream checkpoints;\n- durable admission for every product operation;\n- idempotency before provider admission;\n- stream closure and terminal cancellation;\n- terminal replay and restart uncertainty;\n- exclusive journal ownership;\n- persistence before task scheduling;\n- retained-run and event fail-closed bounds;\n- authenticated HTTP with durable state;\n- rejection of unsafe non-loopback startup.\n\nRetain the resolved package inventory and lockfile digest with the output.\nPassing unit cases do not qualify a built container image.\n\n## Gate 4: verify both images\n\nApply the pinned image verification policy to the host and sidecar:\n\n| Check | Host expectation | Sidecar expectation |\n|---|---|---|\n| Runtime user | `10001:10001` | `10001:10001` |\n| Entrypoint | `/usr/local/bin/aip-connector-host` | `aip-crewai-sidecar` |\n| Component label | `aip-host-crewai` | `aip-crewai-sidecar` |\n| Source label | Exact AIP revision | Exact AIP revision |\n| Version label | Exact release version | Exact release version |\n| Runtime probe | `--help` in hardened container | Import installed sidecar package |\n| Retained evidence | Inspect, full history, and SPDX SBOM | Inspect, full history, and SPDX SBOM |\n\nAlso record the three installed CrewAI distribution versions. The default\nartifact should resolve the complete package set to `1.15.5` at this revision.\n\nVerify signatures and provenance against the admitted trust policy. The pinned\nimage helper records metadata and SBOMs but does not itself prove registry\nsignature policy.\n\n## Gate 5: qualify deterministic real CrewAI execution\n\nThe pinned qualification registry constructs a real CrewAI `Agent`, `Task`, and\nsequential `Crew`. It uses a custom `BaseLLM` that emits real CrewAI stream\nevents without network access.\n\nThe LLM returns `case triaged` and reports five tokens. This case proves the\nCrewAI library path, task graph, event bus, stream consumption, terminal output,\nand Rust-side mapping without depending on a model provider.\n\nExecute and retain these CrewAI native calls through the fleet gateway:\n\n| Case | Capability | Required observation |\n|---|---|---|\n| Seed status | `cap:crewai:support-qualification:status` | Preloaded terminal Action is readable |\n| Governed run | `cap:crewai:support-qualification` | Approval and completed real-CrewAI output |\n| Run status | `cap:crewai:support-qualification:status` | New Action identity and completed state |\n| Run events | `cap:crewai:support-qualification:events` | Ordered retained events from cursor zero |\n\nThe product qualification script runs these among fifteen native calls across\nfive product connectors. Retain the per-operation responses, stderr files,\napproval decision, operation ledger, and product summary.\n\nThis deterministic case does not contact an external model, tool, knowledge\nstore, evaluator, or telemetry service. Record those surfaces as `NOT RUN`\nunless separate exact-provider cases execute them.\n\n## Gate 6: verify fleet identity and isolation\n\nRequire:\n\n- one ready CrewAI replica with a live lease;\n- exactly ten admitted CrewAI capabilities;\n- manifest and artifact digests matching admission;\n- one independently owned CrewAI runtime database;\n- all five required runtime tables present;\n- the correct tenant, account, version, instance, replica, and zone;\n- discovery through the central gateway only for the admitted tenant;\n- a private authenticated sidecar route.\n\nThe pinned five-product topology totals 353 capabilities. That fleet total is\ncontext, not a CrewAI invariant.\n\n## Gate 7: verify restart and failure behavior\n\nExecute every case with before, fault, after, and recovery evidence.\n\n| Case | Required result |\n|---|---|\n| Graceful host restart | Replica goes offline, returns ready, and seeded status completes |\n| Host `SIGKILL` | Expired route fails closed, host returns healthy, and status completes |\n| Sidecar graceful restart | Real-run status and events remain readable from durable state |\n| Sidecar `SIGKILL` | Host becomes unroutable, status fails closed, then recovers after sidecar return |\n| Shared PostgreSQL outage | CrewAI request fails closed, storage recovers, lease returns, and status completes |\n| Gateway failover | The surviving gateway routes through the same admitted CrewAI replica |\n\nPreserve the sidecar volume across restart cases. A restart using a new empty\nvolume is not a durability test.\n\nThe pinned failure matrix reads status for an already completed Action. It does\nnot prove recovery of a running thread-backed train, replay, test, or batch job.\nRecord those cases as `NOT RUN` unless added explicitly.\n\n## Gate 8: add operation-specific cases\n\nThe public capability catalogue includes more operations than the pinned fleet\nscript exercises end to end. Add bounded cases for:\n\n| Operation | Required evidence |\n|---|---|\n| `batch_run` | Input count, ordered outputs, fallback path identity, and partial-effect analysis |\n| `replay` | Exact task ID, input override, thread behavior, and retained result |\n| `train` | Protected artifact path, digest, iterations, timeout, and uncertainty handling |\n| `test` | Evaluator identity, iterations, provider calls, and retained evaluation artifact |\n| `knowledge_query` | Query bounds, source identity, result count, scores, and read-only claim |\n| `memory_reset` | Selected domain, approval, before and after evidence, and irreversibility |\n| `cancel` | Async run and each thread-backed operation with provider-stop limitations |\n\nUse an external provider only when credentials, budgets, data policy, and\nretention have explicit approval. Keep deterministic and provider-live results\nseparate.\n\n## Gate 9: inspect the evidence bundle\n\nThe retained bundle should include:\n\n- source and dependency identities;\n- image inspect, history, SBOM, signature, and provenance;\n- Rust and Python test outputs;\n- admission package and trust decision;\n- registry baseline and final state;\n- runtime database ownership and migration state;\n- Compose process and Docker event timelines;\n- per-case native requests and responses;\n- approval decisions and operation ledger;\n- sidecar state digests before and after restart;\n- redacted timestamped logs;\n- failure-matrix outcomes;\n- final summary and explicit limitations.\n\nValidate that each referenced file exists and calculate a manifest digest for\nthe bundle. Keep raw restricted evidence separate from its publishable index.\n\n## Decide the result\n\n| Result | Rule |\n|---|---|\n| `PASS` | Every required gate passed for the exact identities and every limitation is explicit |\n| `FAIL` | A required case failed, evidence conflicts, identity drifted, or cleanup destroyed required evidence |\n| `NOT RUN` | The case did not execute or lacks sufficient evidence |\n\nA qualification can pass with documented out-of-scope cases only when the\nclaim excludes them. It cannot pass by silently omitting a required case.\n\nPublish the exact artifact digests, topology, executed case list, result,\nevidence-manifest digest, and limitations. Never publish unredacted credentials\nor governed provider content.\n\n## Clean up without losing proof\n\nAfter the evidence bundle is sealed:\n\n1. revoke qualification credentials and assignments;\n2. stop the isolated topology;\n3. remove only run-scoped containers, networks, and volumes;\n4. retain required journal and artifact snapshots in protected evidence;\n5. verify evidence hashes after transfer;\n6. record cleanup status separately from the qualification result.\n\nCleanup failure does not rewrite a passed case. Record it as an operational\nfailure requiring remediation.\n\n## Related documentation\n\n- [CrewAI connector overview](../README.md)\n- [CrewAI capability index](../capabilities/README.md)\n- [Deploy the CrewAI connector](../operations/deployment.md)\n- [CrewAI health, observability, and recovery](../operations/health-observability-and-recovery.md)\n- [Conformance and qualification](../../../reference/conformance.md)\n",
    "text": "Qualify the CrewAI connector\n\nUse this procedure to evaluate one exact CrewAI host and sidecar pair. The\nresult applies only to the recorded artifacts, configuration, topology,\nCrewAI package set, crew code, and executed cases.\n\nSource inspection is a prerequisite, not a qualification result. Record every\ncase as PASS, FAIL, or NOT RUN; never convert missing evidence into a\npassing claim.\n\nDefine the qualification claim\n\nState one bounded claim before execution:\n\nThe identified CrewAI connector artifacts preserve AIP identity, durable job\nadmission, ordered events, fail-closed routing, and recovery for the executed\ncrew and failure cases in the recorded topology.\n\nDo not expand this claim to external model quality, arbitrary tools, every\nCrewAI feature, active-active sidecar state, provider exactly-once behavior, or\nunexecuted operations.\n\nFreeze every identity\n\nRecord these values in the run manifest:\n\n| Identity | Required value |\n\n| AIP source | Full commit and clean source-tree digest |\n| Rust host | Image digest, OCI labels, SBOM, provenance, signature, and binary version |\n| Python sidecar | Image digest, package version, lockfile digest, SBOM, provenance, and signature |\n| CrewAI | Installed crewai, crewai-core, and crewai-cli versions |\n| Method source | Exact upstream source revision used for contract verification |\n| Crew code | Registry module, crew factory source digest, and admitted descriptor digest |\n| State | Fresh volume identity, filesystem, mount policy, and retention settings |\n| Fleet | Type, version, instance, replica, tenant, assignment, zone, and artifact digest |\n| Credentials | Non-secret provider, revision, scope, and rotation-policy references |\n| Runner | Operating system, architecture, Docker engine, Compose, Rust, Python, and uv versions |\n| Time | Run ID, UTC start and completion, and reviewer identity |\n\nUse immutable image digests during execution. A rebuilt image requires a new\nqualification even when source labels are unchanged.\n\nPrepare a clean evidence directory\n\nCreate a new owner-only directory for each run. The pinned fleet verifier\nrejects an existing evidence directory and records diagnostics on both success\nand failure.\n\nPrepare these evidence groups:\n\ncrewai-qualification//\n├── identity/\n├── source-tests/\n├── sidecar-tests/\n├── images/\n├── runtime-evidence/\n├── failure-matrix.jsonl\n├── registry/\n├── state/\n├── logs/\n├── summary.json\n└── limitations.md\n\nStore secret-bearing logs under restricted access. Publish only redacted\nderivatives and cryptographic digests.\n\nGate 1: verify source and contracts\n\nAt the reviewed AIP revision, verify:\n• the operation enum contains exactly ten unique operations;\n• seven operations create durable sidecar jobs;\n• status, events, and cancel are control operations;\n• every descriptor allowlist maps to a unique capability ID;\n• idempotency is required for all operations except status and events;\n• streaming and cancellation flags match the implementation paths;\n• the sidecar and Rust operation sets are identical;\n• the pinned CrewAI method signatures still match adapter calls;\n• public configuration and capability assets match generated values.\n\nFail this gate on any drift. Do not continue with a documentation or manifest\noverride that hides code disagreement.\n\nGate 2: run Rust connector tests\n\nThe package test gate is:\n\ncargo test --locked -p aip-connector-crewai\n\nRetain command, environment, exit status, and complete output. Confirm the six\nordinary tests cover:\n1. stable Action identity across run and cancel;\n2. one frozen job route and replay headers for seven startable operations;\n3. streaming contract advertisement;\n4. unique ten-operation catalogue and idempotency metadata;\n5. required SSE ordering metadata;\n6. preservation of cancellation reason.\n\nOne exact-sidecar test is ignored by the ordinary package run. Record it as\nNOT RUN until the qualification sidecar is supplied and the ignored test is\nexecuted deliberately.\n\nMock-sidecar tests establish Rust mapping behavior. They do not establish real\nCrewAI execution or journal durability.\n\nGate 3: run sidecar runtime tests\n\nResolve the frozen sidecar environment with its test extra, then execute the\npinned test directory:\n\nuv sync --frozen --extra test\nuv run pytest\n\nThe eleven async cases cover:\n• idempotent ordered streaming;\n• bounded durable stream checkpoints;\n• durable admission for every product operation;\n• idempotency before provider admission;\n• stream closure and terminal cancellation;\n• terminal replay and restart uncertainty;\n• exclusive journal ownership;\n• persistence before task scheduling;\n• retained-run and event fail-closed bounds;\n• authenticated HTTP with durable state;\n• rejection of unsafe non-loopback startup.\n\nRetain the resolved package inventory and lockfile digest with the output.\nPassing unit cases do not qualify a built container image.\n\nGate 4: verify both images\n\nApply the pinned image verification policy to the host and sidecar:\n\n| Check | Host expectation | Sidecar expectation |\n\n| Runtime user | 10001:10001 | 10001:10001 |\n| Entrypoint | /usr/local/bin/aip-connector-host | aip-crewai-sidecar |\n| Component label | aip-host-crewai | aip-crewai-sidecar |\n| Source label | Exact AIP revision | Exact AIP revision |\n| Version label | Exact release version | Exact release version |\n| Runtime probe | --help in hardened container | Import installed sidecar package |\n| Retained evidence | Inspect, full history, and SPDX SBOM | Inspect, full history, and SPDX SBOM |\n\nAlso record the three installed CrewAI distribution versions. The default\nartifact should resolve the complete package set to 1.15.5 at this revision.\n\nVerify signatures and provenance against the admitted trust policy. The pinned\nimage helper records metadata and SBOMs but does not itself prove registry\nsignature policy.\n\nGate 5: qualify deterministic real CrewAI execution\n\nThe pinned qualification registry constructs a real CrewAI Agent, Task, and\nsequential Crew. It uses a custom BaseLLM that emits real CrewAI stream\nevents without network access.\n\nThe LLM returns case triaged and reports five tokens. This case proves the\nCrewAI library path, task graph, event bus, stream consumption, terminal output,\nand Rust-side mapping without depending on a model provider.\n\nExecute and retain these CrewAI native calls through the fleet gateway:\n\n| Case | Capability | Required observation |\n\n| Seed status | cap:crewai:support-qualification:status | Preloaded terminal Action is readable |\n| Governed run | cap:crewai:support-qualification | Approval and completed real-CrewAI output |\n| Run status | cap:crewai:support-qualification:status | New Action identity and completed state |\n| Run events | cap:crewai:support-qualification:events | Ordered retained events from cursor zero |\n\nThe product qualification script runs these among fifteen native calls across\nfive product connectors. Retain the per-operation responses, stderr files,\napproval decision, operation ledger, and product summary.\n\nThis deterministic case does not contact an external model, tool, knowledge\nstore, evaluator, or telemetry service. Record those surfaces as NOT RUN\nunless separate exact-provider cases execute them.\n\nGate 6: verify fleet identity and isolation\n\nRequire:\n• one ready CrewAI replica with a live lease;\n• exactly ten admitted CrewAI capabilities;\n• manifest and artifact digests matching admission;\n• one independently owned CrewAI runtime database;\n• all five required runtime tables present;\n• the correct tenant, account, version, instance, replica, and zone;\n• discovery through the central gateway only for the admitted tenant;\n• a private authenticated sidecar route.\n\nThe pinned five-product topology totals 353 capabilities. That fleet total is\ncontext, not a CrewAI invariant.\n\nGate 7: verify restart and failure behavior\n\nExecute every case with before, fault, after, and recovery evidence.\n\n| Case | Required result |\n\n| Graceful host restart | Replica goes offline, returns ready, and seeded status completes |\n| Host SIGKILL | Expired route fails closed, host returns healthy, and status completes |\n| Sidecar graceful restart | Real-run status and events remain readable from durable state |\n| Sidecar SIGKILL | Host becomes unroutable, status fails closed, then recovers after sidecar return |\n| Shared PostgreSQL outage | CrewAI request fails closed, storage recovers, lease returns, and status completes |\n| Gateway failover | The surviving gateway routes through the same admitted CrewAI replica |\n\nPreserve the sidecar volume across restart cases. A restart using a new empty\nvolume is not a durability test.\n\nThe pinned failure matrix reads status for an already completed Action. It does\nnot prove recovery of a running thread-backed train, replay, test, or batch job.\nRecord those cases as NOT RUN unless added explicitly.\n\nGate 8: add operation-specific cases\n\nThe public capability catalogue includes more operations than the pinned fleet\nscript exercises end to end. Add bounded cases for:\n\n| Operation | Required evidence |\n\n| batchrun | Input count, ordered outputs, fallback path identity, and partial-effect analysis |\n| replay | Exact task ID, input override, thread behavior, and retained result |\n| train | Protected artifact path, digest, iterations, timeout, and uncertainty handling |\n| test | Evaluator identity, iterations, provider calls, and retained evaluation artifact |\n| knowledgequery | Query bounds, source identity, result count, scores, and read-only claim |\n| memoryreset | Selected domain, approval, before and after evidence, and irreversibility |\n| cancel | Async run and each thread-backed operation with provider-stop limitations |\n\nUse an external provider only when credentials, budgets, data policy, and\nretention have explicit approval. Keep deterministic and provider-live results\nseparate.\n\nGate 9: inspect the evidence bundle\n\nThe retained bundle should include:\n• source and dependency identities;\n• image inspect, history, SBOM, signature, and provenance;\n• Rust and Python test outputs;\n• admission package and trust decision;\n• registry baseline and final state;\n• runtime database ownership and migration state;\n• Compose process and Docker event timelines;\n• per-case native requests and responses;\n• approval decisions and operation ledger;\n• sidecar state digests before and after restart;\n• redacted timestamped logs;\n• failure-matrix outcomes;\n• final summary and explicit limitations.\n\nValidate that each referenced file exists and calculate a manifest digest for\nthe bundle. Keep raw restricted evidence separate from its publishable index.\n\nDecide the result\n\n| Result | Rule |\n\n| PASS | Every required gate passed for the exact identities and every limitation is explicit |\n| FAIL | A required case failed, evidence conflicts, identity drifted, or cleanup destroyed required evidence |\n| NOT RUN | The case did not execute or lacks sufficient evidence |\n\nA qualification can pass with documented out-of-scope cases only when the\nclaim excludes them. It cannot pass by silently omitting a required case.\n\nPublish the exact artifact digests, topology, executed case list, result,\nevidence-manifest digest, and limitations. Never publish unredacted credentials\nor governed provider content.\n\nClean up without losing proof\n\nAfter the evidence bundle is sealed:\n1. revoke qualification credentials and assignments;\n2. stop the isolated topology;\n3. remove only run-scoped containers, networks, and volumes;\n4. retain required journal and artifact snapshots in protected evidence;\n5. verify evidence hashes after transfer;\n6. record cleanup status separately from the qualification result.\n\nCleanup failure does not rewrite a passed case. Record it as an operational\nfailure requiring remediation.\n\nRelated documentation\n• CrewAI connector overview (../README.md)\n• CrewAI capability index (../capabilities/README.md)\n• Deploy the CrewAI connector (../operations/deployment.md)\n• CrewAI health, observability, and recovery (../operations/health-observability-and-recovery.md)\n• Conformance and qualification (../../../reference/conformance.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "177a5467d4a8bff3774487322e224bff9c0896298a34a84f5514845a88a1cfc8"
  }
}