Понимание петли агентов

Примечание.

Второй пилот SDK в настоящее время находится в Публичный предварительный просмотр. Функциональность и доступность могут меняться.

Architecture

Диаграмма, показывающая поток от вашего приложения к сессии SDK, к Copilot CLI, к LLM и обратно.

Это Второй пилот SDK транспортный слой — он отправляет ваш запрос на Второй пилот CLI JSON-RPC и возвращает события обратно в приложение. CLI — это оркестратор, который запускает цикл использования агентных инструментов, выполняя один или несколько вызовов LLM API до завершения задачи.

Цикл использования инструментов

Когда вы вызываете session.send({ prompt }), Второй пилот CLI входит в цикл:

Схема цикла использования инструментов: запрос на вызов LLM, выполнение инструмента при запросе, в противном случае session.idle.

Модель видит полную историю разговоров по каждому звонку — системный запрос, пользовательское сообщение и все предыдущие вызовы и результаты.

Каждая итерация этого цикла — это ровно один вызов LLM API, видимый как одна assistant.turn_start / assistant.turn_end пара в журнале событий. Скрытых звонков нет.

Ходы

Ход — это один вызов LLM API и его последствия:

Второй пилот CLI отправляет историю разговора в LLM
LLM отвечает (возможно, с помощью запросов инструментов)
Если инструменты были запрошены — Второй пилот CLI выполняет их
assistant.turn_end излучается

Одно сообщение пользователя обычно приводит к нескольким ходам. Например, вопрос вроде «как работает X в этой кодовой базе?» может привести к следующему:

Повернуть	Что делает модель	toolRequests?
1	Вызовы `grep` и `glob` поиск по кодовой базе	Yes
2	Читает конкретные файлы на основе результатов поиска	Yes
3	Читайте больше файлов для более глубокого контекста	Yes
4	Получает итоговый текстовый ответ	Нет (петля заканчивается)

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

Поток событий для многоходового взаимодействия

Диаграмма трёх ходов в взаимодействии агента, каждый с событиями start, message, tool и end, заканчивающимися session.idle.

Кто запускает каждый ход

Actor	Ответственность
Ваше приложение	Отправляет первоначальный запрос через `session.send()`
Второй пилот CLI	Запускает цикл использования инструментов — выполняет инструменты и возвращает результаты в LLM на следующий ход
LLM	Решает, запрашивать ли инструменты (продолжать цикл) или давать окончательный ответ (стоп)
Второй пилот SDK	Передаёт события; не управляет циклом

Второй пилот CLI Это чисто механическая: «Модель просила инструменты → выполнить → снова вызывать модель.» Модель принимает решение, когда остановиться.

`session.idle` и `session.task_complete`

Это два разных сигнала завершения с очень разными гарантиями.

`session.idle`

Всегда излучается , когда цикл использования инструмента заканчивается
Эфемерный: не сохраняется на диске, не воспроизводит при возобновлении сессии
Означает: «Агент прекратил обработку и готов к следующему сообщению»
Используйте это как надёжный сигнал «готово»

Второй пилот SDKМетод 'sendAndWait()s ждёт этого события:

// Blocks until session.idle fires
const response = await session.sendAndWait({ prompt: "Fix the bug" });

`session.task_complete`

Опционально излучается: требует, чтобы модель явно сигнализировала
Сохранено: сохранено в журнал событий сессии на диске
Означает: «агент считает выполненную общую задачу»
Несёт дополнительное summary поле

session.on("session.task_complete", (event) => {
    console.log("Task done:", event.data.summary);
});

Режим автопилота

В режиме автопилота (безголовое или автономное управление) Второй пилот CLI активно отслеживает, вызывала task_completeли модель . Если цикл использования инструмента заканчивается без него, Второй пилот CLI вводится синтетическое пользовательское сообщение, подталкивающее модель продолжать работу.

Это создаёт двухуровневый механизм завершения в автопилоте:

Модель вызывает task_complete с резюме → Второй пилот CLI излучает session.task_complete → выполнено
Модель останавливается, не вызывая её, → Второй пилот CLI подталкивает → модель продолжает или вызывает task_complete

Почему `task_complete` бы не появиться

В интерактивном режиме (обычный чат) Второй пилот CLI не подталкивает к task_complete. Модель может полностью его пропустить. Распространенные причины:

Разговорные вопросы и ответы: модель отвечает на вопрос и просто останавливается — нет отдельной «задачи» для выполнения
Дискреция модели: модель производит итоговый текстовый ответ без вызова сигнала завершения задачи
Прерванные сессии: сессия заканчивается до того, как модель достигает точки завершения

Второй пилот CLI Излучает session.idle всё равно, потому что это механический сигнал (цикл закончился), а не семантический (модель думает, что всё готово).

Какой сигнал использовать

Сценарий использования	Сигнал
Дождитесь, пока агент закончит обработку	`session.idle`
Знайте, когда выполнена задача по программированию
`session.task_complete` (лучшее усилие)
Тайм-аут и обработка ошибок	`session.idle` + `session.error`

Подсчёт вызовов LLM

Количество assistant.turn_start / assistant.turn_end пар в журнале событий равно общему числу LLM API вызовов. Нет скрытых требований к планированию, оценке или проверке завершения.