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

# Edit Agent instructions safely

> Update an Agent's instructions, create a new immutable AgentVersion, and keep existing Sessions frozen.

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.

<Warning>
  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](/getting-started/status) before making availability part of your application's contract.
</Warning>

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

<CodeGroup>
  ```sh CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  checkfu agent update "$CHECKFU_AGENT_ID" --json --input '{
    "version": 3,
    "system": "Answer briefly. Ask for approval before making an external change."
  }'
  ```

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

  ```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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.",
  })
  ```
</CodeGroup>

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:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/guides/author-an-agent-project) for the current
source-authoring workflow over the same canonical Agent operations.

Put user-specific facts and preferences in [Memory](/concepts/memory) rather
than cloning instructions per user. Put reusable procedures in
[Skills](/concepts/capabilities). Keep the Agent instructions focused on
behavior shared by every Session admitted from that AgentVersion.

<CardGroup cols={2}>
  <Card title="Agents and Versions" icon="robot" href="/concepts/agents">
    Review the mutable Agent and immutable AgentVersion model.
  </Card>

  <Card title="Create and version an Agent" icon="plus" href="/guides/create-and-version-an-agent">
    See the full create, update, retrieve, and Session admission flow.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.