Generation
The client has three generation methods. chat() persists successful transcript changes in a Session; completion() and object() are stateless, though all three are metered Turns.
Overview
Every input requires agentId. userId and metadata add Attribution; omitting them selects tenant-level Attribution. signal aborts the request. A literal prompt or message is mutually exclusive with promptId; variables is available only with promptId.
Methods
chat()
The signature is chat(input: ChatInput): Promise<ChatResult>.
ChatInput selects message: UIMessage or promptId: string. Omit sessionId to call POST /v1/agents/:agentId/sessions; the server returns a new ss_ ID through result.sessionId. Pass sessionId to call POST /v1/agents/:agentId/sessions/:sessionId. version is allowed only for a new Session; a resumed Session keeps its immutable Version Pin. trigger defaults to submit-message. regenerate-message is valid only when resuming an existing Session; optional messageId selects where its transcript is truncated.
ChatResult provides sessionId: Promise<string>, toResponse(), and toUIMessageStream(). The response body can be claimed only once.
completion()
The signature is completion(input: CompletionInput): Promise<CompletionResult>.
Calls POST /v1/agents/:agentId/generation with text output. Choose prompt or promptId; optional version, userId, metadata, and signal apply. The result exposes textStream: AsyncIterable<string>, text: Promise<string>, and toResponse().
object()
The signature is object(input: ObjectInput): Promise<ObjectResult>.
Calls POST /v1/agents/:agentId/generation with required schema: Record<string, unknown>. Choose prompt or promptId; the other shared stateless fields are optional. The result exposes partialObjectStream, object: Promise<unknown>, and toResponse().
Types
| Exported type | Contract |
|---|---|
AttributionInput | Optional userId and metadata shared by generation inputs |
ChatTrigger | Either "submit-message" or "regenerate-message" |
ChatMessageInput / ChatPromptInput | agentId plus exactly one message source; optional Session mode, Attribution, trigger, message ID, and signal |
ChatInput | Union of the two chat inputs |
ChatResult | Session ID promise and terminal UI-message stream/response helpers |
CompletionPromptInput / CompletionPromptIdInput | agentId, exactly one Prompt source; optional Version Pin, Attribution, and signal |
CompletionInput | Union of the two completion inputs |
CompletionResult | Text stream, final text promise, and response helper |
ObjectPromptInput / ObjectPromptIdInput | Completion fields plus required JSON schema |
ObjectInput | Union of the two object inputs |
ObjectResult | Partial-object stream, final object promise, and response helper |
BlazingAgentsUIMessage / BlazingAgentsUIMessageChunk | AI SDK message contracts with Blazing Agents metadata |
TerminalStreamResult | One-shot UI-message stream/response helpers, also used by Tool approval continuation |
UIMessage | Public re-export of AI SDK v7's UIMessage type |
See streaming contracts and objects and schemas.
Errors
Pre-response HTTP failures use API codes; transport failures use network_error. Missing Session Location, a claimed chat body, stream decoding failures, or invalid final JSON use stream_error. See protocol errors.
Example
import { BlazingAgents } from "@blazing-agents/sdk";
const client = new BlazingAgents({
apiKey: process.env.BLAZING_AGENTS_API_KEY!,
});
const chat = await client.chat({
agentId: "ag_0123456789abcdef",
message: { id: crypto.randomUUID(), role: "user", parts: [{ type: "text", text: "Hello" }] },
});
console.log(await chat.sessionId);const completion = await client.completion({
agentId: "ag_0123456789abcdef",
prompt: "Write one sentence.",
});
for await (const text of completion.textStream) process.stdout.write(text);const result = await client.object({
agentId: "ag_0123456789abcdef",
prompt: "Return a title.",
schema: { type: "object", properties: { title: { type: "string" } }, required: ["title"] },
});
console.log(await result.object);