Define your agent

Create a reusable, versioned agent configuration.

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

Field	Description
`name`	Required. A human-readable name for the agent.
`model`	Required. The Claude model that powers the agent. Accepts a model ID string or an object, for example `{"id": "claude-opus-5"}`. Claude 4.5 and later models are supported. The object form also accepts `speed`, `effort`, and `inference_geo` fields; see the tips under Create an agent, Effort levels, and Pin the inference geo.
`system`	A system prompt that defines the agent's behavior and persona. The system prompt is distinct from user messages, which should describe the work to be done.
`tools`	The tools available to the agent. Combines pre-built agent tools, MCP tools, and custom tools.
`mcp_servers`	MCP servers that provide standardized third-party capabilities.
`skills`	Skills that supply domain-specific context with progressive disclosure.
`multiagent`	A coordinator declaration listing the agents this agent can delegate to. See Multiagent orchestration.
`description`	A description of what the agent does.
`metadata`	Arbitrary key-value pairs for your own tracking.

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.

Agent configuration fields

Agent configuration fields