SDK

The SDK surface is changing quickly. This page describes the shape; the package READMEs in the repository are the authority for exact method signatures and the current version.

Choose an entry point

Import	Use it for
`@opengeni/sdk/chat`	Server-side chat, tenant mapping, conversation identity, and a host HTTP handler
`@opengeni/sdk`	The full session, workspace, file, tool, and event API

For a product adding chat, start with Integrate your product. Keep the organization API key on your backend.

Chat API

Use the repository workspace packages and a compatible server deployment for these examples. Follow the source quickstart and deployment setup before using the backend chat handler. It has no dedicated React frontend.

import { OpenGeni } from "@opengeni/sdk/chat";

const og = new OpenGeni({
  baseUrl: process.env.OPENGENI_API_BASE_URL!,
  apiKey: process.env.OPENGENI_API_KEY!,
  organizationId: process.env.OPENGENI_ORGANIZATION_ID!,
  source: "acme-product",
});

const chat = await og.chat({
  tenant: "acme",
  user: "u_42",
  conversation: "c_9",
  agentAccess: "session",
  memory: "user",
});
const reply = await chat.send("What did we decide last time?");
console.log(reply.text);

In an authenticated product, resolve tenant and user on your server. The session is created on first send, and the same product, tenant, user, and conversation IDs reopen it. agentAccess defaults to "session"; memory defaults to the same scope and accepts false to disable Memory tools. Both settings apply at creation, not when reopening an existing session.

API	Purpose
`chat.send(message)`	Aggregate a reply with `text`, `status`, and any pending decision
`chat.stream(message)`	Iterate text, tool activity, pending decisions, and the final reply
`chat.snapshot()`	Restore messages, unresolved decisions, and session status
`chat.respond(input)`	Continue after a human approves/rejects a tool or answers/skips a question
`createChatHandler(og, { resolve, format })`	Serve your authenticated chat, history, and decision routes
`og.client`	Use the full SDK on the same session

A reply can be completed, pending, or cancelled. Present pending requests to the user before calling respond; a text reply alone does not imply that the turn completed. The handler supports native, Vercel UI message stream, OpenAI Chat Completions, and OpenAI Responses text-chat formats. Its history and decision endpoints remain native. See the handler setup and protocol choices for route registration and history ownership.

Full TypeScript client

A framework-agnostic TypeScript client with zero runtime dependencies. It needs only WHATWG fetch and streams, so it runs in Node 18+, Bun, Deno, browsers, and edge runtimes.

bun add @opengeni/sdk

import { OpenGeniClient } from "@opengeni/sdk";

const client = new OpenGeniClient({
  baseUrl: "https://your-deployment.example.com",
  apiKey: process.env.OPENGENI_API_KEY!,
});

const workspaceId = process.env.OPENGENI_WORKSPACE_ID!;
const session = await client.createSession(workspaceId, {
  initialMessage: "Investigate the failing deploy on staging",
  resources: [{ kind: "repository", uri: "https://github.com/acme/app.git", ref: "main" }],
});

for await (const event of client.streamEvents(workspaceId, session.id)) {
  if (event.type === "agent.message.delta") {
    process.stdout.write((event.payload as { text: string }).text);
  }
}

What it covers:

Area	Highlights
Organizations and workspaces	Full/read-only organization API keys, idempotent `ensureWorkspace`, workspace settings
Organization sessions	Paginated `listOrganizationSessions` and `iterateOrganizationSessions` across shared workspaces
Sessions	Create with resources, files, Skills, tools, a goal, and a compute target; list, get, archive, cancel
Input and control	Send, Steer, queue management, Pause and Resume, approval decisions, human-input answers
Events	Replay by sequence, bounded event pages, and a streaming iterator with reconnect, resume, gap backfill, and duplicate suppression
Files	Upload, attach, and download workspace files
Goals	Read, pause, resume, and clear a session goal
Connected Machines	Enrollment tokens, device-flow approval, machine discovery and metrics, active-target swap
Proxy helpers	Re-emit a session stream from your own server with an identical wire format

Full reference: packages/sdk/README.md. Organization session listings exclude Personal workspaces and Only me sessions. Each row includes its workspaceId for subsequent session, event, and file reads. Use nextCursor to determine whether another page exists, even when a page is shorter than the requested limit. Read-only organization keys support this reporting path but cannot create chats or send messages.

@opengeni/react

Hooks and styled components built on the SDK: live session streaming, a composer, a timeline that renders streaming deltas, tool calls, approvals, and child-session status, session status badges, and workspace fleet tiles. Every visual decision routes through --og-* CSS variables, so a host rebrands by overriding tokens. Dark mode is the default; light is opt-in. Subpaths keep the root import lean:

Import	Contents
`@opengeni/react`	Timeline, composer, hooks, and the sandbox workbench
`@opengeni/react/composer`	Advanced composer composition
`@opengeni/react/machines`	Connected Machines dashboard and enrollment flow
`@opengeni/react/realtime`	Voice controls, lazily loadable

Full reference: packages/react/README.md. Use SessionConversation with the normal SDK for an existing session, or compose the timeline and composer. These components do not consume the backend chat-handler protocol. Import @opengeni/react/compiled.css for the supplied styles. See the React integration guide.

Compatibility

Published clients and server builds are compatible within the same major version. Within a major, evolution is additive and both sides are tolerant readers: servers ignore unknown request parameters, clients ignore unknown response fields and event types, and removing or retyping a field requires a major release. Servers expose their version through the health and client-config responses. See the compatibility policy.

Get started

Concepts

Guides

Reference

Choose an entry point

Chat API

Full TypeScript client

@opengeni/react

Compatibility

​Choose an entry point

​Chat API

​Full TypeScript client

​@opengeni/react

​Compatibility

Choose an entry point

Chat API

Full TypeScript client

@opengeni/react

Compatibility