Субагенты в SDK

Субагенты в 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-ai/claude-agent-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

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

Вы также можете определить субагентов как 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-ai/claude-agent-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', 'Write', 'Grep', 'Glob']

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

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