Plain text · sha256 645950071bae
The description, rendered
This renders the markdown inside the description, so it isn’t quite the description itself.The raw view and the plain text are the bytes as they were sent.
Launch a new agent to handle complex, multi-step tasks. Each agent type has specific capabilities and tools available to it.
Available agent types are listed in <system-reminder> messages in the conversation.
When using the Agent tool, specify a subagent_type parameter to select which agent type to use. If omitted, the general-purpose agent is used.
When to use
Reach for this when the task matches an available agent type, when you have independent work to run in parallel, or when answering would mean reading across several files — delegate it and you keep the conclusion, not the file dumps. For a single-fact lookup where you already know the file, symbol, or value, search directly. Once you've delegated a search, don't also run it yourself — wait for the result.
- The agent's final report is not shown to the user — relay what matters.
- Use SendMessage with the agent's ID or name to continue a previously spawned agent with its context intact; a new Agent call starts fresh.
- Each agent type's model, reasoning effort, and tools come from its definition (
.claude/agents/*.mdfrontmatter or SDKagents). isolation: "worktree"gives the agent its own git worktree (auto-cleaned if unchanged).- Subagents run in the background by default; you'll be notified when one completes. Pass
run_in_background: falseonly when your very next action depends on the result and nothing else could usefully happen while it runs — otherwise background it so the user can interject. Never fabricate or predict a pending agent's results — the notification is never something you write yourself; if the user asks before it arrives, say it's still running.
What it accepts
6 parameters The JSON parameter schema sent beside this description, 1,696 characters of it. Name, type, then whether the client marked it required.description
string
required
A short (3-5 word) description of the task
isolation
worktree | remote
optional
Isolation mode. "worktree" creates a temporary git worktree so the agent works on an isolated copy of the repo. "remote" launches the agent in a remote cloud environment (always runs in background; availability is gated).
model
sonnet | opus | haiku | fable
optional
Optional model override for this agent. Takes precedence over the agent definition's model frontmatter and the configured default subagent model. If omitted, uses the agent definition's model, else the default (inherits from the parent unless a default subagent model is configured). Ignored for subagent_type: "fork" — forks always inherit the parent model.
prompt
string
required
The task for the agent to perform
run_in_background
boolean
optional
Agents run in the background by default; you will be notified when one completes. Set to false only when your very next action depends on this agent's result and nothing else could usefully happen while it runs — otherwise leave it in the background so the user can hand you other work.
subagent_type
string
optional
The type of specialized agent to use for this task
sha256 9d0b512b84e4 · the schema as the client sent it:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"description": {
"description": "A short (3-5 word) description of the task",
"type": "string"
},
"isolation": {
"description": "Isolation mode. \"worktree\" creates a temporary git worktree so the agent works on an isolated copy of the repo. \"remote\" launches the agent in a remote cloud environment (always runs in background; availability is gated).",
"enum": [
"worktree",
"remote"
],
"type": "string"
},
"model": {
"description": "Optional model override for this agent. Takes precedence over the agent definition's model frontmatter and the configured default subagent model. If omitted, uses the agent definition's model, else the default (inherits from the parent unless a default subagent model is configured). Ignored for subagent_type: \"fork\" \u2014 forks always inherit the parent model.",
"enum": [
"sonnet",
"opus",
"haiku",
"fable"
],
"type": "string"
},
"prompt": {
"description": "The task for the agent to perform",
"type": "string"
},
"run_in_background": {
"description": "Agents run in the background by default; you will be notified when one completes. Set to false only when your very next action depends on this agent's result and nothing else could usefully happen while it runs \u2014 otherwise leave it in the background so the user can hand you other work.",
"type": "boolean"
},
"subagent_type": {
"description": "The type of specialized agent to use for this task",
"type": "string"
}
},
"required": [
"description",
"prompt"
],
"type": "object"
}