Serverless Agents client

@opencomputer/sdk/agents is the TypeScript client for the management API: create sessions, send turns, read the event log, list and label sessions, and manage a project’s memory, webhooks, event subscriptions and GitHub repositories. Use it in your application’s server; use @opencomputer/react in the browser and @opencomputer/agent to define agent behavior.

The client uses web-standard APIs and runs on Cloudflare Workers without Node compatibility, Vercel functions, Deno and Node. It is the package’s only entry point: SDK 3.0 removed the sandbox client from the package root, @opencomputer/sdk.

npm install @opencomputer/sdk

import { OpenComputer, OpenComputerError } from "@opencomputer/sdk/agents";

const oc = new OpenComputer({ apiKey: process.env.OPENCOMPUTER_API_KEY! });

Use it from trusted server code. The key belongs to an organization and reaches every project, agent and session in it; it must not reach a browser. Authenticate your users and check their access before forwarding requests.

new OpenComputer(options)Copy Anchor Link

Methods accept an AbortSignal in their options; startOnDocument takes signal in its params. Return shapes are listed below. Paged session lists return { sessions, nextCursor }; repository lists return { repositories, nextCursor }. Event reads return an array.

ErrorsCopy Anchor Link

HTTP failures throw OpenComputerError with code, status and message. code is the API’s stable code when the body carried one (idempotency_conflict, session_ended, insufficient_credits, session_publication_unconfirmed); when the body had only text, it is derived from the status: unauthorized, forbidden, not_found, conflict, rate_limited, unavailable for 5xx, request_failed otherwise. A 429 also carries retryAfter in seconds, and an error the API tied to a session carries sessionId.

Network failures, response-body read failures and cancellation propagate the underlying error, such as TypeError or AbortError. They do not prove that a write was rejected. A request can commit before its response is lost.

The client does not retry automatically. Keep the same parameters and key for a submission’s retries; use a new key only for new work. Use bounded backoff and an AbortSignal, and retain the submission if the retry budget expires. Aborting the HTTP request does not cancel admitted work.

A successful create or label update confirms publication to the list. See the Management API for each operation’s errors and guarantees.

The client does not follow redirects. The API key is sent to baseUrl and to no other origin: a redirect answer fails the call with code redirected and the redirect’s status, and nothing is sent to the address it named. Check baseUrl when you see it.

Two codes come from the client rather than the API:

ValidationCopy Anchor Link

The client checks response envelopes and selected fields before returning; unknown fields pass through. Application-owned values such as session.result.data and turn payloads still need your application schema.

Event reads check seq, type and that data is an object. They do not validate each known event type’s payload; identity and timestamp fields are checked only when present. The exported event types describe the API contract, not complete runtime validation. Validate event data before using it where its contents affect application correctness or access.

SessionsCopy Anchor Link

create takes agentId, deploymentId, environment, memory, source, labels and externalReference as documented. turns.send takes input, idempotencyKey, mode, payload and answers, the id of the open question the input answers; both create and turns.send send the key as the Idempotency-Key header. The receipt carries the turn’s persisted status: queued or running for a new turn, and for a repeated key the existing turn’s status, completed, failed or cancelled once it has settled, with duplicate: true. The client maps nothing, so a retry after a lost reply learns what became of the turn. An input sent while a question is open, without answers, runs no turn: its receipt is { status: "held", questionId, duplicate } with no turnId ("discarded" once a stop ended the question). list takes the exact filters of GET /sessions: project or projectId, environment, agent or agentId, status, deploymentId, externalReference, createdAfter, createdBefore, updatedAfter, labels (up to three, sent as label.<key>=<value>), plus cursor and limit (1 to 100, default 50). iterate takes the same query and requests the next page whenever the previous one is consumed, stopping when nextCursor is null; it reads live rows, so a session created while you iterate may or may not be seen.

const recovered = await oc.sessions.list({ externalReference: orderId });
for await (const row of oc.sessions.iterate({ status: "suspended", limit: 100 })) {
  console.log(row.id, row.externalReference);
}

Create and submitCopy Anchor Link

Create the session, then send its first turn. Address the agent by its environment alias and retain both keys and the inputs. Retrying either call then returns the same session or turn, even if the agent is redeployed between attempts: the platform records the deployment the session started on. Pinning a deploymentId is an advanced option, not part of this flow.

