Agent deployments

This is a historical migration reference. AgentDeployment is not part of the CMA-compatible Agent API, and the deploy commands below are not executable with checkfu.beta.agents. CMA-compatible Session admission will select an Agent Version and Environment directly.

An AgentDeployment is the Workspace-scoped deployment of one Agent. Session creation names a deployment and either pins one exact revision or resolves the deployment’s current revision once at admission, so every Session runs an immutable, reproducible configuration snapshot. Writes require a Workspace root or admin key; every control-plane read role may read. Creation publishes the head only — current_revision_number starts at 0 and the first revision is an explicit publish.

Create a deployment

POST /v1/organizations/workspaces/{workspace_id}/agent-deployments

{
  "agent_id": "agent_0123456789abcdef0123456789abcdef",
  "key": "support-stable",
  "display_name": "Support (stable)"
}

The deployment id is deterministic over (Workspace, Agent), so an exact keyed retry converges on the same head. Multiple deployments of one Agent may coexist in one Workspace under distinct keys (support-stable beside support-canary) — that is the whole per-Session variance model, because the Session-create wire has no per-Session override knob. GET /v1/organizations/workspaces/{workspace_id}/agent-deployments lists with the standard cursor plus exact key and status filters.

Retrieve a deployment

GET /v1/agent-deployments/{agent_deployment_id}

Returns the deployment head. This read is the supported way to recover the owning Agent from a Session’s agent_deployment_id coordinate.

Patch a deployment

PATCH /v1/agent-deployments/{agent_deployment_id}

{ "expected_resource_version": 3, "display_name": "Support (stable, Q3)", "status": "archived" } — at least one field. Archive is terminal; a stale expected_resource_version returns 409 validation.conflict instead of overwriting another review.

Publish a revision

POST /v1/agent-deployments/{agent_deployment_id}/revisions

A revision is a complete snapshot, never a patch:

{
  "expected_resource_version": 3,
  "agent_release_number": 4,
  "model_routing": {
    "model_routing_profile_id": "mrp_0123456789abcdef0123456789abcdef",
    "model_routing_profile_revision_number": 2
  },
  "execution_target": {
    "type": "managed",
    "harness_profile_id": "hprof_0123456789abcdef0123456789abcdef",
    "harness_profile_revision_number": 5,
    "sandbox_profile_id": "sprof_0123456789abcdef0123456789abcdef",
    "sandbox_profile_revision_number": 2,
    "runner_pool_id": null,
    "harness_topology": "colocated"
  },
  "skill_selections": [],
  "connection_binding_selections": []
}

The discriminated execution_target is closed: a managed target pins exact HarnessProfile and SandboxProfile revisions, an optional RunnerPool, and the harness topology (colocated or split); a connected target pins the customer-operated ConnectedHarness id and its expected non-secret capability-set digest with harness_topology: "connected". A coordinator release additionally carries its resolved roster_snapshot — every member an exact AgentDeploymentRevision in the same Workspace, in authored position order. Publishing advances the head’s current_revision_number under compare-and-swap; a same-number identical-content replay is idempotent, and an old revision never mutates. GET /v1/agent-deployments/{agent_deployment_id}/revisions lists revisions and GET …/revisions/{revision_number} reads one. A pinned revision is static configuration, not live authority: it never freezes away a later PermissionAssignment, ActionPolicy, membership, credential, Budget, lifecycle, or connection revocation. Those stay live checks at their documented boundaries.

Connection bindings

A connection binding is a stable head connecting one deployment to one Connection, revised independently:

POST /v1/agent-deployments/{agent_deployment_id}/connection-bindings

{
  "agent_deployment_id": "adep_0123456789abcdef0123456789abcdef",
  "integration_connection_id": "conn_0123456789abcdef0123456789abcdef",
  "key": "linear",
  "display_name": "Linear"
}

GET /v1/agent-deployment-connection-bindings/{id} reads the head and PATCH on the same path takes expected_resource_version plus optional display_name/status. POST /v1/agent-deployment-connection-bindings/{id}/revisions publishes the immutable non-secret configuration snapshot — tool_selection (logical tool names), tool_aliases, and argument_policy (default or strict) — and GET …/revisions/{revision_number} reads one. A binding revision is configuration, never credential authority, and a binding revision publish requires a new deployment revision before new Sessions may use it.

Deploy an existing release

POST /v1/agents/{id}/deploy

{
  "agent_release_number": 4,
  "target_workspace_id": "wrkspc_0123456789abcdef0123456789abcdef"
}

deployAgentRelease requires an organization-scoped root or admin key and an explicit target_workspace_id in the same Organization and Tenant; deployment_stage never selects the target. It composes the same aggregate from an existing published release: it ensures the target Workspace’s deployment (deterministic key agent-{agentId}) and publishes an exact-pin revision when the target Workspace holds every profile the release names — head-only otherwise, and never a revision for a coordinator release until member resolution exists. Deploying never copies the Agent or forks its identity; repeating a completed deploy converges on the same deployment head.