agents.
Обзор
Субагенты могут быть определены двумя способами при использовании SDK:- Программно - Используя параметр
agentsв опциях вашегоquery()(рекомендуется для SDK приложений) - На основе файловой системы - Размещая markdown файлы с YAML frontmatter в специальных директориях (
.claude/agents/)
agents, который обеспечивает более интегрированный опыт разработки для SDK приложений.
Преимущества использования субагентов
Управление контекстом
Субагенты поддерживают отдельный контекст от основного агента, предотвращая информационную перегрузку и сохраняя взаимодействия сфокусированными. Эта изоляция гарантирует, что специализированные задачи не загрязняют основной контекст разговора ненужными деталями. Пример: Субагентresearch-assistant может исследовать десятки файлов и страниц документации, не засоряя основной разговор всеми промежуточными результатами поиска - возвращая только релевантные находки.
Распараллеливание
Несколько субагентов могут работать одновременно, значительно ускоряя сложные рабочие процессы. Пример: Во время проверки кода вы можете запустить субагентовstyle-checker, security-scanner и test-coverage одновременно, сокращая время проверки с минут до секунд.
Специализированные инструкции и знания
Каждый субагент может иметь индивидуальные системные промпты с конкретной экспертизой, лучшими практиками и ограничениями. Пример: Субагентdatabase-migration может иметь детальные знания о лучших практиках SQL, стратегиях отката и проверках целостности данных, которые были бы ненужным шумом в инструкциях основного агента.
Ограничения инструментов
Субагенты могут быть ограничены конкретными инструментами, снижая риск непреднамеренных действий. Пример: Субагентdoc-reviewer может иметь доступ только к инструментам Read и Grep, гарантируя, что он может анализировать, но никогда случайно не изменит ваши файлы документации.
Создание субагентов
Программное определение (Рекомендуется)
Определите субагентов непосредственно в вашем коде, используя параметрagents:
Конфигурация AgentDefinition
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
description | string | Да | Описание на естественном языке о том, когда использовать этого агента |
prompt | string | Да | Системный промпт агента, определяющий его роль и поведение |
tools | string[] | Нет | Массив разрешенных имен инструментов. Если опущено, наследует все инструменты |
model | 'sonnet' | 'opus' | 'haiku' | 'inherit' | Нет | Переопределение модели для этого агента. По умолчанию основная модель, если опущено |
Определение на основе файловой системы (Альтернатива)
Вы также можете определить субагентов как markdown файлы в конкретных директориях:- Уровень проекта:
.claude/agents/*.md- Доступны только в текущем проекте - Уровень пользователя:
~/.claude/agents/*.md- Доступны во всех проектах
agents) имеют приоритет над агентами на основе файловой системы с тем же именем.
Как SDK использует субагентов
При использовании Claude Agent SDK субагенты могут быть определены программно или загружены из файловой системы. Claude будет:- Загружать программные агенты из параметра
agentsв ваших опциях - Автоматически обнаруживать агенты файловой системы из директорий
.claude/agents/(если не переопределено) - Вызывать их автоматически на основе сопоставления задач и
descriptionагента - Использовать их специализированные промпты и ограничения инструментов
- Поддерживать отдельный контекст для каждого вызова субагента
agents) имеют приоритет над агентами на основе файловой системы с тем же именем.
Примеры субагентов
Для комплексных примеров субагентов, включая проверщиков кода, исполнителей тестов, отладчиков и аудиторов безопасности, смотрите основное руководство по субагентам. Руководство включает детальные конфигурации и лучшие практики для создания эффективных субагентов.Паттерны интеграции SDK
Автоматический вызов
SDK будет автоматически вызывать подходящих субагентов на основе контекста задачи. Убедитесь, что полеdescription вашего агента четко указывает, когда его следует использовать:
Явный вызов
Пользователи могут запросить конкретных субагентов в своих промптах:Динамическая конфигурация агентов
Вы можете динамически настраивать агентов в зависимости от потребностей вашего приложения:Ограничения инструментов
Субагенты могут иметь ограниченный доступ к инструментам через полеtools:
- Опустите поле - Агент наследует все доступные инструменты (по умолчанию)
- Укажите инструменты - Агент может использовать только перечисленные инструменты
Общие комбинации инструментов
Агенты только для чтения (анализ, проверка):Связанная документация
- Основное руководство по субагентам - Комплексная документация по субагентам
- Обзор SDK - Обзор Claude Agent SDK
- Настройки - Справочник по файлу конфигурации
- Слэш-команды - Создание пользовательских команд