> ## Documentation Index
> Fetch the complete documentation index at: https://checkfu.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent deployments

> Create, read, and revise the Workspace-scoped deployments Sessions admit against.

<Warning>
  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.
</Warning>

An [AgentDeployment](/concepts/agents) 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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/organizations/workspaces/{workspace_id}/agent-deployments
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 `key`s (`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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/agent-deployments/{agent_deployment_id}/revisions
```

A revision is a complete snapshot, never a patch:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](/concepts/capabilities), revised independently:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/agent-deployments/{agent_deployment_id}/connection-bindings
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/agents/{id}/deploy
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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.

## `AgentDeployment`

| Field                      | Shape                                                               |            |
| -------------------------- | ------------------------------------------------------------------- | ---------- |
| `id`                       | `AgentDeploymentId` (`adep_…`)                                      |            |
| `workspace_id`             | `WorkspaceId` (`wrkspc_…`)                                          |            |
| `agent_id`                 | `AgentId` (`agent_…`)                                               |            |
| `key`                      | Workspace-unique logical name                                       |            |
| `display_name`             | String or `null`                                                    |            |
| `status`                   | \`active                                                            | archived\` |
| `current_revision_number`  | `0` until the first revision publish, then the pinned head revision |            |
| `resource_version`         | Compare-and-swap counter                                            |            |
| `created_at`, `updated_at` | Server timestamps                                                   |            |
| `archived_at`              | Archive timestamp or `null`                                         |            |

See [Agents](/concepts/agents) for the authoring side and [Sessions](/reference/sessions) for how admission consumes the revision.