Eventi di streaming

Abilitando streaming: true in SessionConfig, le attività durante la sessione vengono consegnate come eventi in sequenza. Questa pagina è la versione italiana, resa più leggibile per Laravel, del streaming-events.md ufficiale.

La pagina SessionEvent descrive la classe SessionEvent estesa per Laravel. Questa pagina è la reference su “quale tipo di evento e quali dati arrivano”.

Panoramica

Le attività dell’agente Copilot (reasoning, generazione di messaggi, esecuzione di strumenti, controllo permessi, ecc.) fluiscono come eventi di sessione.

Ephemeral event: solo consegna in tempo reale. Non viene persistito nel log della sessione (non viene riprodotto alla ripresa)
Persisted event: salvato nel log della sessione (riprodotto alla ripresa)
Delta event: evento incrementale (deltaContent ecc.). Concatenandoli si ricostruisce il testo intero
parentId chain: ciascun evento fa riferimento all’ID dell’evento precedente in una catena

Envelope dell’evento (campi comuni)

Tutti gli eventi hanno la seguente struttura comune.

Campo	Tipo	Descrizione
`id`	`string`	ID univoco dell’evento (UUID v4)
`timestamp`	`string`	Ora di creazione (ISO 8601)
`parentId`	`string \| null`	ID dell’evento precedente (`null` per il primo)
`ephemeral`	`boolean?`	`true` se effimero
`type`	`string`	Tipo di evento
`data`	`object`	Payload specifico dell’evento

Esempio di sottoscrizione in Laravel

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SessionEvent;

Copilot::start(function (CopilotSession $session): void {
    // Tutti gli eventi
    $session->on(function (SessionEvent $event): void {
        info($event->type(), $event->toArray());
    });

    // Un evento specifico
    $session->on(SessionEventType::ASSISTANT_MESSAGE_DELTA, function (SessionEvent $event): void {
        echo $event->deltaContent();
    });

    $session->sendAndWait(prompt: 'Illustra le caratteristiche di Laravel');
}, config: new SessionConfig(streaming: true));

Categorie di eventi principali

Assistant events

`assistant.turn_start`

Inizio del turn.

turnId (obbligatorio)
interactionId (opzionale)

`assistant.intent` (ephemeral)

Intenzione di esecuzione corrente (es. Exploring codebase).

intent (obbligatorio)

`assistant.reasoning`

Blocco di reasoning completo.

reasoningId (obbligatorio)
content (obbligatorio)

`assistant.reasoning_delta` (ephemeral)

Delta del testo di reasoning.

reasoningId (obbligatorio)
deltaContent (obbligatorio)

`assistant.message`

Messaggio finale dell’assistente. Campi principali:

messageId (obbligatorio)
content (obbligatorio)
toolRequests (opzionale)
reasoningOpaque / reasoningText / encryptedContent (opzionali)
phase / outputTokens / interactionId (opzionali)
parentToolCallId (opzionale, quando proviene da un sotto-agente)

`assistant.message_delta` (ephemeral)

Delta del corpo del messaggio.

messageId (obbligatorio)
deltaContent (obbligatorio)
parentToolCallId (opzionale)

`assistant.turn_end`

Fine del turn.

turnId (obbligatorio)

`assistant.usage` (ephemeral)

Informazioni di uso per chiamata API. Campi principali:

model (obbligatorio)
inputTokens / outputTokens / cost / duration (opzionali)
apiCallId / providerCallId (opzionali)
quotaSnapshots / copilotUsage (opzionali)

`assistant.streaming_delta` (ephemeral)

Progresso di ricezione a basso livello.

totalResponseSizeBytes (obbligatorio)

Tool execution events

`tool.execution_start`

Inizio esecuzione strumento.

toolCallId (obbligatorio)
toolName (obbligatorio)
arguments / mcpServerName / mcpToolName / parentToolCallId (opzionali)

