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

Create an agent

The following example defines a coding agent that uses Claude Sonnet 4.6 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 response echoes your configuration and adds id, version, created_at, updated_at, and archived_at fields. The version starts at 1 and increments each time you update the agent.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-sonnet-4-6",
    "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": [],
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

Update an agent

Updating an agent generates a new version. Pass the current version to ensure you're updating from a known state.

Update semantics

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

• Scalar fields (model, system, name, etc.) are replaced with the new value. system and description can be cleared by passing null. model and name are mandatory and cannot be cleared.

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

Agent lifecycle

List versions

Fetch the full version history to track how an agent has changed over time.

Archive an agent

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

Next steps

• Configure tools to customize which capabilities the agent can use.
• Attach skills for domain-specific expertise.
• Start a session that references your agent.

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 an empty string.