Трансляционные события в Copilot SDK

Примечание.

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

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

Когда streaming: true он настроен на сессию, SDK в реальном времени излучает эфемерные события (дельты, обновления прогресса) вместе с сохраненными событиями (полные сообщения, результаты инструментов). Все события имеют общую оболочку и несут полезную data нагрузку, форма которой зависит от события type. Для диаграммы последовательности полного потока событий см. репозиторийgithub/copilot-sdk.

Концепция	Описание

          **Эфемерное событие** | Transient; Транслировался в реальном времени, но **не** сохранялся в журнале сессии. Не повторяется в резюме сессии. |

| Сохраняющееся событие | Сохранено в журнале событий сессии на диске. Повторяется при возобновлении сессии. | | Событие Delta | Эфемерный потоковой фрагмент (текст или рассуждение). Накапливайте дельты для создания полного контента. | | ** parentId Цепь** | Каждое событие parentId указывает на предыдущее, образуя связанный список, по которому можно пройтись. |

Оболочка событий

Каждое событие сессии, независимо от типа, включает следующие поля:

Поле	Тип	Описание
`id`

          `string` (UUID v4) | Уникальный идентификатор события |

Подписка на события

// All events
session.on((event) => {
    console.log(event.type, event.data);
});

// Specific event type — data is narrowed automatically
session.on("assistant.message_delta", (event) => {
    process.stdout.write(event.data.deltaContent);
});

Примеры в Python, Go и .NET см. репозиторийgithub/copilot-sdk.

Совет

          **Python / Go:** Эти SDK используют один `Data` класс/структуру со всеми возможными полями как опциональные/нулируемые. Для каждого типа события заполнены только поля, указанные в таблицах ниже — остальные будут `None` / `nil`.

          **.NET:** .NET SDK использует отдельные, сильно типизированные классы данных для каждого события (например, `AssistantMessageDeltaData`), поэтому для каждого типа существуют только соответствующие поля.

          **TypeScript:** SDK TypeScript использует дискриминированное объединение — при совпадении на `event.type`, `data` полезная нагрузка автоматически сужается до нужной формы.

Соревнования ассистентов

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

`assistant.turn_start`

Излучается, когда агент начинает обрабатывать ход.

Поле данных	Тип	Обязательный	Описание
`turnId`	`string`	✅	Идентификатор поворота (обычно строчный номер хода)
`interactionId`	`string`
Идентификатор взаимодействия для корреляции телеметрии

`assistant.intent`

Эфемерно. Краткое описание того, чем сейчас занимается агент, обновляется по мере работы.

Поле данных	Тип	Обязательный	Описание
`intent`	`string`	✅	Человеком читаемое намерение (например, «Исследование кодовой базы»)

`assistant.reasoning`

Полный расширенный размышленный блок из модели. Выпущено после завершения рассуждений.

Поле данных	Тип	Обязательный	Описание
`reasoningId`	`string`	✅	Уникальный идентификатор для этого блока рассуждения
`content`	`string`	✅	Полный расширенный текст мышления

`assistant.reasoning_delta`

Эфемерно. Постепенная часть расширенного мышления модели, транслируемая в реальном времени.

Поле данных	Тип	Обязательный	Описание
`reasoningId`	`string`	✅	Совпадает с соответствующим `assistant.reasoning` событием
`deltaContent`	`string`	✅	Текст для добавления к содержанию рассуждения

`assistant.message`

Полный ответ ассистента на этот звонок LLM. Может содержать запросы на вызов инструментов.

