Streaming Events

Use .stream() when your UI, worker, or API route needs incremental updates instead of waiting for the final response.

1. Start a Stream

for await (const event of agent.prompt("Write a short reply.").stream()) {
  if (event.type === "text_delta") {
    process.stdout.write(event.delta);
  }
}

The agent's completion model must support streaming. If the model does not support streaming, Anvia throws before the run starts.

2. Handle the Core Events

for await (const event of agent.prompt("Where is order A-100?").stream()) {
  switch (event.type) {
    case "text_delta":
      process.stdout.write(event.delta);
      break;
    case "tool_call":
      console.log("tool_call", event.toolCall.function.name);
      break;
    case "tool_result":
      console.log("tool_result", event.toolName, event.result);
      break;
    case "agent_tool_event":
      console.log("child agent", event.agentId, event.event.type);
      break;
    case "final":
      console.log("done", event.output);
      break;
  }
}

3. Know the Event Order

Most text-only runs look like this:

turn_start
text_delta
text_delta
turn_end
final

Tool runs can span multiple turns:

turn_start
tool_call
turn_end
tool_result
turn_start
text_delta
turn_end
final

Streaming agent-tools add nested child events between the parent turn_end and final parent tool_result:

turn_start
tool_call
turn_end
agent_tool_event turn_start
agent_tool_event text_delta
agent_tool_event tool_call
agent_tool_event tool_result
agent_tool_event final
tool_result
turn_start
text_delta
turn_end
final

4. Event Types

The final event contains the same important data as .send(): output, usage, messages, and optional trace.

reasoning_delta may include contentType and signature metadata. Render summaries or your own internal debug UI deliberately; encrypted and redacted blocks are opaque provider state for history continuity.

agent_tool_event wraps the child event with toolName, internalCallId, optional provider toolCallId, and the child agentId/agentName. Use those fields to group nested progress in UIs. The parent model still receives only the final child output as the normal tool_result.

The final event includes runId. Use it with Event Store when you need to load the persisted event log after the stream ends.