Prompts and streaming

Each conversation is a session. Each prompt() starts a turn in that session, which streams events while it runs and ends with a result.

Read the reply

const turn = agent.session().prompt('Explain how a database index speeds up a query.')
for await (const event of turn) {
  if (event.type === 'text_delta') process.stdout.write(event.delta)
}
const result = await turn.result
console.log(result.stopReason, result.usage)

The turn runs whether or not you read its events, so you can await turn.result alone. Reading the events doesn't consume them, so several readers each get every event.

result.stopReason says how the turn ended, such as end_turn, max_output_tokens, or cancelled. A turn that fails still resolves its result, with the stop reason error and the reason in result.error. TurnResult lists every stop reason.

prompt() throws, and stores nothing, for input libfx would refuse: an empty prompt, invalid image data, or input that with the session's context and settings comes to more than 8 MiB of JSON. That last error has the code FX_INPUT_TOO_LARGE.

Continue the conversation

A session keeps the previous prompts, replies, and tool results. Keep its id, and prompt it again from any process that creates the same agent:

const { sessionId } = await turn.accepted

agent.session(sessionId).prompt('Give me an example.')

turn.accepted resolves once the prompt is stored. A session runs one turn at a time: a prompt sent while a turn runs waits behind it, even when it reaches another server. To add instructions to the running turn instead, use steering.

Each session can bring its own model, instructions, and tool context. They apply to the turns that session object starts:

agent.session(sessionId, {
  model: { id: 'anthropic/claude-opus-5.5', effort: 'high' },
  instructions: 'You review pull requests.',
  context: { userId },
})

For a program with a single conversation, agent.prompt() prompts a session the agent opens for itself.

Handle events

EventDescription
text_deltaA piece of the reply
reasoning_deltaReasoning text, when the model supplies it
tool_startA tool call has started
tool_endA tool call has completed or failed
user_messageSteering instructions entered the conversation

TurnEvent lists the fields.

Stream to a browser

turn.readable is the turn as newline-delimited JSON, ready to return from a route. session.stream(cursor) returns the session's lines after cursor and stays open for new ones:

// app/api/chat/route.js
import { agent } from '@/lib/agent'

export async function POST(request) {
  const sessionId = new URL(request.url).searchParams.get('sessionId') ?? undefined
  // Check that the caller may use this session.
  const turn = agent.session(sessionId).prompt(await request.text())
  return new Response(turn.readable)
}

export async function GET(request) {
  const params = new URL(request.url).searchParams
  const sessionId = params.get('sessionId')
  if (!sessionId) return new Response('sessionId is required', { status: 400 })
  // Same check as POST.
  return new Response(agent.session(sessionId).stream(Number(params.get('cursor') ?? 0)))
}

Each line is a JSON object. Besides the events above, a turn writes turn_start, which carries the sessionId, and turn_end, which carries the stop reason. A turn that stops at a function's time limit writes turn_yield, and the process that continues a stopped turn writes turn_resume. Lines from session.stream() are numbered with a cursor from 1. When a client loses its connection, it calls GET with the last cursor it read, from any server, and continues after it. StreamLine lists every line.

Avoid duplicate prompts

If a client might send the same request twice, give the prompt a messageId:

agent.session(sessionId).prompt(text, { messageId: clientMessageId })

A prompt with an id the session already accepted runs nothing new. It follows the original turn, and its result has repeated: true.

Stop a turn

Call session.cancel(), or pass an AbortSignal as the prompt's signal. A signal cancels only its own prompt's turn, whether it's running or still waiting. Cancellation can't undo tool actions that already finished.

libfx turns have no fixed model-step limit. Cancel turns that exceed your application's time or usage budget.

When your process is done, call await agent.close(). It waits for the turns this process is running, then lets their sessions go.