Define your agent

An agent is a reusable, versioned configuration that defines persona and capabilities. It bundles the model, system prompt, tools, MCP servers, and skills that shape how Claude behaves during a session.

Create the agent once as a reusable resource and reference it by ID each time you start a session. Agents are versioned and easier to manage across many sessions.



Agent configuration fields

You can also override model, system, tools, mcp_servers, and skills for a single session without changing the agent. An effort level set inside a per-session model override isn't applied, and because the override replaces the agent's model object in full, a session created with a model override runs at the model's default effort level; to run at a specific effort level, set effort on the agent and don't override model for that session. See Override agent configuration for a session.



Create an agent

The following example defines a coding agent that uses Claude Opus 5 with access to the pre-built agent toolset. The toolset lets the agent write code, read files, search the web, and more. See the agent tools reference for the full list of supported tools.

The examples use curl, the ant CLI, or one of the SDKs. If you haven't set one up, the quickstart covers installation and client setup.

agent=$(ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-5}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}' \
  --format json)

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")

The response echoes your configuration and adds id, type, version, created_at, updated_at, and archived_at fields, and fills in model fields you omit, such as effort, with their defaults. The version starts at 1 and increments each time an update changes the agent.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-5",
    "effort": { "type": "high" },
    "speed": "standard"
  },
  "system": "You are a helpful coding agent.",
  "description": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "permission_policy": { "type": "always_allow" }
      }
    }
  ],
  "skills": [],
  "mcp_servers": [],
  "multiagent": null,
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

The default_config on the toolset shows its default permission policy, always_allow, which applies unless you configure one.



Pin the inference geo

Like speed and effort, inference_geo is set through the object form of model: pass model as an object and set inference_geo alongside id. The field accepts "us" or "global". When it's unset, each model request follows the workspace's default inference geo at the time it's served. See Data residency for the workspace-level geo controls and pricing.

The following example pins an agent to US inference and prints the inference_geo value echoed in the response's model object:

agent=$(ant beta:agents create \
  --name "Geo-pinned assistant" \
  --model '{id: claude-opus-5, inference_geo: us}' \
  --system "You are a helpful assistant." \
  --format json)

echo "Inference geo: $(jq -r '.model.inference_geo' <<< "$agent")"

An inference_geo pin is validated against the workspace's allowed_inference_geos when the agent is saved, when a session is created from it, and on every turn the session serves. If the workspace allowlist narrows so a pin is no longer allowed, new sessions can't be created from the agent and running sessions refuse further turns; pins are never exempted, because workspaces rely on them for compliance and data residency.

Setting inference_geo on a model that doesn't support geographic inference pinning returns a 400 error; see Model availability for the models that do. In a multiagent configuration, the coordinator's pin and every roster member's must all be set to the same value or all be unset; see Multiagent orchestration. To change or clear the pin later, update the agent's model object; supplying model without inference_geo clears it, as described under Update semantics.



Update an agent

Updating an agent generates a new version when the configuration changes. The version field is optional: supply it for optimistic concurrency (a mismatch returns a 409), or omit it to apply the update unconditionally (last write wins). Updates to archived agents are rejected.

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --system "You are a helpful coding agent. Always write tests."

The preceding example supplies version from the create response, so the update only applies if nothing else has changed the agent since you read it. To apply an update unconditionally, omit version from the request:

updated_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "description": "Writes and reviews code."
  }')

echo "New version: $(jq -r '.version' <<< "$updated_agent")"



Update semantics

• version is optional and must be at least 1 when supplied. When supplied, the request returns a 409 if it doesn't match the agent's current version, even when the fields you send already match the stored values; re-read the agent and retry. When omitted, the update applies unconditionally and the most recent update silently replaces any concurrent one, with no error to either caller. Supplying version is the recommended default for interactive callers, and omitting it fits declarative apply loops, such as a CI job that syncs checked-in agent definitions, where the loop owns the agent.

• Omitted fields are preserved. You only need to include the fields you want to change.

• Scalar fields (model, system, name, description) are replaced with the new value. system and description can be cleared by passing null. model and name are mandatory and cannot be cleared. Within a model object you supply, effort is the sole exception: if the model id is unchanged, omitting effort leaves the stored effort level unchanged. If you change the model id, an omitted effort resets to the new model's default. Other model fields are replaced along with the object: supplying model without inference_geo clears the agent's inference geo pin.

• Array fields (tools, mcp_servers, skills) are fully replaced by the new array. To clear an array field entirely, pass null or an empty array.

• multiagent is replaced as a whole, including its agents roster. Pass null to clear it.

• Metadata is merged at the key level. Keys you provide are added or updated. Keys you omit are preserved. To delete a specific key, set its value to null.

• No-op detection. If the update produces no change relative to the current version, no new version is created and the existing version is returned.

• Coordinator rosters are not updated. Coordinators that reference this agent in their multiagent.agents roster keep the version that was pinned when the coordinator was created or last updated, even if the reference omits version. To delegate to the new version, update the coordinator so its roster references it.



Agent lifecycle



List versions

Fetch the full version history to track how an agent has changed over time. Results are paginated, and the SDK examples fetch every page automatically.

ant beta:agents:versions list --agent-id "$AGENT_ID"



Archive an agent

Archiving makes the agent read-only and cannot be undone. Existing sessions continue to run, but new sessions cannot reference the agent. The response sets archived_at to the archive timestamp.

ant beta:agents archive --agent-id "$AGENT_ID"



Next steps