> ## 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.

# Agents

> Create a reusable Agent whose immutable Versions are minted automatically.

An **Agent** is a reusable, versioned configuration for persona and capabilities.
It contains a model, system prompt, tools, MCP servers, Skills, metadata, and an
optional multiagent roster. An Agent is not a running process.

Checkfu follows the Claude Managed Agents lifecycle: there is no separate Draft
or publish step. Creating an Agent produces Version 1. Every update that changes
the configuration produces the next immutable Version automatically; a no-op
update returns the current Version.

## Create an Agent

<CodeGroup>
  ```sh CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  checkfu agent create --json --input '{
    "name": "support-agent",
    "model": "claude-opus-5",
    "system": "Answer clearly. Escalate when account access is required."
  }'
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST https://api.checkfu.com/v1/agents \
    --header "Authorization: Bearer $CHECKFU_API_KEY" \
    --header "Checkfu-Version: 2026-08-27" \
    --header "checkfu-beta: managed-agents-2026-04-01" \
    --header "Idempotency-Key: create-support-agent-$(uuidgen)" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "support-agent",
      "model": "claude-opus-5",
      "system": "Answer clearly. Escalate when account access is required."
    }'
  ```

  ```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const agent = await checkfu.beta.agents.create({
    name: "support-agent",
    model: "claude-opus-5",
    system: "Answer clearly. Escalate when account access is required.",
  })
  ```
</CodeGroup>

The response includes the stable `agent_…` ID and `version: 1`.

## Update and inspect Versions

`version` is an optional optimistic-concurrency guard. Supplying it rejects a
stale update with `409`; omitting it applies to the newest head. Omitted fields
are preserved. Array fields replace the whole array, metadata merges by key,
and `system` or `description` can be cleared with `null` or an empty string.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const updated = await checkfu.beta.agents.update(agent.id, {
  version: agent.version,
  description: "Handles the customer support queue.",
})

const exact = await checkfu.beta.agents.retrieve(agent.id, {
  version: updated.version,
})

const history = await checkfu.beta.agents.versions.list(agent.id)
```

Within a supplied `model` object, `effort` is the sole retained subfield when
the model ID is unchanged and effort is omitted. Other model fields are
whole-object replacement: omitting `speed` restores `standard`, and omitting
`inference_geo` clears the pin.

## Coordinator rosters

An Agent becomes a coordinator when `multiagent` contains a roster:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "coordinator",
  "agents": [
    "agent_11111111111111111111111111111111",
    {
      "type": "agent",
      "id": "agent_22222222222222222222222222222222",
      "version": 3
    },
    { "type": "self" }
  ]
}
```

A bare Agent ID resolves to its current Version when the coordinator Version is
created. The object form pins an exact Version. `self` is rebound to the new
coordinator Version on every update. All members must be active in the same
Workspace, must not themselves be coordinators, and must use the same inference
geo. An optional advisor is always returned last.

## Archive

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
await checkfu.beta.agents.archive(agent.id)
```

Archiving makes the Agent read-only. Existing immutable Versions remain
retrievable, and list calls omit archived Agents unless `include_archived` is
set.

The CMA-compatible Session admission surface is migrating separately. Until it
lands, do not use the retired Draft, Release, or AgentDeployment APIs with these
Agents.