Подагенты в SDK

Подагенты — это отдельные экземпляры агентов, которые ваш основной агент может создавать для обработки сосредоточенных подзадач. Используйте подагентов для изоляции контекста при выполнении сосредоточенных подзадач, параллельного запуска нескольких анализов и применения специализированных инструкций без перегрузки основного промпта агента.

Это руководство объясняет, как определять и использовать подагентов в SDK с помощью параметра agents.

Обзор

Вы можете создавать подагентов тремя способами:

• Программно: используйте параметр agents в ваших опциях query() (TypeScript, Python)
• На основе файловой системы: определяйте агентов как файлы markdown в директориях .claude/agents/ (см. определение подагентов как файлов)
• Встроенные универсальные: Claude может вызывать встроенного подагента general-purpose в любое время через инструмент Task без необходимости что-либо определять

Это руководство сосредоточено на программном подходе, который рекомендуется для приложений SDK.

Когда вы определяете подагентов, Claude решает, вызывать ли их на основе поля description каждого подагента. Напишите четкие описания, которые объясняют, когда следует использовать подагента, и Claude автоматически делегирует соответствующие задачи. Вы также можете явно запросить подагента по имени в вашем промпте (например, "Используй агента code-reviewer для...").

Преимущества использования подагентов

Управление контекстом

Подагенты поддерживают отдельный контекст от основного агента, предотвращая перегрузку информацией и сохраняя взаимодействия сосредоточенными. Эта изоляция гарантирует, что специализированные задачи не загрязняют основной контекст разговора нерелевантными деталями.

Пример: подагент research-assistant может исследовать десятки файлов и страниц документации без засорения основного разговора всеми промежуточными результатами поиска, возвращая только релевантные находки.

Параллелизация

Несколько подагентов могут работать одновременно, значительно ускоряя сложные рабочие процессы.

Пример: во время проверки кода вы можете одновременно запустить подагентов style-checker, security-scanner и test-coverage, сократив время проверки с минут до секунд.

Специализированные инструкции и знания

Каждый подагент может иметь адаптированные системные промпты со специфической экспертизой, лучшими практиками и ограничениями.

Пример: подагент database-migration может иметь подробные знания о лучших практиках SQL, стратегиях отката и проверках целостности данных, которые были бы ненужным шумом в инструкциях основного агента.

Ограничения инструментов

Подагенты могут быть ограничены определенными инструментами, снижая риск непредвиденных действий.

Пример: подагент doc-reviewer может иметь доступ только к инструментам Read и Grep, гарантируя, что он может анализировать, но никогда случайно не изменит ваши файлы документации.

Создание подагентов

Программное определение (рекомендуется)

Определяйте подагентов непосредственно в вашем коде, используя параметр agents. Этот пример создает двух подагентов: рецензента кода с доступом только для чтения и средство запуска тестов, которое может выполнять команды. Инструмент Task должен быть включен в allowedTools, так как Claude вызывает подагентов через инструмент Task.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review the authentication module for security issues",
        options=ClaudeAgentOptions(
            # Task tool is required for subagent invocation
            allowed_tools=["Read", "Grep", "Glob", "Task"],
            agents={
                "code-reviewer": AgentDefinition(
                    # description tells Claude when to use this subagent
                    description="Expert code review specialist. Use for quality, security, and maintainability reviews.",
                    # prompt defines the subagent's behavior and expertise
                    prompt="""You are a code review specialist with expertise in security, performance, and best practices.

When reviewing code:
- Identify security vulnerabilities
- Check for performance issues
- Verify adherence to coding standards
- Suggest specific improvements

Be thorough but concise in your feedback.""",
                    # tools restricts what the subagent can do (read-only here)
                    tools=["Read", "Grep", "Glob"],
                    # model overrides the default model for this subagent
                    model="sonnet"
                ),
                "test-runner": AgentDefinition(
                    description="Runs and analyzes test suites. Use for test execution and coverage analysis.",
                    prompt="""You are a test execution specialist. Run tests and provide clear analysis of results.

Focus on:
- Running test commands
- Analyzing test output
- Identifying failing tests
- Suggesting fixes for failures""",
                    # Bash access lets this subagent run test commands
                    tools=["Bash", "Read", "Grep"]
                )
            }
        )
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Конфигурация AgentDefinition

