События потоковых сессий

Обзор

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

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

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

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

// 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);
});

from copilot.session_events import SessionEventType

def handle(event):
    if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
        print(event.data.delta_content, end="", flush=True)

session.on(handle)

session.On(func(event copilot.SessionEvent) {
    if d, ok := event.Data.(*copilot.AssistantMessageDeltaData); ok {
        fmt.Print(d.DeltaContent)
    }
})

session.On<SessionEvent>(evt =>
{
    if (evt is AssistantMessageDeltaEvent delta)
    {
        Console.Write(delta.Data.DeltaContent);
    }
});

// All events
session.on(event -> System.out.println(event.getType()));

// Specific event type — data is narrowed to the matching class
session.on(AssistantMessageDeltaEvent.class, event ->
    System.out.print(event.getData().deltaContent())
);

Подписка перед началом сеанса

Сеанс может выдавать события до возврата вызова создания или возобновления. Агент может уже работать , особенно в возобновлении с continuePendingWorkсобытиями и временными событиями, такими как session.idle никогда не записываются в журнал сеансов, поэтому getMessages их невозможно восстановить после этого. Подписка, установленная после того, как дескриптор сеанса отсутствует в этом окне запуска.

use github_copilot_sdk::{Client, SessionConfig};

async fn create_without_missing_startup_events(
    client: &Client,
) -> Result<(), github_copilot_sdk::Error> {
    let prepared = client.prepare_session(
        SessionConfig::default().with_event_buffer_capacity(2048),
    )?;

    // Installed before any wire activity: nothing is dropped for lack of a receiver.
    let mut events = prepared.subscribe();
    tokio::spawn(async move {
        while let Ok(event) = events.recv().await {
            println!("{}", event.event_type);
        }
    });

    let session = prepared.start().await?;
    let _ = session;
    Ok(())
}

prepare_* является синхронным и инертным: он проверяет емкость буфера, выделяет локальный канал и не делает ничего другого. Сеанс не зарегистрирован и ничего не достигает интерфейса командной строки до start() первого опроса. Удаление подготовленного сеанса, которое никогда не было запущено, не оставляет состояния позади и закрывает свои подписки; start() удаление будущего отменяет запуск во время полета и отменяет регистрацию сеанса, поэтому повторная попытка с тем же идентификатором сеанса успешно выполнена. Очистка ограничена точной регистрацией заброшенного запуска, поэтому она не может вытеснить повторную попытку, которая уже взяла на себя тот же идентификатор сеанса.

Буферизация запуска стоит планировать для:

• Буфер событий является конечным — 512 событий, если event_buffer_capacity он не переопределяется. Емкость 0 отклоняется с ошибкой недопустимой конфигурации, а не зажатой.
• Медленные подписчики наблюдают за ошибкой, сообщая Lagged о количестве пропущенных событий. Они никогда не применяют обратную прессу к циклу событий сеанса.
• Потребители, которые нуждаются в потере представления большого запуска при запуске, должны настроить емкость, которая охватывает ее или слив подписку одновременно с start().

Отрисовка только ответа родительского агента

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

import type { CopilotSession } from "@github/copilot-sdk";

export function subscribeParentResponse(session: CopilotSession): void {
    session.on("assistant.message_delta", (event) => {
        if (!event.agentId) {
            process.stdout.write(event.data.deltaContent);
        }
    });
}

from copilot import CopilotSession, SessionEvent, SessionEventType
from copilot.session_events import AssistantMessageDeltaData

def subscribe_parent_response(session: CopilotSession) -> None:
    def handle(event: SessionEvent) -> None:
        if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA and event.agent_id is None:
            data = event.data
            if isinstance(data, AssistantMessageDeltaData):
                print(data.delta_content, end="", flush=True)

    session.on(handle)

package example

import (
    "fmt"

    copilot "github.com/github/copilot-sdk/go"
)

func subscribeParentResponse(session *copilot.Session) {
    session.On(func(event copilot.SessionEvent) {
        if event.AgentID != nil {
            return
        }

        if d, ok := event.Data.(*copilot.AssistantMessageDeltaData); ok {
            fmt.Print(d.DeltaContent)
        }
    })
}

using System;
using GitHub.Copilot;

static class ParentAgentResponseExample
{
    public static void SubscribeParentResponse(CopilotSession session)
    {
        session.On<AssistantMessageDeltaEvent>(evt =>
        {
            if (evt.AgentId is null)
            {
                Console.Write(evt.Data.DeltaContent);
            }
        });
    }
}

import com.github.copilot.CopilotSession;
import com.github.copilot.generated.AssistantMessageDeltaEvent;