`tool.execution_partial_result` (ephemeral)

Output parziale durante l’esecuzione.

toolCallId (obbligatorio)
partialOutput (obbligatorio)

`tool.execution_progress` (ephemeral)

Messaggio di progresso.

toolCallId (obbligatorio)
progressMessage (obbligatorio)

`tool.execution_complete`

Esecuzione strumento completata (successo/fallimento).

toolCallId (obbligatorio)
success (obbligatorio)
result (in caso di successo)
error (in caso di fallimento)
toolTelemetry / parentToolCallId (opzionali)

`tool.user_requested`

Chiamata a strumento su richiesta esplicita dell’utente.

toolCallId (obbligatorio)
toolName (obbligatorio)
arguments (opzionale)

Session lifecycle events

`session.start`

Inizio sessione. Nelle Cloud Sessions è più sicuro inviare il primo prompt dopo aver verificato che producer sia copilot-agent in session.start.

producer (opzionale)

`session.idle` (ephemeral)

Elaborazione corrente completata, in attesa del prossimo input.

backgroundTasks (opzionale)

`session.error`

Errore durante l’elaborazione della sessione.

errorType (obbligatorio)
message (obbligatorio)
stack / statusCode / providerCallId (opzionali)

`session.compaction_start`

Inizio compattazione del contesto (data è un oggetto vuoto).

`session.compaction_complete`

Compattazione del contesto completata. Campi principali:

success (obbligatorio)
error (opzionale)
preCompactionTokens / postCompactionTokens (opzionali)
summaryContent / checkpointPath (opzionali)

`session.title_changed` (ephemeral)

Aggiornamento automatico del titolo.

title (obbligatorio)

`session.context_changed`

Cambio del contesto di lavoro.

cwd (obbligatorio)
gitRoot / repository / branch (opzionali)

`session.info`

Informazioni della sessione come URL remoto.

infoType (obbligatorio)
url (opzionale, ad es. quando infoType è remote)

`session.remote_steerable_changed`

Evento che indica il cambio della possibilità di operare a distanza da Mission Control.

remoteSteerable (opzionale)

`session.usage_info` (ephemeral)

Stato di uso della context window.

tokenLimit (obbligatorio)
currentTokens (obbligatorio)
messagesLength (obbligatorio)

`session.task_complete`

Notifica di completamento task.

summary (opzionale)

`session.shutdown`

Chiusura della sessione. Campi principali:

shutdownType (obbligatorio)
errorReason (opzionale)
totalPremiumRequests / totalApiDurationMs (obbligatori)
codeChanges / modelMetrics (obbligatori)

Permission / user input events

`permission.requested` (ephemeral)

Richiesta di conferma di permesso.

requestId (obbligatorio)
permissionRequest (obbligatorio)

permissionRequest.kind:

shell
write
read
mcp
url
memory
custom-tool

`permission.completed` (ephemeral)

Esito della verifica del permesso.

requestId (obbligatorio)
result.kind (obbligatorio)

`user_input.requested` (ephemeral)

Domanda all’utente.

requestId (obbligatorio)
question (obbligatorio)
choices / allowFreeform (opzionali)

`user_input.completed` (ephemeral)

Input utente completato.

requestId (obbligatorio)

`elicitation.requested` (ephemeral)

Richiesta di input strutturato (form).

requestId (obbligatorio)
message (obbligatorio)
requestedSchema (obbligatorio)

`elicitation.completed` (ephemeral)

Completamento dell’input strutturato.

requestId (obbligatorio)

Sub-agent / skill events

`subagent.started`

toolCallId (obbligatorio)
agentName / agentDisplayName / agentDescription (obbligatori)

`subagent.completed`

toolCallId (obbligatorio)
agentName / agentDisplayName (obbligatori)

`subagent.failed`

toolCallId (obbligatorio)
agentName / agentDisplayName (obbligatori)
error (obbligatorio)

