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

# Create and version an Agent

> Create an Agent, update it, and retrieve immutable Versions.

Checkfu matches Claude Managed Agents: Agent Versions are automatic. There is
no Draft resource and no publish operation. The CLI and TypeScript examples
require [CLI access](/getting-started/cli-access) and [SDK
access](/reference/typescript-sdk).

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Checkfu } from "@checkfu/sdk"

const checkfu = new Checkfu({ apiKey: process.env.CHECKFU_API_KEY })
```

## Create Version 1

<CodeGroup>
  ```sh CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  export CHECKFU_AGENT_ID="$(checkfu agent create --json --input '{
    "name": "release-notes",
    "model": "claude-opus-5",
    "system": "Lead with user impact, then cite verification evidence."
  }' | jq -r '.id')"
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  export CHECKFU_AGENT_ID="$(curl --silent --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 "Content-Type: application/json" \
    --data '{
      "name": "release-notes",
      "model": "claude-opus-5",
      "system": "Lead with user impact, then cite verification evidence."
    }' | jq -r '.id')"
  ```

  ```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const agent = await checkfu.beta.agents.create({
    name: "release-notes",
    model: "claude-opus-5",
    system: "Lead with user impact, then cite verification evidence.",
  })
  ```
</CodeGroup>

The CLI and cURL tabs capture the stable `agent_…` ID in
`CHECKFU_AGENT_ID`; the TypeScript tab retains it as `agent.id`. The created
Agent has `version: 1`.

## Create the next Version

<CodeGroup>
  ```sh CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  checkfu agent update "$CHECKFU_AGENT_ID" --json --input '{
    "version": 1,
    "description": "Drafts concise release notes from verified changes."
  }'
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST "https://api.checkfu.com/v1/agents/$CHECKFU_AGENT_ID" \
    --header "Authorization: Bearer $CHECKFU_API_KEY" \
    --header "Checkfu-Version: 2026-08-27" \
    --header "checkfu-beta: managed-agents-2026-04-01" \
    --header "Content-Type: application/json" \
    --data '{
      "version": 1,
      "description": "Drafts concise release notes from verified changes."
    }'
  ```

  ```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const updated = await checkfu.beta.agents.update(agent.id, {
    version: agent.version,
    description: "Drafts concise release notes from verified changes.",
  })
  ```
</CodeGroup>

A changed configuration returns Version 2. The optional `version` field is the
optimistic-concurrency guard; omit it for a last-write-wins declarative apply
loop. An unchanged effective configuration is a no-op.

## Retrieve one exact Version

<CodeGroup>
  ```sh CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  checkfu agent get "$CHECKFU_AGENT_ID" --version 1 --json
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.checkfu.com/v1/agents/$CHECKFU_AGENT_ID?version=1" \
    --header "Authorization: Bearer $CHECKFU_API_KEY" \
    --header "Checkfu-Version: 2026-08-27" \
    --header "checkfu-beta: managed-agents-2026-04-01"
  ```

  ```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const version1 = await checkfu.beta.agents.retrieve(agent.id, { version: 1 })
  ```
</CodeGroup>

Updating the Agent head never changes an earlier Version.

## List Version history

<CodeGroup>
  ```sh CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  checkfu agent versions "$CHECKFU_AGENT_ID" --json
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.checkfu.com/v1/agents/$CHECKFU_AGENT_ID/versions" \
    --header "Authorization: Bearer $CHECKFU_API_KEY" \
    --header "Checkfu-Version: 2026-08-27" \
    --header "checkfu-beta: managed-agents-2026-04-01"
  ```

  ```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const versions = await checkfu.beta.agents.versions.list(agent.id)
  ```
</CodeGroup>

The CMA-compatible Session slice is the next lifecycle step. The retired Draft,
Release, export/import, and AgentDeployment calls are not part of the current
Agent API.