const { session } = await oc.sessions.create(
  { agentId: "<agent-id>@development", labels: { request: taskId } },
  { idempotencyKey: taskId },
);
const receipt = await oc.sessions.turns.send(session.id, {
  input: text,
  idempotencyKey: `${taskId}/start`,
  payload: { repo, ref },
});

Send follow-ups to the same session with a fresh key per submission. To display work in a browser, attach the React hook through your authenticated application routes.

Read progress and resultsCopy Anchor Link

Read events from sequence 0, then request only events after the last sequence processed:

const events = await oc.sessions.events.list(session.id, { after: 0 });
const cursor = events.at(-1)?.seq ?? 0;
const next = await oc.sessions.events.list(session.id, { after: cursor });

Each read returns up to 500 events. Continue immediately while catching up; when a read is empty, wait before polling again. A cursor skips earlier events; it does not reconstruct state you have discarded. See Session events for payloads and replay.

sessions.get(id) returns the latest typed result, if the agent has reported one. Results retain their turn provenance and can outlive later work; see Sessions before treating a result as ready for review.

Start a session on a memory documentCopy Anchor Link

sessions.startOnDocument creates a memory document if it does not exist, then a session bound to it, and reports both ids and whether each already existed. These are two requests, not an atomic operation: the document remains if session creation fails. Retries reuse the document and converge on the session while the agent, environment and bindings remain unchanged.

const { document, session } = await oc.sessions.startOnDocument({
  projectId: "<project-id>",
  environment: "development",
  agent: "<agent-id>",
  resource: "notes",
  documentId: "workshop",
  document: { title: "Workshop notes" },
  idempotencyKey: "topic/workshop/1",
});

The steps, in order:

1. PUT /projects/<projectId>/memory/<resource>/documents/<documentId> with If-None-Match: * and the document body. 201 means the document was created. 412 means it exists; the call reads it with GET and leaves its content as it is. A 404 on that read means the ID was deleted and is reserved, which fails with code memory_document_deleted, since a binding to it would fail admission.
2. POST /sessions with agentId: "<agent>@<environment>", source, and memory set to your further bindings plus { [resource]: { scope: "document", id: documentId, access } }. The Idempotency-Key header is sessionIdempotencyKey(idempotencyKey), the SHA-256 hex digest of opencomputer.memory.session, a NUL byte and your key. 201 created the session; 200 means the key had already created it. Anything else under that key fails with code idempotency_key_reused; the document was left as it is.

The result:

The helper addresses the environment’s agent alias on every call; the platform records the deployment the session started on, so a retry after a redeploy returns the same session. A new key would create another session; it does not recover a lost response.

startSessionOnDocument({ apiKey, baseUrl?, fetch?, ...params }), exported from the same subpath, is the standalone form of the call for code that holds a key and no client, and sessionIdempotencyKey(key) derives the session-create key.

ProjectsCopy Anchor Link

MemoryCopy Anchor Link

Every call takes { environment } last; conditional writes also take the revision the write is conditional on, sent as If-Match.

Bodies, the document object and the error codes are on Document memory.

WebhooksCopy Anchor Link

create and rotateToken return the webhook with its token and full invocationUrl once; see Agent webhooks.

Event subscriptionsCopy Anchor Link

The shapes are on Event subscriptions.

GitHub repositoriesCopy Anchor Link

projects.github.repositories(p, { environment, cursor?, limit? }) calls GET /projects/<p>/github/repositories and returns { repositories, nextCursor }, each repository { id, fullName, private, defaultBranch, archived } as the environment’s GitHub installation covers them.

Agents and deploymentsCopy Anchor Link

TypesCopy Anchor Link

The subpath exports the types of every object above: Session, SessionSummary, SessionCreated, Turn, TurnReceipt, SessionEvent, Project, AgentSummary, Deployment, Webhook, Repository, the Create…Params and List…Query shapes, and DataValue for JSON payloads and results. The memory types (MemoryDocument, MemoryBindings, SessionMemoryBinding, MemoryResourceInventory, the document bodies, MemorySavedEvent, MemoryErrorCode) and the event subscription types (EventSubscription, CreateEventSubscriptionBody, OutcomeEvent, EventInput, TurnOutcomeDelivery, EventSubscriptionErrorCode) are exported from the same place.