Readable Streams

Use @anvia/server when an HTTP route should return streaming agent events. The package can serialize any AsyncIterable as newline-delimited JSON or Server-Sent Events.

1. Stream an Agent Request

import { createEventStream } from "@anvia/server";

return createEventStream(agent.prompt("Draft a reply.").stream(), {
  format: "jsonl",
});

createEventStream(...) returns a Response with streaming headers and an encoded body.

2. Choose JSONL or SSE

return createEventStream(agent.prompt("Draft a reply.").stream(), {
  format: "sse",
});

JSONL is the default and is usually the best fit for chat APIs because it works naturally with fetch, POST bodies, auth headers, and cancellation. SSE is available when you need text/event-stream compatibility.

JSONL writes one JSON event per line:

{"type":"text_delta","turn":1,"delta":"Hello"}
{"type":"final","output":"Hello","usage":{"totalTokens":12}}

SSE writes JSON event payloads in data: fields:

data: {"type":"text_delta","turn":1,"delta":"Hello"}

3. Use Lower-Level Stream Helpers

import { createJsonlStream, createSseStream } from "@anvia/server";

const jsonl = createJsonlStream(agent.prompt("Draft a reply.").stream());
const sse = createSseStream(agent.prompt("Draft a reply.").stream());

Use these helpers when your framework creates the Response object for you.

4. Handle Stream Errors

If iteration fails, @anvia/server emits one final event with type: "error" and then closes the stream.

{"type":"error","error":{"name":"Error","message":"provider failed"}}

Clients should handle both final and error events.

For React clients, see Client Transports.