Субагенты в SDK

Работа с субагентами в Claude Code SDK

Субагенты в 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.

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

• Основное руководство по субагентам - Исчерпывающая документация по субагентам
• Руководство по конфигурации SDK - Обзор подходов к конфигурации
• Настройки - Справочник по файлам конфигурации
• Слэш-команды - Создание пользовательских команд