CrewAI sidecar contract and lockfile

This reference identifies the Python artifact behind the CrewAI connector and the private HTTP contract used by its Rust host. Use it to compare image provenance, request shapes, durable records, and failure responses.

The sidecar is not a tenant-facing AIP API. AIP identity, admission, policy, approval, routing, and signed results remain owned by the Rust host and shared runtime.

Fix the reviewed identity

The operation catalogue records the method-verification source revision. That revision is not the package identity of the default product sidecar.

Choose the artifact definition deliberately

The reviewed tree contains two image definitions with different identities.

The default image labels CrewAI version 1.15.5. It also places CREWAI_STORAGE_DIR and HOME under /var/lib/aip-crewai so journal and CrewAI-local state share one durable volume.

The source-overlay definition accepts a CREWAI_SOURCE_REVISION build argument and copies an external stage named crewai-source. It verifies only that the argument is non-empty; it does not compare the argument with copied bytes.

At the reviewed CrewAI source commit, the reinstalled distribution reports 1.15.2. The overlay does not reinstall crewai-core or crewai-cli, so those dependencies remain at lockfile version 1.15.5.

The source-overlay definition also lacks the default image’s durable HOME and CREWAI_STORAGE_DIR declarations. Configure equivalent paths explicitly before using that artifact with persistent credentials or storage.

Bind the source files and lockfile

These SHA-256 values are calculated from each blob at the reviewed AIP commit.

An image digest and retained software bill of materials remain the deployment identity. Source hashes identify reviewed inputs; they do not prove which bytes a registry image contains.

Keep the HTTP boundary private

Every route requires the complete Bearer header unless the process binds to loopback and explicitly enables unauthenticated development mode. The sidecar compares the expected header in constant time.

Uvicorn disables proxy-header trust and omits its server header. These settings do not supply TLS, AIP identity, tenant routing, or admission. Deploy the sidecar behind the fixed private route used by aip-host-crewai.

The Rust host disables redirects and uses HTTPS except for explicit loopback HTTP. Do not expose the sidecar port through the public AIP edge.

Read the start and cancel models

Every startable operation uses this closed request envelope:

Operation-specific validation then applies exact fields and bounds. The sidecar rejects unknown request-envelope fields.

Cancellation uses a separate closed envelope:

The request model does not reject control characters in reason at this revision.

Use only the fixed private routes

Legacy aliases remain for POST /runs, POST /runs/stream, GET /runs/{action_id}, and POST /runs/{action_id}/cancel. The two start aliases accept only the run operation.

There is no legacy events or archive alias. AIP callers must not call either route family directly.

Supply the required headers

The Rust connector also sends X-AIP-Action-ID on job starts and explicit cancel Actions. The reviewed FastAPI handlers do not read that header; the body and path IDs remain authoritative inside the sidecar.

Interpret records and event streams

A durable record contains Action ID, crew ID, operation, request hash, status, events, and optional output. Raw operation input and idempotency-key bytes are not persisted, but they contribute to the request hash.

Events have this stored form:

{
  "event": "completed",
  "sequence": 3,
  "data": {
    "status": "completed"
  }
}

SSE serializes the same record under its event name:

event: completed
data: {"event":"completed","sequence":3,"data":{"status":"completed"}}

One job status is running, completed, failed, or cancelled. A blocking route returns only after terminal state or its HTTP wait timeout. The timeout does not prove that the job or worker thread stopped.

Stored events and output can contain model, tool, knowledge, or provider data. Treat the journal as confidential even though credential and raw-input bytes are absent.

Interpret HTTP failures

An ordinary provider failure becomes a terminal failed event with exception class and a generic message. It has no uncertain_outcome field at this revision.

The sidecar logs such failures with LOGGER.exception. Restrict and redact sidecar logs because provider exception text and traceback may contain governed content or credentials.

Verify an artifact before deployment

1. identify which Dockerfile definition produced the image;
2. verify the exact AIP commit and the relevant source-blob hashes;
3. retain the immutable image digest, labels, build provenance, and SBOM;
4. inspect installed crewai, crewai-core, and crewai-cli distributions;
5. verify durable HOME, CrewAI storage, journal, and training paths;
6. compare authenticated health with the admitted descriptor set;
7. qualify route, timeout, restart, cancellation, and archive behavior;
8. record every mismatch between published support and provider behavior.

Do not infer a source-overlay build from the revision label alone. Do not infer provider termination from a successful cancellation response.

Related documentation

• CrewAI connector overview
• CrewAI connector configuration
• CrewAI authentication and admitted crews
• CrewAI capability index
• Errors and retry decisions