Поле данных	Тип	Обязательный	Описание
`messageId`	`string`	✅	Уникальный идентификатор для этого сообщения
`content`	`string`	✅	Ответ ассистента в тексте
`toolRequests`	`ToolRequest[]`
Вызовы инструментов, которые хочет сделать ассистент (см. ниже)
`reasoningOpaque`	`string`
Зашифрованное расширенное мышление (антропные модели); Привязанный к сеансам
`reasoningText`	`string`
Читаемый текст рассуждений из расширенного мышления
`encryptedContent`	`string`
Зашифрованное рассуждение (модели OpenAI); Привязанный к сеансам
`phase`	`string`
Фаза генерации (например, `"thinking"` против `"response"`)
`outputTokens`	`number`
Фактическое количество токенов вывода из ответа API
`interactionId`	`string`
Идентификатор взаимодействия для телеметрии
`parentToolCallId`	`string`
Устанавливается, когда это сообщение исходит от субагента

          **
          `ToolRequest` Области:**

Поле	Тип	Обязательный	Описание
`toolCallId`	`string`	✅	Уникальный идентификатор для этого вызова инструмента
`name`	`string`	✅	Имя инструмента (например, `"bash"`, `"edit"`, `"grep"`)
`arguments`	`object`
Проанализированные аргументы в пользу инструмента
`type`	`"function" \| "custom"`
Тип вызова; по `"function"` умолчанию — когда отсутствует

`assistant.message_delta`

Эфемерно. Постепенный фрагмент ответа ассистента в реальном времени.

Поле данных	Тип	Обязательный	Описание
`messageId`	`string`	✅	Совпадает с соответствующим `assistant.message` событием
`deltaContent`	`string`	✅	Текстовый фрагмент для добавления к сообщению
`parentToolCallId`	`string`
Set при возникновении от субагента

`assistant.turn_end`

Издаётся после завершения хода агентом (выполнение всех инструментов завершено, финальный ответ получен).

Поле данных	Тип	Обязательный	Описание
`turnId`	`string`	✅	Совпадает с соответствующим `assistant.turn_start` событием

`assistant.usage`

Эфемерно. Информация об использовании токена и стоимости для отдельного вызова API.

Поле данных	Тип	Обязательный	Описание
`model`	`string`	✅	Идентификатор модели (например, `"gpt-4.1"`)
`inputTokens`	`number`
Расходуемые входные токены
`outputTokens`	`number`
Выпускные токены
`cacheReadTokens`	`number`
Токены, читаемые из кэша prompt
`cacheWriteTokens`	`number`
Токены, записываемые для кэша prompt
`cost`	`number`
Стоимость мультипликатора модели для выставления счетов
`duration`	`number`
Длительность вызова API в миллисекундах
`initiator`	`string`
Что вызвало этот вызов (например, `"sub-agent"`); отсутствует для инициированного пользователем
`apiCallId`	`string`
Идентификатор завершения от провайдера (например, `chatcmpl-abc123`)
`providerCallId`	`string`

          GitHub ID запроса трассировки (`x-github-request-id`) |

`assistant.streaming_delta`

Эфемерно. Низкоуровневый индикатор прогресса сети — общее количество байт, полученных от ответа потокового API.

Поле данных	Тип	Обязательный	Описание
`totalResponseSizeBytes`	`number`	✅	Совокупные байты, полученные на данный момент

События выполнения инструментов

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

`tool.execution_start`

Испускается, когда инструмент начинает работать.

Поле данных	Тип	Обязательный	Описание
`toolCallId`	`string`	✅	Уникальный идентификатор для этого вызова инструмента
`toolName`	`string`	✅	Название инструмента (например, `"bash"`, `"edit"`, `"grep"`)
`arguments`	`object`
Анализированные аргументы, передаваемые инструменту
`mcpServerName`	`string`
Имя сервера MCP, когда инструмент предоставляется сервером MCP
`mcpToolName`	`string`
Оригинальное имя инструмента на сервере MCP
`parentToolCallId`	`string`
Устанавливается при вызове субагентом

`tool.execution_partial_result`

Эфемерно. Инкрементальный вывод от запущенного инструмента (например, потоковый выход bash).