final class ParentAgentResponseExample {
    static void subscribeParentResponse(CopilotSession session) {
        session.on(AssistantMessageDeltaEvent.class, event -> {
            if (event.getAgentId() == null) {
                System.out.print(event.getData().deltaContent());
            }
        });
    }
}

use github_copilot_sdk::session::Session;

async fn subscribe_parent_response(session: &Session) {
    let mut events = session.subscribe();

    while let Ok(event) = events.recv().await {
        if event.event_type == "assistant.message_delta" && event.agent_id.is_none() {
            if let Some(delta) = event.data.get("deltaContent").and_then(|v| v.as_str()) {
                print!("{delta}");
            }
        }
    }
}

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

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

assistant.turn_start

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

assistant.intent

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

assistant.reasoning

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

assistant.reasoning_delta

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

assistant.message

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

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

assistant.message_delta

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

assistant.turn_end

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

assistant.usage

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

assistant.streaming_delta

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

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

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

tool.execution_start

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

tool.execution_partial_result

Deprecated. Используется tool.shell_output для выходных данных динамического терминала. Это эфемерное событие по-прежнему создается вместе с заменой во время миграции; подписывайтесь только на одно представление, чтобы не отображать одинаковые выходные данные дважды.

tool.shell_output

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

Накапливайте по toolCallId отдельности и streamприсоединяйте text блоки в порядке последовательности для объединенного дисплея. Порядковый номер идентифицирует повторяющиеся и отсутствующие блоки; Он не устанавливает точное упорядочение между независимыми операционными системами записи. Поздний подписчик может получить первую последовательность больше нуля.

Эти события доступны только в режиме реального времени: они не сохраняются или повторяются после возобновления. Окончательные tool.execution_complete результаты, форматирование и отсоединение команды не изменяются. Текст может содержать последовательности элементов управления терминалом; Отрисовщики должны применять обычную обработку текста терминала.

Команда подключенного терминала может выполняться после tool.execution_complete выполнения асинхронно или продолжается дальше initial_wait. Выходные данные, полученные в то время как он продолжает использовать исходный toolCallId и продолжается одинаково sequence, а не перезапускается на нуле. Потребители, которые отображают только активные вызовы, должны игнорировать блоки, полученные после завершения, а не воссоздать состояние завершенного вызова.

Фильтрация секретов работает с каждой декодируемой блокой. Среда выполнения не выполняет искусственное разделение строк, но операции чтения операционной системы могут разделить линию или секрет между блоками; Перекрестная перекрестная реконструкция секрета не предоставляется.

tool.execution_progress

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

tool.execution_complete

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

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

tool.user_requested

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

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

session.idle

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

session.error

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

session.compaction_start

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

session.compaction_complete

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

session.title_changed

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

session.context_changed

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

session.usage_info

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

session.session_limits_changed

Лимиты сессий изменились для текущего бухгалтерского окна. Значение null``sessionLimits означает, что ограничения не активны.

session.usage_checkpoint

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

session.task_complete

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

session.shutdown

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

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

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

permission.requested

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

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

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

Запросы на запись также могут включать fileEdits в себя как permissionRequest , так и promptRequest. Каждая запись содержит необязательный и моментальный before снимок, каждый из которых является абсолютным path в пространстве имен файловой системы сеанса и завершает UTF-8content.after before Отсутствие означает создание; отсутствует after означает удаление. Пустая строка представляет пустой content файл, а не недоступную предварительную версию. Перемещение может иметь разные пути на двух сторонах. При перезаписи перемещения существующего назначения отдельные записи описывают замену источника и назначения.

Эти моментальные снимки описывают плановую операцию, а не более позднюю чтение динамической файловой системы. Среда выполнения не может fileEdits предоставить полную предварительную версию текста, включая запросы, сделанные перед чтением изолированного файла, содержимого, отличного от UTF-8, или нечитаемого или нестандартного назначения перемещения, например именованного канала. Не выводите удаление из пустого устаревшего newFileContents значения. Существующие поля и варианты утверждения остаются доступными для потребителей, которые не используют предварительные версии.

permission.completed

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

user_input.requested

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

user_input.completed

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

elicitation.requested

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

elicitation.completed

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

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

subagent.started

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

subagent.completed

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

subagent.failed

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

subagent.selected

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

subagent.deselected

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

skill.invoked

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

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

abort

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

user.message

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

system.message

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

external_tool.requested

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

external_tool.completed

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

exit_plan_mode.requested

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

exit_plan_mode.completed

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

command.queued

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

command.completed

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

session_limits_exhausted.requested

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

session_limits_exhausted.completed

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

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

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

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
│   ├── permission.completed  → Approval result
│   ├── tool.execution_start  → Tool begins
│   ├── tool.shell_output              → Stream-tagged terminal 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)

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

В этой таблице перечислены ключевые data полезные поля. Общие поля конверта описаны выше.