Streaming & HTTP

The provider mounts eleven core routes under config.path (default agent) at boot. They cover the full chat lifecycle — start, stream, cancel, HITL, threads, and quota. No controllers to write; the provider resolves the actor, calls the framework-agnostic AgentService, and pipes the SSE.

Five optional surfaces mount only when their configuration is present:

The routesCopy Anchor Link

The persona catalog route is registered before threads/:id so it isn't captured by the :id param.

The SSE envelopeCopy Anchor Link

POST /agent/chat and GET /agent/chat/:runId/stream reply with Content-Type: text/event-stream, written in the chat stream protocol compatible with Aviary: one AgentStreamEvent JSON object per data: frame. Agora's local React transport, useAgentChat, transcript model and @adonis-agora/agent/client read it unchanged.

event: meta
data: {"runId":"<uuid>","threadId":"<uuid>"}

data: {"kind":"step-start"}

data: {"kind":"reasoning","text":"The user wants…"}

data: {"kind":"tool-input-available","id":"c1","name":"weather","input":{"city":"Lisbon"},"toolKind":"read"}

data: {"kind":"tool-output","id":"c1","output":{"tempC":21}}

data: {"kind":"step-finish","usage":{"inputTokens":812,"outputTokens":40},"costUsd":0.0004}

data: {"kind":"step-start"}

data: {"kind":"text","text":"It is 21°C in Lisbon."}

data: {"kind":"step-finish","usage":{"inputTokens":870,"outputTokens":9},"costUsd":0.0001}

data: {"kind":"title","title":"Weather in Lisbon"}

event: done
data: {}

The vocabulary remains compatible with Aviary's stream protocol (AgentStreamEvent, exported from this package too). What this package writes:

Every event frame carries an SSE id: — its 1-based position in the run (id: 7 above data: {"kind":"text",…}). The number belongs to the frame, not the connection: the same frame has the same id on the POST that started the run and on every later GET …/stream. GET /agent/chat/:runId/stream?after=<n> (or the standard Last-Event-ID header; after wins) sends only the frames numbered above n, still preceded by meta — which is how the Agora React client resumes a dropped stream without re-rendering what it has. meta, done and error carry no id. When nothing is buffered under the run any more (it ended while the client was away, its buffer passed the sink's replay window, or it went with a restarted process), the route answers 404, read as "nothing to resume"; a sink reports that through the optional TokenStreamSink.has (the in-process, in-memory and Redis sinks implement it).

A failed run ends with event: error + data: {"code","message"} instead of done; the codes are quota_exceeded, output_rejected, structured_output_invalid and run_failed.

Frames are written from inside the loop's existing checkpoints, so a durable replay never streams one twice and no checkpoint moved.

The response also sets X-Agent-Run-Id and X-Agent-Thread-Id headers (plus Cache-Control: no-cache, no-transform and X-Accel-Buffering: no so proxies don't buffer the stream). The stream ends only on run completion — the token sink stays open across a HITL suspend, so an approved-then-resumed run keeps one continuous stream. When the client closes the connection first, the route (native, AG-UI and A2UI alike) ends its subscription to the run; the run itself keeps going.

Persisted historyCopy Anchor Link

GET /agent/threads/:id returns the messages a reload rebuilds the transcript from. Besides content, toolCalls/toolResults and attachments, an assistant message carries what its step streamed, so a reloaded thread shows what the live one did:

They are read off the frames inside the model call's own checkpoint, so a durable replay persists the same values rather than re-measuring a turn that is not happening. A provider may also report them itself on ModelTurnResult (reasoning, reasoningMs, ui); its values win. @adonis-agora/agent/react's storedThreadToUiMessages replays them as reasoning and data-ui parts.

ModelsCopy Anchor Link

A turn's model is the send's model, else the thread's pinned model, else the provider's default. The simple way to offer a picker is aiSdkModels — several models behind one provider, which carries its own catalog:

import { aiSdkModels } from '@adonis-agora/agent/ai-sdk'
import { openai } from '@ai-sdk/openai'

export default defineConfig({
  model: () =>
    aiSdkModels(
      {
        'openai/gpt-4o-mini': { model: openai('gpt-4o-mini'), label: 'GPT-4o mini', badges: ['fast'] },
        'openai/gpt-4o': { model: openai('gpt-4o'), label: 'GPT-4o' },
      },
      { default: 'openai/gpt-4o-mini', providerLabels: { openai: 'OpenAI' } },
    ),
})

With no models in the config, GET /agent/models serves that catalog and a turn runs on the picked id. aiSdkModel(model) serves one model and refuses a pick naming another (the turn fails) rather than silently answering on a model nobody chose.

A send's model applies to that turn only — the server never stores it on the thread, whether the send creates the thread or continues one. Pinning is its own request, PATCH /agent/threads/:id { model } (null unpins), and only a pin outlives the turn.

Locking an agent to one model. A catalog that answers locked: { model, reason? } for an agent runs every turn of that agent on locked.model, whatever the send or the thread's pin names, and refuses a send naming another model with 400 (code: 'model_not_allowed'). GET /agent/agents reports it as lockedModel. List the other models as unavailable as well, so a client that predates the field cannot pick them.

To decide per caller (plan, budget, provider health), set models to a ModelCatalog — list({ actor, agent }) returns the same view, with available: false and an unavailableReason for what the caller cannot use right now — or to a literal view for a fixed list. The server refuses (400) any model the catalog does not list as available, on a send and when pinning — a client only ever sends ids the catalog listed, but the server does not trust that. The picked id reaches the provider as ModelTurnArgs.model. The pick rides the run's input, so a durable replay runs on the same model, and it labels the turn's usage when the provider reports no model id.

Regenerating an answerCopy Anchor Link

POST /agent/chat { threadId, regenerate: true } answers the thread's last user message again — the retry button under the last answer. The server requires threadId (400, code: 'thread_required', without one) and the caller's own thread; stores no user message (message is ignored — the stored one is answered); drops the answer(s) after that user message, so the model does not see the answer it is replacing; and streams the new answer as a normal run under a new runId. model, agent and pageContext apply as on any send. The truncation is its own durable step (regenerate:truncate), so a replay never truncates twice and a normal turn journals exactly what it always did.

Message queueCopy Anchor Link

A person can keep typing while a turn is running. A message sent then is queued on the thread, server-side — it survives a reload, a closed tab, another device — and runs as soon as the turn ahead of it settles, exactly as if it had been sent then. It is not part of the transcript until it runs: the turn it starts appends it as its user message. The queue contract remains compatible with Aviary; Agora's local React client exposes it through chat.queue.

POST /agent/chat takes mode:

The 202 body is { queued: true, threadId, messageId, position, queue: { items, paused }, runId?, interrupting? } — position is 0-based (0 runs next), runId is present only when the message started straight away, and a queued message's run id is its own messageId, so a client can name the run before it starts. Everything a send carries (agent, model, attachments, pageContext) is resolved and checked when it is queued (400 / 403 / 429 then, not later) and stored with the message; the actor is the one who queued it. The turn it starts records when it was queued (or the send's own sentAt) as the message's sentAt, so messageTimestamps shows the model when it was sent, not when its turn began. regenerate is refused with 409 { code: 'run_active' } while a turn runs.

When the turn holding the thread settles, the server decides what follows before writing that turn's terminal frame, and announces it as the stream's last event — {"kind":"queue","queue":{…},"started":{"messageId","runId"}} (attach to the new run with GET /agent/chat/:runId/stream), or a queue.paused saying why nothing starts:

The head's actor is checked against the quota as it starts; an exhausted budget pauses the queue (quota_exceeded) instead. A paused queue keeps every message and starts nothing until POST /agent/threads/:id/queue/resume. Every change to the queue while a turn holds the thread (queued, edited, moved, removed) is also written into that turn's stream as a queue event — a whole snapshot, never a delta. GET /agent/threads/:id carries queue too.

One turn per thread. The thread's active run (activeRunId) is the admission lock, and every write to it is a compare-and-set (claimActiveStream / releaseActiveStream on the store), so a settling run on a worker and a send on a web pod cannot both start a turn. A holder that is no longer running (a process that crashed mid-turn) is replaced by the next send or resume rather than queued behind for ever. With the durable runner the handoff is journaled (queue:completed / queue:failed local steps behind ctx.patched('agent:chat-queue'), then ctx.startChild under the message's id), so a replay never starts a message twice and a run in flight when you upgrade replays the history it has.

The queue needs a store that implements ChatQueueStore — the Lucid store (table agent_queued_message, column agent_thread.queue_pause; both created by createAgentTables) and the in-memory store do. A custom store that does not keeps the old behaviour (a send on a busy thread starts a second, concurrent turn) and the queue routes answer 501; CHAT_QUEUE_STORE_CONTRACT in @adonis-agora/agent/testing checks an implementation of your own.

Human-in-the-loopCopy Anchor Link