Поле данных	Тип	Обязательный	Описание
`toolCallId`	`string`	✅	Совпадает с соответствующими `tool.execution_start`
`partialOutput`	`string`	✅	Инкрементальный выходной блок

`tool.execution_progress`

Эфемерно. Статус прогресса, читаемый человеком, из запускающегося инструмента (например, уведомления о прогрессе сервера MCP).

Поле данных	Тип	Обязательный	Описание
`toolCallId`	`string`	✅	Совпадает с соответствующими `tool.execution_start`
`progressMessage`	`string`	✅	Сообщение о статусе прогресса

`tool.execution_complete`

Издаётся, когда инструмент завершает выполнение — успешно или с ошибкой.

Поле данных	Тип	Обязательный	Описание
`toolCallId`	`string`	✅	Совпадает с соответствующими `tool.execution_start`
`success`	`boolean`	✅	Была ли казнь успешной
`model`	`string`
Модель, которая сгенерировала этот вызов инструмента
`interactionId`	`string`
Идентификатор взаимодействия
`isUserRequested`	`boolean`

          `true` когда пользователь явно запросил этот вызов инструмента |

| result | Result | | Представление об успехе (см. ниже) | | error | { message, code? } | | Присутствует при неисправности | | toolTelemetry | object | | Телеметрия, специфичная для инструмента | | parentToolCallId | string | | Устанавливается при вызове субагентом |

          **
          `Result` Области:**

Поле	Тип	Обязательный	Описание
`content`	`string`	✅	Краткий результат отправляется в LLM (может быть урезан для повышения эффективности токенов)
`detailedContent`	`string`
Полный результат для отображения, сохраняя полный контент, например, diff
`contents`	`ContentBlock[]`
Структурированные блоки контента (текст, терминал, изображение, аудио, ресурс)

`tool.user_requested`

Издаётся, когда пользователь явно запрашивает вызов инструмента (вместо того чтобы модель выбирает вызов инструмента).

Поле данных	Тип	Обязательный	Описание
`toolCallId`	`string`	✅	Уникальный идентификатор для этого вызова инструмента
`toolName`	`string`	✅	Название инструмента, который пользователь хочет вызвать
`arguments`	`object`
Аргументы в пользу призыва

События жизненного цикла сессии

`session.idle`

Эфемерно. Агент завершил всю обработку и готов к следующему сообщению. Это сигнал о полном завершении поворота.

Поле данных	Тип	Обязательный	Описание
`backgroundTasks`	`BackgroundTasks`
Фоновые агенты/оболочки всё ещё работали, когда агент стал простоем

`session.error`

Во время обработки сессии произошла ошибка.

Поле данных	Тип	Обязательный	Описание
`errorType`	`string`	✅	Категория ошибок (например, `"authentication"`, `"quota"`, `"rate_limit"`)
`message`	`string`	✅	Сообщение об ошибке, читаемое человеком
`stack`	`string`
Трассировка стека ошибок
`statusCode`	`number`
Статус HTTP-кода из восходящего запроса
`providerCallId`	`string`

          GitHub идентификатор трассировки запроса для корреляции логов на стороне сервера |

`session.compaction_start`

Началось уплотнение контекстного окна. Полезная нагрузка данных пуста ({}).

`session.compaction_complete`

Уплотнение контекстного окна завершено.

Поле данных	Тип	Обязательный	Описание
`success`	`boolean`	✅	Удалось ли уплотнение
`error`	`string`
Сообщение об ошибке при неудачном уплотнении
`preCompactionTokens`	`number`
Токены до уплотнения
`postCompactionTokens`	`number`
Токены после уплотнения
`preCompactionMessagesLength`	`number`
Количество сообщений до уплотнения
`messagesRemoved`	`number`
Сообщения удалены
`tokensRemoved`	`number`
Жетоны удалены
`summaryContent`	`string`
LLM-генерируемое резюме компактной истории
`checkpointNumber`	`number`
Номер снимка контрольной точки для восстановления
`checkpointPath`	`string`
Путь файла, где хранился контрольный пункт
`compactionTokensUsed`	`{ input, output, cachedInput }`
Использование токена для вызова компрессионного LLM
`requestId`	`string`

          GitHub запрос идентификатора трассировки для вызова уплотнения |

