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

CLI

checkfu agent create --json --input '{
  "name": "support-agent",
  "model": "claude-opus-5",
  "system": "Answer clearly. Escalate when account access is required."
}'

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.

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:

{
  "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

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.