Streaming Threads

Build a multi-turn chat experience with server-sent events.

Streaming threads are for chat interfaces and long-running agent responses. The API streams events as the run progresses and returns a thread ID that can be reused on later turns.

Endpoint

POST /api/v1/agents/{agent_id}/stream/threads

To continue an existing conversation, pass the thread ID as a query parameter.

POST /api/v1/agents/{agent_id}/stream/threads?thread_id=thread_123

Request

{
  "query": "Can you compare the two uploaded policies?",
  "documents": [
    "https://signed-url.example/policy-a.pdf",
    "https://signed-url.example/policy-b.pdf"
  ],
  "metadata": {
    "source": "docs_comparison"
  }
}

JavaScript Example

const response = await fetch(
  "https://api.fluo.one/api/v1/agents/agent_123/stream/threads",
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-project-id": process.env.FLUO_PROJECT_ID!,
      "x-api-key": process.env.FLUO_API_KEY!,
    },
    body: JSON.stringify({
      query: "Write a short welcome message.",
    }),
  }
);

if (!response.ok || !response.body) {
  throw new Error(`Stream failed: ${response.status}`);
}

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value, { stream: true });
  console.log(chunk);
}

Event Types

The stream uses server-sent events. Depending on the agent and tools involved, clients may receive:

EventMeaning
run_startA run has started. May include the thread ID.
message_deltaA partial assistant text update.
message_finalThe assistant message has completed.
thinking_partOptional reasoning or progress detail.
tool_startA tool call has started.
tool_endA tool call has completed.

Thread Handling

Store the thread ID when you want to continue the conversation. If you omit thread_id, Fluo creates a new thread.

Thread IDs are application state:

Treat thread IDs like conversation identifiers. They are not credentials, but they may reveal user workflow state, so store and transmit them carefully.