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.

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

Build and customize

Integrate and deliver

Operate and evaluate

Migrate and own execution

Examples

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