Определение на основе файловой системы (альтернатива)

Вы также можете определять подагентов как файлы markdown в директориях .claude/agents/. См. документацию подагентов Claude Code для деталей этого подхода. Программно определенные агенты имеют приоритет над агентами на основе файловой системы с тем же именем.

Вызов подагентов

Автоматический вызов

Claude автоматически решает, когда вызывать подагентов на основе задачи и поля description каждого подагента. Например, если вы определяете подагента performance-optimizer с описанием "Performance optimization specialist for query tuning", Claude вызовет его, когда ваш промпт упоминает оптимизацию запросов.

Напишите четкие, специфические описания, чтобы Claude мог сопоставить задачи с правильным подагентом.

Явный вызов

Чтобы гарантировать, что Claude использует определенного подагента, упомяните его по имени в вашем промпте:

"Use the code-reviewer agent to check the authentication module"

Это обходит автоматическое сопоставление и напрямую вызывает названного подагента.

Динамическая конфигурация агента

Вы можете создавать определения агентов динамически на основе условий во время выполнения. Этот пример создает рецензента безопасности с разными уровнями строгости, используя более мощную модель для строгих проверок.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

# Factory function that returns an AgentDefinition
# This pattern lets you customize agents based on runtime conditions
def create_security_agent(security_level: str) -> AgentDefinition:
    is_strict = security_level == "strict"
    return AgentDefinition(
        description="Security code reviewer",
        # Customize the prompt based on strictness level
        prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...",
        tools=["Read", "Grep", "Glob"],
        # Key insight: use a more capable model for high-stakes reviews
        model="opus" if is_strict else "sonnet"
    )

async def main():
    # The agent is created at query time, so each request can use different settings
    async for message in query(
        prompt="Review this PR for security issues",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob", "Task"],
            agents={
                # Call the factory with your desired configuration
                "security-reviewer": create_security_agent("strict")
            }
        )
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Обнаружение вызова подагента

Подагенты вызываются через инструмент Task. Чтобы обнаружить, когда вызывается подагент, проверьте блоки tool_use с name: "Task". Сообщения из контекста подагента включают поле parent_tool_use_id.

Этот пример проходит через потоковые сообщения, логируя, когда вызывается подагент и когда последующие сообщения исходят из контекста выполнения этого подагента.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Use the code-reviewer agent to review this codebase",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Task"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Expert code reviewer.",
                    prompt="Analyze code quality and suggest improvements.",
                    tools=["Read", "Glob", "Grep"]
                )
            }
        )
    ):
        # Check for subagent invocation in message content
        if hasattr(message, 'content') and message.content:
            for block in message.content:
                if getattr(block, 'type', None) == 'tool_use' and block.name == 'Task':
                    print(f"Subagent invoked: {block.input.get('subagent_type')}")

        # Check if this message is from within a subagent's context
        if hasattr(message, 'parent_tool_use_id') and message.parent_tool_use_id:
            print("  (running inside subagent)")

        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Возобновление подагентов

Подагенты можно возобновить, чтобы продолжить с того места, где они остановились. Возобновленные подагенты сохраняют полную историю разговора, включая все предыдущие вызовы инструментов, результаты и рассуждения. Подагент продолжает работу ровно с того места, где он остановился, а не начинает заново.

Когда подагент завершается, Claude получает его ID агента в результате инструмента Task. Чтобы программно возобновить подагента:

1. Захватите ID сессии: извлеките session_id из сообщений во время первого запроса
2. Извлеките ID агента: разберите agentId из содержимого сообщения
3. Возобновите сессию: передайте resume: sessionId в опциях второго запроса и включите ID агента в ваш промпт