`subagent.selected`

agentName (obbligatorio)
agentDisplayName (obbligatorio)
tools (obbligatorio, ammette null)

`subagent.deselected`

Ritorno all’agente predefinito (data è un oggetto vuoto).

`skill.invoked`

name / path / content (obbligatori)
allowedTools / pluginName / pluginVersion (opzionali)

Other events

`abort`

reason (obbligatorio)

`user.message`

content (obbligatorio)
transformedContent / attachments / source / agentMode / interactionId (opzionali)

`system.message`

content (obbligatorio)
role (obbligatorio)
name / metadata (opzionali)

`external_tool.requested` (ephemeral)

requestId / sessionId / toolCallId / toolName (obbligatori)
arguments (opzionale)

`external_tool.completed` (ephemeral)

requestId (obbligatorio)

`exit_plan_mode.requested` (ephemeral)

requestId / summary / planContent / actions / recommendedAction (obbligatori)

`exit_plan_mode.completed` (ephemeral)

requestId (obbligatorio)

`command.queued` (ephemeral)

requestId (obbligatorio)
command (obbligatorio)

`command.completed` (ephemeral)

requestId (obbligatorio)

Ordine tipico degli eventi

assistant.turn_start
├── assistant.intent (ephemeral)
├── assistant.reasoning_delta (ephemeral, più volte)
├── assistant.reasoning
├── assistant.message_delta (ephemeral, più volte)
├── assistant.message
├── assistant.usage (ephemeral)
├── [se necessario permission / tool.* in loop]
assistant.turn_end
session.idle (ephemeral)

Elenco completo degli eventi (riferimento rapido)

Event Type	Ephemeral	Categoria
`session.start`		Session
`assistant.turn_start`		Assistant
`assistant.intent`	✅	Assistant
`assistant.reasoning`		Assistant
`assistant.reasoning_delta`	✅	Assistant
`assistant.streaming_delta`	✅	Assistant
`assistant.message`		Assistant
`assistant.message_delta`	✅	Assistant
`assistant.turn_end`		Assistant
`assistant.usage`	✅	Assistant
`tool.user_requested`		Tool
`tool.execution_start`		Tool
`tool.execution_partial_result`	✅	Tool
`tool.execution_progress`	✅	Tool
`tool.execution_complete`		Tool
`session.idle`	✅	Session
`session.error`		Session
`session.compaction_start`		Session
`session.compaction_complete`		Session
`session.title_changed`	✅	Session
`session.context_changed`		Session
`session.info`		Session
`session.remote_steerable_changed`		Session
`session.usage_info`	✅	Session
`session.task_complete`		Session
`session.shutdown`		Session
`permission.requested`	✅	Permission
`permission.completed`	✅	Permission
`user_input.requested`	✅	User Input
`user_input.completed`	✅	User Input
`elicitation.requested`	✅	User Input
`elicitation.completed`	✅	User Input
`subagent.started`		Sub-Agent
`subagent.completed`		Sub-Agent
`subagent.failed`		Sub-Agent
`subagent.selected`		Sub-Agent
`subagent.deselected`		Sub-Agent
`skill.invoked`		Skill
`abort`		Control
`user.message`		User
`system.message`		System
`external_tool.requested`	✅	External Tool
`external_tool.completed`	✅	External Tool
`command.queued`	✅	Command
`command.completed`	✅	Command
`exit_plan_mode.requested`	✅	Plan Mode
`exit_plan_mode.completed`	✅	Plan Mode

Documenti correlati

Reference ufficiale degli Streaming Events
Descrizione della classe eventi per Laravel: SessionEvent
Pattern di implementazione dello streaming: Streaming

Ultima modifica il 13 luglio 2026

Argomenti correlati

Loop dell'agente Fleet Mode Cloud Sessions Eventi del ciclo di vita della sessione Tecniche pratiche di Laravel Telescope

Streaming

Attachments