Субагенты в Claude Code SDK — это специализированные ИИ, которые управляются основным агентом. Используйте субагентов для управления контекстом и распараллеливания. Это руководство объясняет, как SDK-приложения взаимодействуют с субагентами, созданными через markdown-файлы, и используют их.

​
Обзор

Субагенты создаются исключительно через подход на основе файловой системы путем размещения markdown-файлов с YAML frontmatter в специально предназначенных каталогах. SDK может затем вызывать эти предопределенные субагенты во время выполнения.

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

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

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

​
Распараллеливание

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

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

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

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

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

​
Создание субагентов

Субагенты определяются как markdown-файлы в специальных каталогах:
  • Уровень проекта: .claude/agents/*.md - Доступны только в текущем проекте
  • Уровень пользователя: ~/.claude/agents/*.md - Доступны во всех проектах

​
Формат файла

Каждый субагент — это markdown-файл с YAML frontmatter: 
---
name: code-reviewer
description: Expert code review specialist. Use for quality, security, and maintainability reviews.
tools: Read, Grep, Glob, Bash  # Optional - inherits all tools if omitted
---

Your subagent's system prompt goes here. This defines the subagent's
role, capabilities, and approach to solving problems.

Include specific instructions, best practices, and any constraints
the subagent should follow.

​
Поля конфигурации

ПолеОбязательноеОписание
nameДаУникальный идентификатор, использующий строчные буквы и дефисы
descriptionДаОписание на естественном языке о том, когда использовать этого субагента
toolsНетСписок разрешенных инструментов через запятую. Если опущено, наследует все инструменты

​
Как SDK использует субагентов

При использовании Claude Code SDK субагенты, определенные в файловой системе, автоматически доступны. Claude Code будет:
  1. Автоматически обнаруживать субагентов из каталогов .claude/agents/
  2. Вызывать их автоматически на основе соответствия задач
  3. Использовать их специализированные промпты и ограничения инструментов
  4. Поддерживать отдельный контекст для каждого вызова субагента
SDK соблюдает конфигурацию файловой системы — нет программного способа создавать субагентов во время выполнения. Все субагенты должны быть определены как файлы до выполнения SDK.

​
Примеры субагентов

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

​
Паттерны интеграции SDK

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

SDK будет автоматически вызывать подходящих субагентов на основе контекста задачи. Убедитесь, что поле description вашего субагента четко указывает, когда его следует использовать: 
---
name: performance-optimizer
description: Use PROACTIVELY when code changes might impact performance. MUST BE USED for optimization tasks.
tools: Read, Edit, Bash, Grep
---

​
Явный вызов

Пользователи могут запрашивать конкретных субагентов в своих промптах: 
// При использовании SDK пользователи могут явно запрашивать субагентов:
const result = await query({
  prompt: "Use the code-reviewer subagent to check the authentication module"
});

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

Субагенты могут иметь ограниченный доступ к инструментам через поле tools:
  • Опустить поле - Субагент наследует все доступные инструменты (по умолчанию)
  • Указать инструменты - Субагент может использовать только перечисленные инструменты
Пример субагента анализа только для чтения: 
---
name: code-analyzer
description: Static code analysis and architecture review
tools: Read, Grep, Glob  # No write or execute permissions
---

You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.

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