useLoushoAgent() puts an agent behind a chat UI. It runs a turn, reads the
typed event stream as it arrives and turns it into
render-ready state: messages with their text and tool calls, a status for
the composer, and the tool call waiting for approval, if any.
It lives in the lousho/react subpath. react (18 or 19) is
an optional peer dependency: install it in the app that uses the hook.
Sources
The first argument says where the agent runs.
In-process mode is for React code that runs where the agent can (Electron,
React Native, tests). In a browser, use the remote mode: model API keys belong
on the server.
Returned state
Unmounting the component aborts the turn in flight. Events of a
sub-agent’s run (they carry
subagent) do not change
messages — except a sub-agent’s approval.requested, which does update
messages, pendingApproval and status (the pause is the user’s to decide).
Read other sub-agent events from lastEvent if you want to show them.
Approvals
When a tool withneedsApproval is called, the run stops with
approval.requested. status becomes 'awaiting-approval' and
pendingApproval holds the call. Then:
- In process,
approve(note?)andreject(note?)callagent.approvals.streamResolve({ id, approved, note }, { signal })(see Approvals). The continued run’s events stream in live, so its text is appended to the assistant message as it arrives andstatusreturns to'idle', or to'awaiting-approval'if the run pauses again. - Remote, pass
{ approvalsUrl }as the second argument. The hook POSTs{ "approved": true, "note": "..." }to${approvalsUrl}/${approvalId}and shows the continuation live from the SSE stream the session API answers with (the same events as a chat turn; a second pause arrives asapproval.requested). A server that answers with anApprovalOutcomeJSON instead (the one below) still works. - Remote without
approvalsUrl,approve()andreject()do nothing. ShowpendingApprovaland resolve it through your own API, thensend()the next turn.
askQuestion: true can ask the user something (see
Asking the user a question). The
pause arrives the same way, with pendingApproval.kind === 'question': show
pendingApproval.question.text and its options, and call answer(text).
The server side
A Node endpoint for the remote mode, with the approvals route (thevendor/
model prefix chooses the provider; with OpenRouter use
openrouter/<vendor>/<model>, e.g. openrouter/openai/gpt-4o-mini):
useLoushoAgent({ url: '/api/agent' }, { approvalsUrl: '/api/approvals' }).
For a multi-turn chat, keep an agent.session({ id }) per conversation on the
server and call session.stream() instead of agent.stream(). Give the agent
a store (createAgent({ store: memoryStore() }), or a durable one) when
sessions are opened per request: without one each agent.session({ id })
gets a fresh in-memory transcript and the next turn forgets the first (see
Choosing a store).
In process
The hook takes the agent itself, too. Called from a custom hook:Without React
The hook is a thin wrapper. The state logic isreduceAgentEvents(state, event), a pure reducer over AgentEvents and a few local actions
(ui.send, ui.decide, ui.resumed, ui.stopped, ui.reset, ui.error), and
parseEventStream(response) reads events back from a fetch response. Both are
exported from the same subpath, for a custom binding or a non-React client:
parseEventStream() skips blank lines, SSE comments and event:/id:
fields, and any line that is not a known event, so it reads both framings.
Breaking out of its loop cancels the response body.
Todos
An agent that has the todo tools emits atodo.updated event for every todo_write; the hook keeps the latest list in
todos, and useTodos(agent) turns it into a view with counts, the item being
worked on and the progress. It takes the hook’s result, so one stream feeds the
chat and the plan. The list carries across turns and is cleared by nothing but a
new hook (it is not restored when the page reconnects to an existing session).
current is the in_progress item, else the first pending one, and undefined
when nothing is left; progress is completed / total (0 for an empty list).
The view is memoized on agent.todos. todoView(todos) computes the same view
outside React.