Edit Agent instructions safely

An Agent’s instructions are authored configuration, not application code. Changing them does not rebuild an image, restart a runner, or replace a harness. A material update to the mutable Agent creates the next immutable AgentVersion automatically. The safety boundary is simple:

future Sessions that select the current Agent resolve the new AgentVersion;
existing Sessions keep the AgentVersion frozen at admission;
an earlier AgentVersion never changes.

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.

Update the instructions

Start with the Version currently returned by the Agent. Passing that Version back as version prevents a stale editor from overwriting a newer change.

checkfu agent update "$CHECKFU_AGENT_ID" --json --input '{
  "version": 3,
  "system": "Answer briefly. Ask for approval before making an external change."
}'

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": 3,
    "system": "Answer briefly. Ask for approval before making an external change."
  }'

const current = await checkfu.agents.retrieve(agentId)

const updated = await checkfu.agents.update(agentId, {
  version: current.version,
  system: "Answer briefly. Ask for approval before making an external change.",
})

When Version 3 is current, this material change returns Version 4. Repeating the same effective update is a no-op and does not create Version 5. Omitted fields are preserved. Set system to null or an empty string to clear it.

Why running Sessions do not change

A Session resolves its Agent selector once at admission. Checkfu records the resolved AgentVersion with the Session’s admitted authority and uses that immutable configuration throughout its Turns, Runs, child Runs, recovery, and continuation. That freeze gives every outcome, event, Usage record, and approval a precise configuration to refer to. Live propagation would make a Run depend on whatever the Agent happened to contain at an unrecorded instant. To use the new instructions, create a new Session that selects the Agent’s current Version or pins the new Version explicitly:

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

Choose one authoring owner

Authoring interfaces are not owners. Your builder, the Checkfu UI, HTTP API, SDK, CLI, and MCP all invoke the same Agent operations. A direct write is available while the Agent is unclaimed. A Git- or YAML-backed source process may keep reconciling it only when that process is the Agent’s one active desired-state owner. Use the optimistic-concurrency version guard to reject stale edits. Do not mistake that guard for an ownership transfer. References and proposals claim nothing, and adopting or transferring an existing Agent requires an explicit, audited handoff. Never run two active reconcilers against the same Agent. See Author an Agent project for the current source-authoring workflow over the same canonical Agent operations. Put user-specific facts and preferences in Memory rather than cloning instructions per user. Put reusable procedures in Skills. Keep the Agent instructions focused on behavior shared by every Session admitted from that AgentVersion.

Agents and Versions

Review the mutable Agent and immutable AgentVersion model.

Create and version an Agent

See the full create, update, retrieve, and Session admission flow.

Get started

Agents

Sessions

Environments

Tools

Context

Automations

Permissions

Security

Billing

Deployment

Edit Agent instructions safely

Update the instructions

Why running Sessions do not change

Choose one authoring owner

Agents and Versions

Create and version an Agent

​Update the instructions

​Why running Sessions do not change

​Choose one authoring owner

Agents and Versions

Create and version an Agent

Update the instructions

Why running Sessions do not change

Choose one authoring owner