Skip to main content
POST
/
api
/
agent
/
chat
/
stream
Stream an agent chat run
curl --request POST \
  --url https://app.puffle.ai/api/agent/chat/stream \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "messages": [
    {}
  ],
  "conversationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "currentPage": "<string>"
}
'
{
  "error": "Internal server error"
}

​
Overview

Streams agent output as an AI SDK UI message stream. The response is not JSON — it’s a chunked SSE-style text/event-stream produced by the AI SDK’s toUIMessageStreamResponse(). Use this for real-time chat UIs that want text deltas, tool-call starts/results, step boundaries, and step-finish usage telemetry as they happen. The conversation id is echoed in the x-conversation-id response header.

​
AI agent notes

Admin-only. 120 s max duration. The request will be terminated after 120 seconds even if the agent hasn’t finished — budget accordingly.Tool-approval protocol. When a tool requires human approval, the server pauses the stream and waits for a follow-up request carrying approvalResponse: { toolCallId, approved }. The caller’s messages should include the pending tool call so the server can resume with the frozen args or the rejection result.Body shape — AI SDK UI messages. messages is the standard AI SDK UI message array (not plain chat messages). On first turn, send the user’s message as a UI message; on subsequent turns, send the full accumulated history.Runtime. Node runtime (runtime = "nodejs"). Streams terminate early on client disconnect via abortSignal.Related: Start an agent chat run (async poll), Run an agent chat synchronously (blocking).

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
messages
object[]
required

AI SDK UI messages array. Typically the full conversation so far, with the new user turn appended.

​
conversationId
string<uuid>
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
​
currentPage
string

Optional hint about which page the user is on, passed to the system prompt for context.

​
approvalResponse
object

Sent when resuming after a tool-approval gate. The server executes the frozen tool call (or rejects it) and splices the result back into the stream.

​
{key}
any

Response

SSE stream. Events follow the AI SDK UI message format — text deltas, tool-call starts/results, step boundaries, step-finish with usage, stream-finish. Header x-conversation-id carries the conversation the run is writing to.