`session.title_changed`

Эфемерно. Автоматически сгенерированное название сессии было обновлено.

Поле данных	Тип	Обязательный	Описание
`title`	`string`	✅	Новое название сессии

`session.context_changed`

Рабочий каталог или контекст репозитория сессии изменились.

Поле данных	Тип	Обязательный	Описание
`cwd`	`string`	✅	Текущий рабочий справочник
`gitRoot`	`string`
Корень репозитория Git
`repository`	`string`
Репозиторий в `"owner/name"` формате
`branch`	`string`
Текущая ветвь Git

`session.usage_info`

Эфемерно. Снимок использования контекстного окна.

Поле данных	Тип	Обязательный	Описание
`tokenLimit`	`number`	✅	Максимальное количество токенов для контекстного окна модели
`currentTokens`	`number`	✅	Текущие токены в контекстном окне
`messagesLength`	`number`	✅	Текущее количество сообщений в разговоре

`session.task_complete`

Агент выполнил назначенную задачу.

Поле данных	Тип	Обязательный	Описание
`summary`	`string`
Краткое содержание выполненной задачи

`session.shutdown`

Сессия закончилась.

Поле данных	Тип	Обязательный	Описание
`shutdownType`	`"routine" \| "error"`	✅	Обычное отключение или сбой
`errorReason`	`string`
Описание ошибки, когда `shutdownType` равна `"error"`
`totalPremiumRequests`	`number`	✅	Общее количество используемых премиум-запросов API
`totalApiDurationMs`	`number`	✅	Кумулятивное время вызова API в миллисекундах
`sessionStartTime`	`number`	✅	Unix timestamp (ms) при начале сессии
`codeChanges`	`{ linesAdded, linesRemoved, filesModified }`	✅	Метрики агрегированных изменений кода
`modelMetrics`	`Record<string, ModelMetric>`	✅	Распределение использования по моделям
`currentModel`	`string`
Модель выбрана во время отключения

Разрешения и события ввода пользователя

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

`permission.requested`

Эфемерно. Агенту требуется разрешение на выполнение действия (запуск команды, записи файла и т.д.).

Поле данных	Тип	Обязательный	Описание
`requestId`	`string`	✅	Используйте это, чтобы ответить через `session.respondToPermission()`
`permissionRequest`	`PermissionRequest`	✅	Детали запрашиваемого разрешения

Это permissionRequest дискриминационный союз на kind:

`kind`	Ключевые поля	Описание
`"shell"`

          `fullCommandText`, , `intention``commands[]``possiblePaths[]` | Выполните команду shell |

Все kind варианты также включают опциональную toolCallId связь с вызовом инструмента, который инициировал запрос.

`permission.completed`

Эфемерно. Запрос на разрешение был урегулирован.

Поле данных	Тип	Обязательный	Описание
`requestId`	`string`	✅	Совпадает с соответствующими `permission.requested`
`result.kind`	`string`	✅	Один из: `"approved"`, `"denied-by-rules"`, `"denied-interactively-by-user"`, `"denied-no-approval-rule-and-could-not-request-from-user"`, `"denied-by-content-exclusion-policy"`

`user_input.requested`

Эфемерно. Агент задаёт пользователю вопрос.

Поле данных	Тип	Обязательный	Описание
`requestId`	`string`	✅	Используйте это, чтобы ответить через `session.respondToUserInput()`
`question`	`string`	✅	Вопрос, который стоит задать пользователю
`choices`	`string[]`
Предопределённые варианты для пользователя
`allowFreeform`	`boolean`
Разрешен ли ввод свободного текста

