Субагенты в Claude Agent SDK — это специализированные ИИ, которые управляются основным агентом. Используйте субагентов для управления контекстом и распараллеливания. Это руководство объясняет, как определять и использовать субагентов в SDK с помощью параметра agents.

​
Обзор

Субагенты могут быть определены двумя способами при использовании SDK:
  1. Программно - Используя параметр agents в опциях вашего query() (рекомендуется для SDK приложений)
  2. На основе файловой системы - Размещая markdown файлы с YAML frontmatter в специальных директориях (.claude/agents/)
Это руководство в основном фокусируется на программном подходе с использованием параметра agents, который обеспечивает более интегрированный опыт разработки для SDK приложений.

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

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

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

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

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

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

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

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

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

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

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

Определите субагентов непосредственно в вашем коде, используя параметр agents: 
import { query } from '@anthropic/claude-code-sdk';

const result = query({
  prompt: "Проверьте модуль аутентификации на предмет проблем безопасности",
  options: {
    agents: {
      'code-reviewer': {
        description: 'Эксперт-специалист по ревью кода. Используйте для проверки качества, безопасности и сопровождаемости.',
        prompt: `Вы специалист по ревью кода с экспертизой в области безопасности, производительности и лучших практик.

При ревью кода:
- Выявляйте уязвимости безопасности
- Проверяйте проблемы производительности
- Проверяйте соблюдение стандартов кодирования
- Предлагайте конкретные улучшения

Будьте тщательными, но краткими в своих отзывах.`,
        tools: ['Read', 'Grep', 'Glob'],
        model: 'sonnet'
      },
      'test-runner': {
        description: 'Запускает и анализирует тестовые наборы. Используйте для выполнения тестов и анализа покрытия.',
        prompt: `Вы специалист по выполнению тестов. Запускайте тесты и предоставляйте четкий анализ результатов.

Сосредоточьтесь на:
- Запуске тестовых команд
- Анализе вывода тестов
- Выявлении неудачных тестов
- Предложении исправлений для сбоев`,
        tools: ['Bash', 'Read', 'Grep'],
      }
    }
  }
});

for await (const message of result) {
  console.log(message);
}

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

ПолеТипОбязательноОписание
descriptionstringДаОписание на естественном языке о том, когда использовать этого агента
promptstringДаСистемный промпт агента, определяющий его роль и поведение
toolsstring[]НетМассив разрешенных имен инструментов. Если опущено, наследует все инструменты
model'sonnet' | 'opus' | 'haiku' | 'inherit'НетПереопределение модели для этого агента. По умолчанию основная модель, если опущено

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

Вы также можете определить субагентов как markdown файлы в специальных директориях:
  • Уровень проекта: .claude/agents/*.md - Доступны только в текущем проекте
  • Уровень пользователя: ~/.claude/agents/*.md - Доступны во всех проектах
Каждый субагент — это markdown файл с YAML frontmatter: 
---
name: code-reviewer
description: Эксперт-специалист по ревью кода. Используйте для проверки качества, безопасности и сопровождаемости.
tools: Read, Grep, Glob, Bash
---

Системный промпт вашего субагента идет здесь. Это определяет роль субагента,
возможности и подход к решению проблем.
Примечание: Программно определенные агенты (через параметр agents) имеют приоритет над агентами на основе файловой системы с тем же именем.

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

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

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

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

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

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

SDK будет автоматически вызывать подходящих субагентов на основе контекста задачи. Убедитесь, что поле description вашего агента четко указывает, когда его следует использовать: 
const result = query({
  prompt: "Оптимизируйте запросы к базе данных в слое API",
  options: {
    agents: {
      'performance-optimizer': {
        description: 'Используйте ПРОАКТИВНО, когда изменения кода могут повлиять на производительность. ДОЛЖЕН ИСПОЛЬЗОВАТЬСЯ для задач оптимизации.',
        prompt: 'Вы специалист по оптимизации производительности...',
        tools: ['Read', 'Edit', 'Bash', 'Grep'],
        model: 'sonnet'
      }
    }
  }
});

​
Явный вызов

Пользователи могут запрашивать конкретных субагентов в своих промптах: 
const result = query({
  prompt: "Используйте агента code-reviewer для проверки модуля аутентификации",
  options: {
    agents: {
      'code-reviewer': {
        description: 'Эксперт-специалист по ревью кода',
        prompt: 'Вы ревьюер кода, сосредоточенный на безопасности...',
        tools: ['Read', 'Grep', 'Glob']
      }
    }
  }
});

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

Вы можете динамически настраивать агентов в зависимости от потребностей вашего приложения: 
import { query, type AgentDefinition } from '@anthropic/claude-code-sdk';

function createSecurityAgent(securityLevel: 'basic' | 'strict'): AgentDefinition {
  return {
    description: 'Ревьюер кода по безопасности',
    prompt: `Вы ${securityLevel === 'strict' ? 'строгий' : 'сбалансированный'} ревьюер безопасности...`,
    tools: ['Read', 'Grep', 'Glob'],
    model: securityLevel === 'strict' ? 'opus' : 'sonnet'
  };
}

const result = query({
  prompt: "Проверьте этот PR на предмет проблем безопасности",
  options: {
    agents: {
      'security-reviewer': createSecurityAgent('strict')
    }
  }
});

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

Субагенты могут иметь ограниченный доступ к инструментам через поле tools:
  • Опустить поле - Агент наследует все доступные инструменты (по умолчанию)
  • Указать инструменты - Агент может использовать только перечисленные инструменты
Пример агента только для чтения и анализа: 
const result = query({
  prompt: "Проанализируйте архитектуру этой кодовой базы",
  options: {
    agents: {
      'code-analyzer': {
        description: 'Статический анализ кода и обзор архитектуры',
        prompt: `Вы аналитик архитектуры кода. Анализируйте структуру кода,
выявляйте паттерны и предлагайте улучшения без внесения изменений.`,
        tools: ['Read', 'Grep', 'Glob']  // Нет разрешений на запись или выполнение
      }
    }
  }
});

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

Агенты только для чтения (анализ, ревью): 
tools: ['Read', 'Grep', 'Glob']
Агенты выполнения тестов: 
tools: ['Bash', 'Read', 'Grep']
Агенты модификации кода: 
tools: ['Read', 'Edit', 'MultiEdit', 'Write', 'Grep', 'Glob']

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