Серия «Создаём агентов в Claude» — Часть 3 из 3
Финал серии. В первой части разбирали системные промпты. Во второй — собирали автономного агента с инструментами. Теперь — высший уровень: один ИИ-агент управляет командой других ИИ-агентов. У каждого своя специализация, свои инструменты, свой контекст. Мульти-агентные системы — поехали.
Зачем вообще несколько агентов?
Вы — технический директор. Задача: провести аудит безопасности продукта, написать новый модуль и покрыть его тестами. Вы же не делаете всё сами. Ставите задачу безопаснику, разработчику и QA-инженеру — они работают параллельно, а вы собираете результаты.
Мульти-агентная система работает точно так же:
- Оркестратор (менеджер) — получает задачу, разбивает её на части, раздаёт субагентам
- Субагенты (исполнители) — каждый решает свою узкую задачу с минимальным набором инструментов
- Результат — оркестратор собирает ответы, синтезирует финальный результат
Почему не один большой агент? Контекстное окно — не резиновое. Когда один агент пытается одновременно искать информацию, писать код и проверять его, он теряет фокус. Честно говоря, я сам первый раз попробовал запихнуть всё в одного агента — и получил кашу вместо результата. Субагенты решают эту проблему: каждый работает в чистом контексте, сосредоточившись на одном деле.
Когда это оправдано, а когда — лишнее
Не каждая задача требует команду агентов. Вот когда это действительно имеет смысл:
- Задача декомпозируется на независимые части — поиск информации, генерация кода и написание тестов могут идти параллельно
- Нужна специализация — один агент хорош в анализе безопасности, другой в оптимизации, третий в документации
- Контекст переполняется — задача настолько объёмная, что одному агенту не хватает окна контекста
- Нужна скорость — три агента параллельно работают быстрее, чем один последовательно
Когда это избыточно: если задача решается одним промптом за 30 секунд, мульти-агентная архитектура только добавит сложности и стоимости. Не усложняйте ради красоты архитектуры.
Claude Agent SDK: что это и как устроен
Claude Agent SDK — программная библиотека от Anthropic для Python и TypeScript, которая позволяет встроить Claude-агента прямо в ваш код. Это не чат-интерфейс и не CLI — это библиотека, которая запускает полноценный агентный цикл внутри вашего процесса.
Ключевые понятия:
- query() — главная функция. Отправляет задачу агенту и получает поток сообщений по мере работы
- AgentDefinition — описание субагента: его системный промпт, доступные инструменты, модель
- Инструмент Agent — специальный инструмент, через который оркестратор запускает субагентов
- Изоляция контекста — каждый субагент получает чистое окно контекста. Он не видит историю родителя — только свою задачу и свои инструменты
Смотрите, архитектура выглядит так:
┌─────────────────────────────────────┐
│ ОРКЕСТРАТОР (Claude) │
│ Получает задачу, декомпозирует, │
│ запускает субагентов через Agent │
└──────┬──────────┬──────────┬────────┘
│ │ │
▼ ▼ ▼
┌───────────┐ ┌──────────┐ ┌──────────┐
│ Субагент │ │ Субагент │ │ Субагент │
│ Researcher│ │ Coder │ │ Tester │
│ Read,Grep │ │ Read,Edit│ │ Bash,Read│
│ Glob │ │ Write │ │ Grep │
└───────────┘ └──────────┘ └──────────┘
(параллельно, изолированный контекст)
Конкретный пример: агент-оркестратор для код-ревью
Окей, переходим к практике. Допустим, вы хотите автоматизировать полный код-ревью. Оркестратор получает PR, разбивает задачу на три направления и запускает субагентов параллельно.
Шаг 1: Определяем субагентов
from claude_code_sdk import query, ClaudeCodeOptions, AgentDefinition
# Субагент-исследователь: ищет контекст и зависимости
researcher = AgentDefinition(description="Research agent for understanding code context and dependencies",prompt="""Ты — исследователь кодовой базы. Твоя задача:
найти все файлы, связанные с изменённым кодом,
выявить зависимости и потенциальные конфликты.
Дай краткий отчёт: что затронуто, какие модули связаны.""",tools=["Read", "Glob", "Grep"], # только чтениеmodel="sonnet", # быстрая модель для поиска
)
# Субагент-безопасник: ищет уязвимости
security_reviewer = AgentDefinition(description="Security reviewer for finding vulnerabilities in code changes",prompt="""Ты — специалист по безопасности. Проверь код на:
SQL-инъекции, XSS, утечки секретов, небезопасную десериализацию,
проблемы с аутентификацией. Для каждой проблемы укажи файл,
строку и уровень критичности.""",tools=["Read", "Glob", "Grep"],model="opus", # самая мощная модель для безопасности
)
# Субагент-тестировщик: проверяет покрытие тестами
test_analyzer = AgentDefinition(description="Test coverage analyzer for checking if changes are properly tested",prompt="""Ты — QA-инженер. Проверь:
1. Есть ли тесты для изменённых функций?
2. Покрывают ли тесты edge-кейсы?
3. Какие тесты нужно добавить?
Дай конкретные рекомендации с примерами.""",tools=["Read", "Glob", "Grep", "Bash"],model="sonnet",
)
Шаг 2: Запускаем оркестратора
import asyncio
async def run_code_review(pr_description: str):messages = []
async for message in query(prompt=f"""Проведи полное код-ревью для этого PR:
{pr_description}
Используй всех трёх субагентов ПАРАЛЛЕЛЬНО:
1. Запусти researcher — пусть найдёт контекст и зависимости
2. Запусти security-reviewer — пусть проверит безопасность
3. Запусти test-analyzer — пусть оценит тестовое покрытие
Когда все трое ответят, собери единый отчёт:
- Общая оценка (approve / request changes)
- Ключевые находки по каждому направлению
- Приоритизированный список действий""",options=ClaudeCodeOptions(allowed_tools=["Read", "Glob", "Grep", "Agent"],agents={"researcher": researcher,"security-reviewer": security_reviewer,"test-analyzer": test_analyzer,},model="opus", # оркестратор — самый мощный),):if hasattr(message, "content"):print(message.content)
asyncio.run(run_code_review("Добавлен эндпоинт /api/users/export"))
Что происходит под капотом
- Оркестратор (Opus) анализирует задачу
- Вызывает инструмент Agent три раза — Claude запускает все три субагента параллельно
- Каждый субагент работает в изолированном контексте — получает только свой промпт и задачу от оркестратора
- Результаты возвращаются оркестратору как ответы инструмента Agent
- Оркестратор синтезирует финальный отчёт
Альтернативный подход: конфигурация через CLAUDE.md
Если вы работаете в Claude Code (CLI или IDE), субагенты определяются через файлы .md в директории .claude/agents/:
# Файл: .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Security vulnerability scanner for code changes
model: opus
tools:
- Read
- Glob
- Grep
---
You are a security specialist. When invoked, analyze the provided
code for OWASP Top 10 vulnerabilities. Focus on:
- Injection flaws (SQL, XSS, command injection)
- Broken authentication
- Sensitive data exposure
- Security misconfiguration
Report format:
- CRITICAL / HIGH / MEDIUM / LOW
- File path and line number
- Description and remediation
Оркестратор (основной агент Claude Code) автоматически видит этих субагентов и может их вызывать — либо по прямой инструкции пользователя, либо самостоятельно, если описание субагента совпадает с текущей задачей.
Где это сломается: о чём молчат туториалы
Ну, слушайте. Мульти-агентные системы — мощный инструмент, но с серьёзными оговорками. Не буду врать — я на некоторые из этих граблей наступил лично.
Стоимость токенов
Каждый субагент — это отдельное контекстное окно. Три субагента — три полных сессии с моделью. Оркестратор на Opus + три субагента могут легко сжечь сотни тысяч токенов на одну задачу. Впечатлило меня это в первый раз не в хорошем смысле. Совет: используйте Sonnet для субагентов, где не нужна максимальная мощность, а Opus — только для критичных задач вроде безопасности.
Глубина — только один уровень
Субагенты не могут запускать своих субагентов. Архитектура ограничена одним уровнем вложенности: оркестратор → субагенты. Это осознанное решение — глубокая рекурсия создаёт неконтролируемый рост стоимости.
Отладка — отдельная боль
Когда что-то идёт не так, вам нужно разбираться в логике нескольких агентов одновременно. Субагент не видит контекст родителя, и если оркестратор плохо сформулировал задачу — субагент тихо вернёт бесполезный результат. У меня был случай: полчаса смотрел на вывод и не мог понять, почему результат пустой — оказалось, в промпте оркестратора была опечатка в имени субагента. Отладка требует анализа промптов на каждом уровне.
Нет общения между субагентами
Субагенты изолированы друг от друга. Исследователь не может передать свои находки тестировщику напрямую — только через оркестратора. Если вам нужна коллаборация между агентами, рассмотрите экспериментальную функцию Agent Teams в Claude Code CLI — там агенты могут обмениваться сообщениями напрямую через общий mailbox.
Стоп, а когда НЕ стоит использовать?
- Задача решается одним агентом за минуту — не добавляйте сложность ради сложности
- Части задачи сильно зависят друг от друга — параллелизация не даст выигрыша
- Бюджет ограничен — мульти-агент потребляет токены кратно количеству субагентов
- Вы не готовы отлаживать — если промпты не отточены, результаты будут непредсказуемыми
Итог серии: три уровня агентов
За три статьи мы прошли путь от простых инструкций до полноценной команды ИИ-агентов. Вот сводка — какой уровень когда выбирать:
УровеньЧто этоКогда использоватьСложностьСтоимость 1. Системный промптClaude с детальными инструкциями, ролью и ограничениямиТиповые задачи: ответы, генерация текста, анализ. Когда задача решается за один ходНизкаяМинимальная 2. Автономный агентClaude + инструменты (файлы, bash, поиск, API). Цикл «думаю → действую → наблюдаю»Задачи, требующие взаимодействия с окружением: рефакторинг, исследование кодовой базы, автоматизацияСредняяУмеренная 3. Мульти-агентная системаОркестратор + специализированные субагенты, работающие параллельноМасштабные задачи: полный код-ревью, миграция, аудит, когда одному агенту не хватает контекстаВысокаяВысокая (×N агентов) Как выбрать? Начинайте с простого. Это работает. Серьёзно. Если системный промпт не справляется — добавьте инструменты (уровень 2). Если один агент не тянет или задача естественно декомпозируется — поднимайтесь на уровень 3. Не используйте мульти-агентную систему, когда хватает одного хорошо настроенного агента.
Главный вывод
Мульти-агентные системы — не магия. Это доступный инструмент, который работает прямо сейчас. Claude Agent SDK даёт вам возможность собрать команду специализированных ИИ-агентов за пару десятков строк кода. Но ключ — в понимании, когда его применять, а когда не надо.
Один хороший агент лучше, чем три плохо настроенных. Начните с малого, экспериментируйте, и масштабируйте только когда задача этого требует.
Это была финальная часть серии «Создаём агентов в Claude». Если вы прошли все три статьи — у вас теперь есть полная картина: от промптов до мульти-агентных систем.
Подписывайтесь на канал @skazhi_ai — разбираем ИИ по винтикам, без воды и хайпа.