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 routes

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

The SSE envelope

POST /agent/chat and GET /agent/chat/:runId/stream reply with Content-Type: text/event-stream and this exact frame sequence:

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

data: {"delta":"The "}
data: {"delta":"weather "}
data: {"delta":"in Lisbon is 21°C."}

event: done
data: {}

• A single meta frame first, carrying the runId and threadId.
• One data frame per streamed chunk, each {"delta": "<text>"}.
• A terminating done frame when the run completes.

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.

Human-in-the-loop

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.

Re-attaching to a run

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 activeStreamId, a reloading client can find the in-flight run and rejoin its stream.

Consuming the stream

The package ships the client. @adonis-agora/agent/client posts a turn, decodes the envelope above into typed frames, and re-attaches automatically when the connection drops; @adonis-agora/agent/react wraps it in a useAgentChat hook:

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

function Chat() {
  const { messages, status, error, send, cancel } = useAgentChat({ basePath: '/agent' })
  // messages[].parts is ChatPart[] — text and component parts in emission order
}

Both are covered in full — options, resume semantics, component frames, and the HITL calls the client deliberately leaves to you — in Browser client & React.

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, and treat an unnamed event as a text delta.