React integration

@opencomputer/react provides one hook, useAgent. It renders a session’s messages, streams new turns and sends input. The session comes from one of two places:

Attach to a session your server created. This is the pattern for any application that keeps its API key on the server and chooses what a session may do there, including every application that binds memory.
Create a session from the browser during development, through the authenticated development bridge.

npm install @opencomputer/react

Attach to a server-created session

Three pieces: your server creates the session, your server proxies three routes under its own authentication, and the browser attaches with the session id.

1. Create the session on the server

Create the session where the API key lives. With memory, that is also where the bindings are chosen; the browser can neither see the key nor change what the session may read or write. startSessionOnDocument from @opencomputer/sdk creates the document if it does not exist yet, then the session bound to it, both converging under one idempotency key (details):

import { startSessionOnDocument } from "@opencomputer/sdk";

const { session } = await startSessionOnDocument({
  apiKey: process.env.OPENCOMPUTER_API_KEY!,
  projectId: process.env.OPENCOMPUTER_PROJECT_ID!,
  environment: "development",
  agent: "<agent-id>",
  resource: "notes",
  documentId: "workshop",
  document: { title: "Workshop notes" },
  idempotencyKey: `workshop/${user.id}`,
});
// Store session.id with the workshop; the browser attaches to it.

Without memory, POST /api/managed-agents/sessions with x-api-key and { "agentId": "<agent-id>@development" } returns { session: { id } }. Both are management API calls.

2. Proxy three routes

The hook needs exactly these management API routes, relative to its basePath:

Route	Purpose
`GET /sessions/<id>/events?after=<seq>`	The durable event log from a cursor; history and live turns
`POST /sessions/<id>/turns`	A new turn: `{ input, idempotencyKey }`
`POST /sessions/<id>/interrupt`	Stop the running turn

Expose them under your own authentication, check that the signed-in user may use that session, and forward to OpenComputer with the API key. A Next.js route handler that serves all three:

// app/api/agent/sessions/[id]/[action]/route.ts
const allowed: Record<string, string[]> = { GET: ["events"], POST: ["turns", "interrupt"] };

async function proxy(request: Request, { params }: { params: Promise<{ id: string; action: string }> }) {
  const { id, action } = await params;
  const user = await requireUser(request); // your session cookie or token
  if (!allowed[request.method]?.includes(action) || !(await userOwnsSession(user, id))) {
    return new Response(null, { status: 404 });
  }
  const upstream = await fetch(
    `https://app.opencomputer.dev/api/managed-agents/sessions/${encodeURIComponent(id)}/${action}${new URL(request.url).search}`,
    {
      method: request.method,
      headers: { "x-api-key": process.env.OPENCOMPUTER_API_KEY!, "content-type": "application/json" },
      body: request.method === "POST" ? await request.text() : undefined,
    },
  );
  return new Response(upstream.body, { status: upstream.status, headers: { "content-type": "application/json" } });
}

export const GET = proxy;
export const POST = proxy;

The turn body carries an idempotencyKey the hook generates per send, so a retried request does not start a second turn. Forward request bodies and responses unchanged; the hook reads { events }, { turnId } and the error envelope { error: { message } }.

3. Attach in the browser

import { useState } from "react";
import { useAgent } from "@opencomputer/react";

export function WorkshopChat({ sessionId, onNotesChanged }: { sessionId: string; onNotesChanged: () => void }) {
  const { messages, send, stop, isReplaying, isRunning, error } = useAgent({
    sessionId,
    basePath: "/api/agent",
    onMemorySaved: onNotesChanged,
  });
  const [draft, setDraft] = useState("");

  async function submit() {
    await send(draft); // rejects when no turn was admitted
    setDraft(""); // clear only once the platform has the input
  }

  return (
    <section>
      {isReplaying ? <p>Loading the conversation…</p> : null}
      {messages.map((message) => (
        <p key={message.id}>
          <strong>{message.role}:</strong> {message.text}
        </p>
      ))}
      <input value={draft} onChange={(event) => setDraft(event.target.value)} />
      <button onClick={() => submit().catch(() => undefined)}>Send</button>
      <button disabled={!isRunning} onClick={() => void stop()}>Stop</button>
      {error ? <p role="alert">{error}</p> : null}
    </section>
  );
}

On mount the hook reads the whole event log from after (default 0) and reduces it to messages, so a reopened page shows the conversation as it stands, including turns that ran while the tab was closed. It then keeps polling from its cursor. A failed poll sets error, backs off, and resumes from the same cursor; nothing is replayed twice, and error clears when the log answers again. Changing sessionId replays the new session; a send still in flight for the previous session settles for its caller but never changes what the new session shows. after is a position, not a snapshot: the hook applies only events after it, so messages and running state from before that position are not reconstructed. Pass after to skip history you have already rendered from your own store, otherwise start at 0. Turns sent while one is running are queued by the platform. stop interrupts the running turn without spending a model turn.

