Generation and streaming

Generation runs an Agent as a Turn and streams progress before terminal settlement completes. Use chat for stored history and completion for one stateless text result; use structured output when the result must follow a JSON Schema.

Choose stateful chat or stateless text

	`client.chat`	`client.completion`
Input	One AI SDK user `UIMessage`, or a stored Prompt	Literal text, or a stored Prompt
Session and history	Starts or resumes a Session and loads its history	Creates no Session or transcript
Result	UI-message SSE through `toUIMessageStream()` or `toResponse()`; awaited `sessionId`	Text deltas through `textStream`, awaited `text`, or `toResponse()`
Common use	Stateful conversational interfaces	Summaries, rewrites, and other independent text work

Both modes can carry end-user Attribution and use the resolved Agent configuration, Tools, Skills, MCP connections, Memory, and attached Sandbox where configured.

Stream a response

A chat response body can be claimed once: select either the decoded toUIMessageStream() view for server-side chunk handling or toResponse() to relay the untouched AI SDK UI-message SSE body.

Consume a stream once

Calling both chat body methods, or calling either method twice, throws a stream_error. Choose the body view once; sessionId remains independently awaitable.

Completion exposes independent branches for textStream, text, and toResponse(). Consume the branch your backend needs; the SDK derives the final text while streaming and does not promise recovery of an already consumed branch.

const result = await client.completion({
  agentId,
  prompt: "Write a two-sentence release note for passkey login.",
});

let streamed = "";
for await (const delta of result.textStream) {
  process.stdout.write(delta);
  streamed += delta;
}

const finalText = await result.text;
if (streamed !== finalText) {
  throw new Error("Stream and final text differ");
}
console.log("\nVerified final text");

Final values and response relays

For chat, await result.sessionId to retain the server-minted Session ID, then fully drain the selected UI-message stream or return its relay response. If the caller abandons that body before it finishes, cancel the selected stream or abort the supplied signal; cancellation propagates so the chat Turn can settle.

For completion, result.text starts eagerly draining an internal stream branch as soon as the result is built, even if the caller never awaits the promise. textStream and toResponse() are separate branches for observation or relay; their consumption is not what drives terminal settlement. Await result.text when the application needs the complete text, and pass signal when it needs to cancel the Turn itself.

chat().toResponse() returns AI SDK UI-message SSE for a frontend chat transport. completion().toResponse() returns the AI SDK text-stream response. See connect your app and the streaming protocol before adding a protocol adapter.

Image input and regeneration

Chat accepts one user message containing text parts and image file parts. Each image needs a non-empty URL and an image/* media type; filename is optional.

const message = {
  id: "message-image-1",
  role: "user" as const,
  parts: [
    { type: "text" as const, text: "Describe this diagram." },
    { type: "file" as const, mediaType: "image/png", url: imageUrl },
  ],
};

To regenerate an existing response, resume its Session with trigger: "regenerate-message" and optionally identify the visible message boundary with messageId. Regeneration is invalid on a new Session.

const regenerated = await client.chat({
  agentId,
  sessionId,
  message,
  trigger: "regenerate-message",
  messageId: "message-2",
});

See image input and regeneration for the complete application flow.

Abort, errors, and settlement

Pass an AbortSignal as signal; the SDK forwards it to the request and cancellation propagates into the Turn. Agent resolution, validation, quota, and similar failures before streaming starts reject the SDK call as a typed HTTP error.

After chat SSE starts, a native server-generated { type: "error", errorText } chunk represents Turn failure. It remains a valid AI SDK chunk, not transcript content. Malformed SSE or a transport failure instead makes the decoded toUIMessageStream() reject with a BlazingAgentsError whose code is stream_error; toResponse() relays the raw SSE body without decoding it.

For completion, textStream propagates the underlying transport error. Only the awaited text normalizes that failure to BlazingAgentsError with code stream_error. Every terminal outcome still settles usage, including model failure and cancellation.

Persistence and usage

Successful chat commits its accepted exchange to the Session; failed or cancelled chat does not. Completion remains a metered Turn, resolves an Agent Version, and records Attribution and usage, but creates no Session or transcript.

Stored Prompts can replace literal input in either mode. Prompt expansion happens before execution and only the rendered text enters a chat transcript.