Отправка параллельных агентов

Обзор

Вы делегируете задачи специализированным агентам с изолированным контекстом. Точно формулируя их инструкции и контекст, вы добиваетесь, чтобы они оставались сфокусированными и справлялись с задачей. Они никогда не должны наследовать контекст или историю вашей сессии — вы конструируете ровно то, что им нужно. Это также сохраняет ваш собственный контекст для координации.

Когда у вас несколько несвязанных сбоев (разные файлы тестов, разные подсистемы, разные баги), последовательное расследование тратит время. Каждое расследование независимо и может идти параллельно.

Главный принцип: отправляйте по одному агенту на каждую независимую проблемную область. Пусть работают одновременно.

Когда использовать

digraph when_to_use {
    "Multiple failures?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single agent investigates all" [shape=box];
    "One agent per problem domain" [shape=box];
    "Can they work in parallel?" [shape=diamond];
    "Sequential agents" [shape=box];
    "Parallel dispatch" [shape=box];
    "Multiple failures?" -> "Are they independent?" [label="yes"];
    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}

Используйте, когда:

• 3+ файлов тестов падают с разными корневыми причинами
• Несколько подсистем сломаны независимо
• Каждую проблему можно понять без контекста других
• Нет разделяемого состояния между расследованиями

Не используйте, когда:

• Сбои связаны (исправление одного может исправить другие)
• Нужно понять полное состояние системы
• Агенты мешали бы друг другу

Паттерн

1. Выявите независимые области

Сгруппируйте сбои по тому, что сломано:

• Тесты файла A: поток одобрения инструментов
• Тесты файла B: поведение пакетного завершения
• Тесты файла C: функциональность прерывания

Каждая область независима — починка одобрения инструментов не влияет на тесты прерывания.

2. Создайте сфокусированные задачи для агентов

Каждый агент получает:

• Конкретный объём: один файл тестов или подсистема
• Ясную цель: сделать так, чтобы эти тесты проходили
• Ограничения: не менять другой код
• Ожидаемый вывод: сводка того, что найдено и исправлено

3. Отправьте параллельно

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

Subagent (general-purpose): "Fix agent-tool-abort.test.ts failures"
Subagent (general-purpose): "Fix batch-completion-behavior.test.ts failures"
Subagent (general-purpose): "Fix tool-approval-race-conditions.test.ts failures"
# Все три выполняются одновременно.

Несколько вызовов запуска в одном ответе = параллельное исполнение. По одному на ответ = последовательное.

4. Просмотрите и интегрируйте

Когда агенты возвращаются: прочитайте каждую сводку; проверьте, что исправления не конфликтуют; прогоните полный набор тестов; интегрируйте все изменения.

Структура промпта агента

Хорошие промпты агентов: 1) сфокусированы — одна ясная проблемная область; 2) самодостаточны — весь контекст для понимания проблемы; 3) конкретны по выводу — что агент должен вернуть?

Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:
1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by replacing arbitrary timeouts with event-based waiting, fixing bugs, or adjusting expectations

Do NOT just increase timeouts - find the real issue.
Return: Summary of what you found and what you fixed.

Частые ошибки

❌ Слишком широко: «Почини все тесты» — агент теряется. ✅ Конкретно: «Почини agent-tool-abort.test.ts» — узкий объём.

❌ Без контекста: «Почини состояние гонки» — агент не знает где. ✅ С контекстом: вставьте сообщения об ошибках и имена тестов.

❌ Без ограничений: агент может всё отрефакторить. ✅ С ограничениями: «НЕ меняй продакшен-код» или «Чини только тесты».

❌ Расплывчатый вывод: «Почини» — вы не знаете, что изменилось. ✅ Конкретно: «Верни сводку корневой причины и изменений».

Когда НЕ использовать

Связанные сбои: починка одного может починить другие — сначала исследуйте вместе. Нужен полный контекст: понимание требует видеть всю систему. Разведочная отладка: вы ещё не знаете, что сломано. Разделяемое состояние: агенты мешали бы друг другу (правят одни файлы, используют одни ресурсы).

Реальный пример из сессии

Сценарий: 6 падений тестов в 3 файлах после крупного рефакторинга.

Решение: независимые области — логика прерывания отдельно от пакетного завершения отдельно от состояний гонки.

Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts

Результаты: Агент 1 заменил таймауты ожиданием по событиям; Агент 2 исправил баг структуры события (threadId не на месте); Агент 3 добавил ожидание завершения асинхронного исполнения инструмента. Интеграция: все исправления независимы, без конфликтов, весь набор зелёный.

Ключевые преимущества

1. Параллелизм — несколько расследований идут одновременно
2. Фокус — у каждого агента узкий объём, меньше контекста
3. Независимость — агенты не мешают друг другу
4. Скорость — 3 проблемы за время одной

Проверка

После возврата агентов: 1) просмотрите каждую сводку; 2) проверьте конфликты — правили ли агенты один код?; 3) прогоните полный набор; 4) выборочно проверьте — агенты могут совершать систематические ошибки.