> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventi di streaming

> Riepilogo dei tipi di Session Event e dei relativi payload disponibili quando abiliti lo streaming in SessionConfig.

## 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](/it/packages/laravel-copilot-sdk/session-event) 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

```php theme={null}
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

```text theme={null}
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](https://github.com/github/copilot-sdk/blob/main/docs/features/streaming-events.md)
* Descrizione della classe eventi per Laravel: [SessionEvent](/it/packages/laravel-copilot-sdk/session-event)
* Pattern di implementazione dello streaming: [Streaming](/it/packages/laravel-copilot-sdk/streaming)


## Related topics

- [Loop dell'agente](/it/packages/laravel-copilot-sdk/agent-loop.md)
- [Fleet Mode](/it/packages/laravel-copilot-sdk/fleet-mode.md)
- [Cloud Sessions](/it/packages/laravel-copilot-sdk/cloud-sessions.md)
- [Eventi del ciclo di vita della sessione](/it/packages/laravel-copilot-sdk/session-lifecycle-event.md)
- [Tecniche pratiche di Laravel Telescope](/it/blog/telescope-introduction.md)