<!--
name: 'Tool Description: Agent'
description: Default SDK built-in tool description and input schema for Agent.
sdkPackage: '@anthropic-ai/claude-agent-sdk@0.3.168'
claudeCodeVersion: '2.1.168'
tool: "Agent"
-->
# Tool Description: Agent

## Metadata

- Request location: `tools[]`
- Tool name: `Agent`
- Input schema properties: `description`, `prompt`, `subagent_type`, `model`, `run_in_background`, `isolation`

## Description

Launch a new agent to handle complex, multi-step tasks. Each agent type has specific capabilities and tools available to it.

Available agent types and the tools they have access to:
- claude: Catch-all for any task that doesn't fit a more specific agent. FleetView's default when no agent name is typed. (Tools: *)
- Explore: Read-only search agent for broad fan-out searches — when answering means sweeping many files, directories, or naming conventions and you only need the conclusion, not the file dumps. It reads excerpts rather than whole files, so it locates code; it doesn't review or audit it. Specify search breadth: "medium" for moderate exploration, "very thorough" for multiple locations and naming conventions. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
- general-purpose: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. (Tools: *)
- Plan: Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
- statusline-setup: Use this agent to configure the user's Claude Code status line setting. (Tools: Read, Edit)

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 message is returned to you as the tool result; it 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.
- `isolation: "worktree"` gives the agent its own git worktree (auto-cleaned if unchanged).
- `run_in_background: true` runs the agent asynchronously; you'll be notified when it completes.
- When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently

## Input Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "description": {
      "description": "A short (3-5 word) description of the task",
      "type": "string"
    },
    "prompt": {
      "description": "The task for the agent to perform",
      "type": "string"
    },
    "subagent_type": {
      "description": "The type of specialized agent to use for this task",
      "type": "string"
    },
    "model": {
      "description": "Optional model override for this agent. Takes precedence over the agent definition's model frontmatter. If omitted, uses the agent definition's model, or inherits from the parent.",
      "type": "string",
      "enum": [
        "sonnet",
        "opus",
        "haiku"
      ]
    },
    "run_in_background": {
      "description": "Set to true to run this agent in the background. You will be notified when it completes.",
      "type": "boolean"
    },
    "isolation": {
      "description": "Isolation mode. \"worktree\" creates a temporary git worktree so the agent works on an isolated copy of the repo.",
      "type": "string",
      "enum": [
        "worktree"
      ]
    }
  },
  "required": [
    "description",
    "prompt"
  ],
  "additionalProperties": false
}
```

## Token Impact

<!-- TOKEN_COUNT_START -->
- Complete definition estimated tokens: **1,263**
- Measurement: captured tool object serialized independently as JSON text against the common baseline
- Additivity: independent, non-additive estimate
<!-- TOKEN_COUNT_END -->