`user_input.completed`

Эфемерно. Запрос пользователя был решен.

Поле данных	Тип	Обязательный	Описание
`requestId`	`string`	✅	Совпадает с соответствующими `user_input.requested`

`elicitation.requested`

Эфемерно. Агенту нужен структурированный ввод формы от пользователя (протокол идентификации MCP).

Поле данных	Тип	Обязательный	Описание
`requestId`	`string`	✅	Используйте это, чтобы ответить через `session.respondToElicitation()`
`message`	`string`	✅	Описание необходимой информации
`mode`	`"form"`
Режим вызова (пока только `"form"`)
`requestedSchema`	`{ type: "object", properties, required? }`	✅	Схема JSON, описывающая поля формы

`elicitation.completed`

Эфемерно. Запрос на расследование был урегулирован.

Поле данных	Тип	Обязательный	Описание
`requestId`	`string`	✅	Совпадает с соответствующими `elicitation.requested`

События субагентов и навыков

`subagent.started`

Был вызван таможенный агент как субагент.

Поле данных	Тип	Обязательный	Описание
`toolCallId`	`string`	✅	Родительский вызов инструмента, который породил этот подагент
`agentName`	`string`	✅	Внутреннее имя субагента
`agentDisplayName`	`string`	✅	Отображение, читаемое человеком
`agentDescription`	`string`	✅	Описание того, что делает субагент

`subagent.completed`

Субагент успешно закончил.

Поле данных	Тип	Обязательный	Описание
`toolCallId`	`string`	✅	Совпадает с соответствующими `subagent.started`
`agentName`	`string`	✅	Внутреннее имя
`agentDisplayName`	`string`	✅	Показать имя

`subagent.failed`

Субагент столкнулся с ошибкой.

Поле данных	Тип	Обязательный	Описание
`toolCallId`	`string`	✅	Совпадает с соответствующими `subagent.started`
`agentName`	`string`	✅	Внутреннее имя
`agentDisplayName`	`string`	✅	Показать имя
`error`	`string`	✅	Сообщение об ошибке

`subagent.selected`

Был выбран (вывод) пользовательский агент для обработки текущего запроса.

Поле данных	Тип	Обязательный	Описание
`agentName`	`string`	✅	Внутреннее имя выбранного агента
`agentDisplayName`	`string`	✅	Показать имя
`tools`	`string[] \| null`	✅	Имена инструментов, доступные этому агенту; `null` для всех инструментов

`subagent.deselected`

Пользовательский агент был снят с выбора и вернулся к стандартному агенту. Полезная нагрузка отклика будет пустой ({}).

`skill.invoked`

Для текущего разговора был активирован навык.

Поле данных	Тип	Обязательный	Описание
`name`	`string`	✅	Название навыка
`path`	`string`	✅	Путь файла к определению SKILL.md
`content`	`string`	✅	В разговор добавляется полный контент по навыкам
`allowedTools`	`string[]`
Инструменты автоматически одобряются, пока этот навык активен
`pluginName`	`string`
Плагин, из которого возник навык
`pluginVersion`	`string`
Версия плагина

Другие события

`abort`

Текущий поворот был прерван.

Поле данных	Тип	Обязательный	Описание
`reason`	`string`	✅	Почему ход был прерван (например, `"user initiated"`)

`user.message`

Пользователь отправил сообщение. Записано для хронологии сессии.

Поле данных	Тип	Обязательный	Описание
`content`	`string`	✅	Текст сообщения пользователя
`transformedContent`	`string`
Трансформированная версия после предварительной обработки
`attachments`	`Attachment[]`
Файл, каталог, выбор, blob или GitHub ссылки на вложения
`source`	`string`
Идентификатор источника сообщения
`agentMode`	`string`
Режим агента: `"interactive"`, `"plan"`, `"autopilot"`, или `"shell"`
`interactionId`	`string`
Идентификатор взаимодействия