What `send` returns

send(text) resolves once the platform has admitted the input as a turn, with a receipt { sessionId, turnId, status } where status is queued or running. The input appears in messages at that point; the log’s own record of it confirms that message rather than adding a second one. isRunning is true from admission until the log settles the turn, and a reply that arrives after the log has already shown the turn completed changes nothing. send rejects with a SendError when no turn was admitted, so a composer can keep the draft:

`code`	Cause	`status`
The platform’s error code, for example `session_ended`, `memory_admission_unconfirmed` or `insufficient_credits`	The request was answered with an error	The HTTP status
`network_error`	The request was not answered	none
`empty_input`	The text was blank; nothing was sent	none
`busy`	Create mode only: a turn is already running	none

The hook’s error is set to the same message either way. A turn that fails after admission is not a rejection: the receipt was returned, the failure arrives through the log as a turn.failed event and sets error. The hook never suspends, resumes or ends an attached session. Its lifecycle belongs to the server that created it.

Refresh notes on save

Every memory.saved event the session records (document memory) is appended to memorySaves and passed to onMemorySaved with its resource, documentId, revision and bytes. Re-read the document through your own owner route when one arrives. Saves are reported best-effort: a document can change without an event, so also refresh when the user opens the panel. Every event is available through onEvent, for example tool activity for an activity view; the types are listed on Session events.

Create a session from the browser

For a local application against Development, pass agent-id@alias and the first send creates the session through the development bridge:

import { useAgent } from "@opencomputer/react";

export default function Chat() {
  const { messages, send, sessionId, isRunning, error } = useAgent(
    "hello-world@development",
  );

  return (
    <main>
      {messages.map((message) => (
        <p key={message.id}>
          <strong>{message.role}:</strong> {message.text}
        </p>
      ))}
      <button
        disabled={isRunning}
        onClick={() => send("Hello").catch(() => undefined)}
      >
        Send
      </button>
      {sessionId ? <small>Session: {sessionId}</small> : null}
      {error ? <p role="alert">{error}</p> : null}
    </main>
  );
}

Each send resumes the session, streams one turn and suspends it again; the promise settles when the turn ends, with the same receipt and rejections as in attach mode. Sessions created this way have no memory bindings. Run the watched agent deployment and the web application separately:

npm run deploy -- --watch
npm run dev:web

The first command deploys agent changes and provides the authenticated development bridge at the hook’s default basePath. The second starts only the web application. Credentials are not bundled into browser code.

Hook result

Value	Purpose
`messages`	User and assistant messages, in log order
`send(text)`	Starts a turn; resolves with `{ sessionId, turnId, status }` or rejects with a `SendError`. In create mode the first call creates the session
`stop()`	Interrupts the running turn
`sessionId`	The attached session, or the created one after the first send
`isRunning`	A turn is admitted and not yet settled by the log
`isReplaying`	Attach mode: true until the existing history has been read
`error`	The most recent request or turn failure
`memorySaves`	`memory.saved` events seen so far
`cursor`	The last event position applied

Options

Option	Purpose
`sessionId`	Attach to this session
`agent`	Create mode: `agent-id@alias`
`basePath`	Route prefix for the three routes; default `/api/opencomputer/managed-agents`
`fetch`	A fetch implementation, for example one that adds a CSRF header
`after`	Attach mode: apply only events after this position; earlier history is not reconstructed
`pollIntervalMs`	Attach mode: interval between empty polls; default 1000, 500 while a turn runs
`onEvent`	Every applied event, including replayed history
`onMemorySaved`	Each `memory.saved` event
`source`	Create mode: the session’s input source

For the durable conversation model, see Sessions and turns.

Getting started

Concepts

Agent API

Test and operate

Examples

Attach to a server-created session

1. Create the session on the server

2. Proxy three routes

3. Attach in the browser

What `send` returns

Refresh notes on save

Create a session from the browser

Hook result

Options

​Attach to a server-created session

​1. Create the session on the server

​2. Proxy three routes

​3. Attach in the browser

​What send returns

​Refresh notes on save

​Create a session from the browser

​Hook result

​Options

Attach to a server-created session

1. Create the session on the server

2. Proxy three routes

3. Attach in the browser

What `send` returns

Refresh notes on save

Create a session from the browser

Hook result

Options