Пример ниже демонстрирует этот процесс: первый запрос запускает подагента и захватывает ID сессии и ID агента, затем второй запрос возобновляет сессию, чтобы задать вопрос для уточнения, требующий контекста из первого анализа.

import { query, type SDKMessage } from '@anthropic-ai/claude-agent-sdk';

// Helper to extract agentId from message content
// Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.)
function extractAgentId(message: SDKMessage): string | undefined {
  if (!('message' in message)) return undefined;
  // Stringify the content so we can search it without traversing nested blocks
  const content = JSON.stringify(message.message.content);
  const match = content.match(/agentId:\s*([a-f0-9-]+)/);
  return match?.[1];
}

let agentId: string | undefined;
let sessionId: string | undefined;

// First invocation - use the Explore agent to find API endpoints
for await (const message of query({
  prompt: "Use the Explore agent to find all API endpoints in this codebase",
  options: { allowedTools: ['Read', 'Grep', 'Glob', 'Task'] }
})) {
  // Capture session_id from ResultMessage (needed to resume this session)
  if ('session_id' in message) sessionId = message.session_id;
  // Search message content for the agentId (appears in Task tool results)
  const extractedId = extractAgentId(message);
  if (extractedId) agentId = extractedId;
  // Print the final result
  if ('result' in message) console.log(message.result);
}

// Second invocation - resume and ask follow-up
if (agentId && sessionId) {
  for await (const message of query({
    prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`,
    options: { allowedTools: ['Read', 'Grep', 'Glob', 'Task'], resume: sessionId }
  })) {
    if ('result' in message) console.log(message.result);
  }
}

Транскрипты подагентов сохраняются независимо от основного разговора:

• Компактирование основного разговора: когда основной разговор компактируется, транскрипты подагентов не затрагиваются. Они хранятся в отдельных файлах.
• Сохранение сессии: транскрипты подагентов сохраняются в пределах их сессии. Вы можете возобновить подагента после перезагрузки Claude Code, возобновив ту же сессию.
• Автоматическая очистка: транскрипты очищаются на основе параметра cleanupPeriodDays (по умолчанию: 30 дней).

Ограничения инструментов

Подагенты могут иметь ограниченный доступ к инструментам через поле tools:

• Опустить поле: агент наследует все доступные инструменты (по умолчанию)
• Указать инструменты: агент может использовать только перечисленные инструменты

Этот пример создает агента анализа только для чтения, который может изучать код, но не может изменять файлы или запускать команды.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Analyze the architecture of this codebase",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob", "Task"],
            agents={
                "code-analyzer": AgentDefinition(
                    description="Static code analysis and architecture review",
                    prompt="""You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.""",
                    # Read-only tools: no Edit, Write, or Bash access
                    tools=["Read", "Grep", "Glob"]
                )
            }
        )
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Общие комбинации инструментов

Устранение неполадок

Claude не делегирует подагентам

Если Claude выполняет задачи напрямую вместо делегирования вашему подагенту:

1. Включите инструмент Task: подагенты вызываются через инструмент Task, поэтому он должен быть в allowedTools
2. Используйте явное указание: упомяните подагента по имени в вашем промпте (например, "Use the code-reviewer agent to...")
3. Напишите четкое описание: объясните ровно, когда следует использовать подагента, чтобы Claude мог правильно сопоставить задачи

Агенты на основе файловой системы не загружаются

Агенты, определенные в .claude/agents/, загружаются только при запуске. Если вы создаете новый файл агента во время работы Claude Code, перезагрузите сессию, чтобы загрузить его.

Windows: сбои при длинных промптах

В Windows подагенты с очень длинными промптами могут не работать из-за ограничений длины командной строки (8191 символов). Держите промпты краткими или используйте агентов на основе файловой системы для сложных инструкций.

Связанная документация

• Подагенты Claude Code: полная документация подагентов, включая определения на основе файловой системы
• Обзор SDK: начало работы с Claude Agent SDK