Create and version an Agent

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 and SDK access. The example uses the BYOK claude-opus-5 model. To run it on your own key, add an Anthropic credential in Model credentials and pin it from the model config ("model": { "id": "claude-opus-5", "provider": "anthropic", "model_credential_id": "mcred_..." }); see Model access. Starting a Session also requires a ready Claude Code image and qualified Runner; check capability status before trying one.

Plain HTTP against the Checkfu API needs no private package. The Checkfu CLI and TypeScript SDK are optional private-alpha artifacts; the HTTP requests work without them. Part of this flow is behind a rollout fence; a deployment that has not enabled it refuses the request rather than running it. Confirm capability status before making availability part of your application’s contract.

import { Checkfu } from "@checkfu/sdk"

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

Create the Agent and Version 1

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')"

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')"

const agent = await checkfu.agents.create({
  name: "change-summary",
  model: "claude-opus-5",
  harness: "claude-code",
  system: "Summarize user impact, then cite verification evidence.",
})

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

Create the next AgentVersion

checkfu agent update "$CHECKFU_AGENT_ID" --json --input '{
  "version": 1,
  "description": "Writes concise change summaries from verified changes."
}'

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."
  }'

const updated = await checkfu.agents.update(agent.id, {
  version: agent.version,
  description: "Writes concise change summaries from verified changes.",
})

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. An update’s model replaces the whole model. If the Agent holds a provider or a model_credential_id, send it again to keep it: an update that leaves a held selector out is refused with validation.malformed and the field name, instead of moving the Agent to another provider or payer. To change a held selector, send the new value, or null to clear it, together with the Agent version you last read. A change to supply without version, or with a stale one, is refused, and a newly chosen credential must be an active credential in the Workspace for the model’s provider. Moving a held credential to a different provider by changing the model id also needs version. This rule applies to Agent updates only. 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 before adding a Git- or YAML-backed reconciler.

Retrieve one exact AgentVersion

checkfu agent get "$CHECKFU_AGENT_ID" --version 1 --json

curl "https://api.checkfu.com/v1/agents/$CHECKFU_AGENT_ID?version=1" \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31"

const version1 = await checkfu.agents.retrieve(agent.id, { version: 1 })

Updating the Agent never changes an earlier AgentVersion.

List AgentVersion history

checkfu agent versions "$CHECKFU_AGENT_ID" --json

curl "https://api.checkfu.com/v1/agents/$CHECKFU_AGENT_ID/versions" \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31"

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

Admit the Version into a Session

Create or choose an Environment, then create a Session. Pin the exact AgentVersion when reproducibility matters:

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.

Get started

Agents

Sessions

Environments

Tools

Context

Automations

Permissions

Security

Billing

Deployment

Create and version an Agent

Create the Agent and Version 1

Create the next AgentVersion

Retrieve one exact AgentVersion

List AgentVersion history

Admit the Version into a Session

​Create the Agent and Version 1

​Create the next AgentVersion

​Retrieve one exact AgentVersion

​List AgentVersion history

​Admit the Version into a Session

Create the Agent and Version 1

Create the next AgentVersion

Retrieve one exact AgentVersion

List AgentVersion history

Admit the Version into a Session