`system.message`

В разговор вводился подсказка системы или разработчика.

Поле данных	Тип	Обязательный	Описание
`content`	`string`	✅	Текст запроса
`role`	`"system" \| "developer"`	✅	Роль сообщения
`name`	`string`
Идентификатор источника
`metadata`	`{ promptVersion?, variables? }`
Метаданные шаблона запросов

`external_tool.requested`

Эфемерно. Агент хочет вызвать внешний инструмент (предоставленный потребителем SDK).

Поле данных	Тип	Обязательный	Описание
`requestId`	`string`	✅	Используйте это, чтобы ответить через `session.respondToExternalTool()`
`sessionId`	`string`	✅	Сессия, к которой принадлежит этот запрос
`toolCallId`	`string`	✅	Идентификатор вызова инструмента для этого вызова
`toolName`	`string`	✅	Название внешнего инструмента
`arguments`	`object`
Аргументы в пользу инструмента

`external_tool.completed`

Эфемерно. Запрос на внешний инструмент был урегулирован.

Поле данных	Тип	Обязательный	Описание
`requestId`	`string`	✅	Совпадает с соответствующими `external_tool.requested`

`exit_plan_mode.requested`

Эфемерно. Агент составил план и хочет выйти из режима плана.

Поле данных	Тип	Обязательный	Описание
`requestId`	`string`	✅	Используйте это, чтобы ответить через `session.respondToExitPlanMode()`
`summary`	`string`	✅	Краткое содержание плана
`planContent`	`string`	✅	Полный файл плана
`actions`	`string[]`	✅	Доступные действия пользователя (например, одобрить, отредактировать, отклонить)
`recommendedAction`	`string`	✅	Рекомендуемое действие

`exit_plan_mode.completed`

Эфемерно. Запрос на режим выхода был урегулирован.

Поле данных	Тип	Обязательный	Описание
`requestId`	`string`	✅	Совпадает с соответствующими `exit_plan_mode.requested`

`command.queued`

Эфемерно. Для выполнения была поставлена слэш-команда.

Поле данных	Тип	Обязательный	Описание
`requestId`	`string`	✅	Используйте это, чтобы ответить через `session.respondToQueuedCommand()`
`command`	`string`	✅	Текст команды по косой черте (например, `/help`, `/clear`)

`command.completed`

Эфемерно. Была решена очередная команда.

Поле данных	Тип	Обязательный	Описание
`requestId`	`string`	✅	Совпадает с соответствующими `command.queued`

Краткая справка: агентный поток поворотов

Типичный агентный ход генерирует события в следующем порядке:

assistant.turn_start          → Turn begins
├── assistant.intent          → What the agent plans to do (ephemeral)
├── assistant.reasoning_delta → Streaming thinking chunks (ephemeral, repeated)
├── assistant.reasoning       → Complete thinking block
├── assistant.message_delta   → Streaming response chunks (ephemeral, repeated)
├── assistant.message         → Complete response (may include toolRequests)
├── assistant.usage           → Token usage for this API call (ephemeral)
│
├── [If tools were requested:]
│   ├── permission.requested  → Needs user approval (ephemeral)
│   ├── permission.completed  → Approval result (ephemeral)
│   ├── tool.execution_start  → Tool begins
│   ├── tool.execution_partial_result  → Streaming tool output (ephemeral, repeated)
│   ├── tool.execution_progress        → Progress updates (ephemeral, repeated)
│   ├── tool.execution_complete        → Tool finished
│   │
│   └── [Agent loops: more reasoning → message → tool calls...]
│
assistant.turn_end            → Turn complete
session.idle                  → Ready for next message (ephemeral)

Все типы событий одним взглядом

Тип события	Эфемерный	Категория	Ключевые поля данных
`assistant.turn_start`
Помощник

          `turnId`, `interactionId?` |

Кто может использовать эту функцию?

В этой статье