When the model calls an action tool, the run records it pending_approval and pauses. The client learns the pending toolCallId from the thread detail (GET /agent/threads/:id → the tool call's status), then decides:

# approve
curl http://localhost:3333/agent/tool-call/approve \
  -H 'content-type: application/json' \
  -d '{"runId":"<runId>","toolCallId":"<toolCallId>"}'

# or reject, optionally with a reason fed back to the model
curl http://localhost:3333/agent/tool-call/reject \
  -H 'content-type: application/json' \
  -d '{"runId":"<runId>","toolCallId":"<toolCallId>","reason":"not this account"}'

On approve, the loop runs the tool and continues, recording who approved it. On reject, it records the rejection and feeds a rejection result back to the model, which continues the turn. A decision is always scoped to one (runId, toolCallId) pair, so one run can never approve another's call. runId may be omitted — a tool call id is unique, so the route reads the run off the call's own row (AgentStore.getToolCallRunId) and answers 404 for a call it does not know. That is the body @adonis-agora/agent/react sends; the same holds for tool-call/answer and tool-call/skip.

Both decision routes take two optional fields: via names the surface the decision came through ('web' when omitted, 1–64 characters) and remember: true (approve only) approves later calls of the same tool in the same thread without asking again. A malformed one is a 400.

Approval policyCopy Anchor Link

By default the person chatting approves every action call, and a request never lapses. approvalPolicy in config/agent.ts changes who and for how long:

export default defineConfig({
  // …
  approvalPolicy: {
    ttlMs: 15 * 60_000, // every request lapses after 15 minutes
    tools: {
      refund: { approver: 'FINANCE' }, // a role decides refunds
      lookupInvoice: { required: false }, // an action that runs without asking
    },
  },
})

That shorthand covers most deployments. For a decision per actor, thread or agent, pass a whole ApprovalPolicy — requirementFor(tool, actor, thread) returns { required, approver, ttlMs? }, and an optional canDecide(actor, { toolCallId, approver, requesterRef }) replaces the default "holds that role" rule (plug an authz gate in there):

import { REQUESTER_APPROVER, type ApprovalPolicy } from '@adonis-agora/agent'

const approvalPolicy: ApprovalPolicy = {
  requirementFor: (tool, actor) =>
    tool.spec?.ability === 'billing.refund'
      ? { required: true, approver: 'FINANCE', ttlMs: 3_600_000 }
      : { required: true, approver: REQUESTER_APPROVER },
  canDecide: (actor, decision) => actor.roles?.includes(decision.approver) === true,
}

What changes on the wire and the routes:

• Who. approval-requested carries the approver. For the requester, the approve/reject routes keep the ownership check they always had. For any other approver the caller must pass canDecide, else 403 — including the person chatting.
• Until when. With a ttlMs the frame carries expiresAt, and the run waits at most that long: the inline runner arms a timer, the durable runner hands the time to its signal wait's own timeout (a deadline the runtime journals, so it survives a restart). Nobody deciding in time settles the call expired: approval-settled { status: 'expired' }, then tool-output-denied with reason approval expired, and the model is told the approval lapsed — not that someone said no. A decision on a lapsed request answers 410.
• How it settled. approval-settled names decidedBy, decidedVia and remember (or reason on a rejection). A remembered approval streams approval-settled { decidedVia: 'remembered' } without asking.
• History. GET /agent/threads/:id returns each message's approvals: [{ toolCallId, approver, expiresAt?, status, remember?, decidedBy?, decidedVia?, reason? }].

The requirement is decided inside the call's own persist:toolcall checkpoint, so a parked durable run keeps the answer it was given even if the policy changes while it waits. The Lucid store adds four nullable agent_tool_call columns for it (approver, expires_at, remember, decided_via); a custom AgentStore opts in with rememberedApprovals and toolCallApproval (both optional).

Re-attaching to a runCopy Anchor Link

Streams survive a dropped connection. A late subscriber to GET /agent/chat/:runId/stream replays the run's buffered chunks first, then follows live until done. Combined with the thread's activeRunId, a reloading client can find the in-flight run and rejoin its stream.

Consuming the streamCopy Anchor Link

The package ships both consumers. In React, @adonis-agora/agent/react is the whole layer — the provider, useAgentChat, the transcript model, the queue, approvals, attachments:

import { AgentProvider, useAgentChat } from '@adonis-agora/agent/react'

function Chat() {
  const { transcript, composer, queue } = useAgentChat() // under <AgentProvider>
}

See React. Outside React, @adonis-agora/agent/client posts a turn, decodes the envelope above into typed frames, and re-attaches automatically when the connection drops — see Browser client.

For a non-JavaScript consumer, or a bespoke reader, the envelope above is the whole contract: read text/event-stream, dispatch on the event: name (meta, error, done), and read an unnamed event as an AgentStreamEvent dispatched on its kind — tolerating kinds you do not know. The NestJS library's React package works against this server as-is.