> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opengeni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK

> Choose the backend chat handler or the full TypeScript session client and React surfaces.

<Note>
  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.
</Note>

## 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](/guides/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](/guides/integrate-your-product#connect-your-backend) before using the backend chat handler. It has no dedicated React frontend.

```ts theme={null}
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](/guides/integrate-your-product#mount-the-handler) 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.

```bash theme={null}
bun add @opengeni/sdk
```

```ts theme={null}
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](https://github.com/Cloudgeni-ai/opengeni/blob/main/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](/reference/authentication#organization-key-access) 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](https://github.com/Cloudgeni-ai/opengeni/blob/main/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](/guides/integrate-your-product#render-the-chat).

## 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](https://github.com/Cloudgeni-ai/opengeni/blob/main/docs/architecture.md#310-clientserver-compatibility-policy).