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

# Create and version an Agent

> Create an Agent, update its mutable head, and retrieve immutable AgentVersions.

Creating an Agent creates AgentVersion 1 automatically. A material update creates
the next immutable AgentVersion. There is no separate draft or publish step.

The CLI and TypeScript examples require [CLI
access](/getting-started/cli-access) and [SDK
access](/reference/typescript-sdk).

<Warning>
  Plain HTTP against the Checkfu API needs no private package.
  The Checkfu CLI and TypeScript SDK are private-alpha artifacts with no self-service public installation channel.
  The artifacts this page uses are gated behind the current private-alpha rollout.
  Confirm [capability status](/getting-started/status) before making availability part of your application's contract.
</Warning>

```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 the Agent and Version 1

<CodeGroup>
  ```sh CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  export CHECKFU_AGENT_ID="$(checkfu agent create --json --input '{
    "name": "change-summary",
    "model": "claude-opus-5",
    "harness": "claude-code",
    "system": "Summarize 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-31" \
    --header "Idempotency-Key: create-change-summary-$(uuidgen)" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "change-summary",
      "model": "claude-opus-5",
      "harness": "claude-code",
      "system": "Summarize user impact, then cite verification evidence."
    }' | jq -r '.id')"
  ```

  ```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const agent = await checkfu.agents.create({
    name: "change-summary",
    model: "claude-opus-5",
    harness: "claude-code",
    system: "Summarize user impact, then cite verification evidence.",
  })
  ```
</CodeGroup>

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

## Create the next AgentVersion

<CodeGroup>
  ```sh CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  checkfu agent update "$CHECKFU_AGENT_ID" --json --input '{
    "version": 1,
    "description": "Writes concise change summaries 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-31" \
    --header "Content-Type: application/json" \
    --data '{
      "version": 1,
      "description": "Writes concise change summaries from verified changes."
    }'
  ```

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

`harness` is not an update field. It is chosen once, at create, and every
later Version carries that choice forward unchanged, so a partial update can
never silently retarget an Agent's execution loop. Sending it to
`agents.update` is rejected as an unexpected field. To run one Session on a
different harness, override it on that Session
(`agent: { type: "agent_with_overrides", harness: "codex", … }`); to change an
Agent's standing choice, create a new Agent.

A changed effective configuration returns Version 2. The optional `version`
field is an optimistic-concurrency guard. It rejects the update if another
write already advanced the Agent. Omitting it applies the update to the current
head. An unchanged effective configuration is a no-op and returns the current
Version.

The `version` field prevents stale writes; it does not decide authorship. UI,
HTTP, SDK, CLI, and MCP all invoke the same Agent operations. Keep zero or one
active desired-state owner for the Agent. See [Author an Agent
project](/guides/author-an-agent-project) before adding a Git- or YAML-backed
reconciler.

## Retrieve one exact AgentVersion

<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-31" \
  ```

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

Updating the Agent never changes an earlier AgentVersion.

## List AgentVersion 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-31" \
  ```

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

## Admit the Version into a Session

Create or choose an [Environment](/concepts/work-environments), then create a
Session. Pin the exact AgentVersion when reproducibility matters:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const environment = await checkfu.environments.create({
  name: "change-summary-work",
})

const session = await checkfu.sessions.create({
  agent: {
    type: "agent",
    id: agent.id,
    version: updated.version,
  },
  environment_id: environment.id,
})
```

The Session freezes that AgentVersion and the selected Environment at
admission. Later Agent or Environment edits do not change the admitted Session.
Omit `version` from the Agent selector when you want admission to resolve the
Agent's current Version.