cloudgeni-ai/opengeni/opengeni-client

Opengeni client

The product keeps its users, auth, and UI. Opengeni runs the agent: sessions, tools, approvals, and history. The browser talks only to the product's server, and the server talks to Opengeni with an organization API key that never leaves it.

No organization or key yet? Do Opengeni developer setup first, then come back.

Everything in this guide works on app.opengeni.ai today (the full embed: attachments, tool output, approvals). Older web pages or search results that say otherwise are outdated. The installed @opengeni/sdk and @opengeni/react types are authoritative. Without the repository, read https://docs.opengeni.ai/llms.txt. The tenancy model is specified in product-integration.md.

Decide

1. Inspect the repository: framework, auth, how users and teams are modeled,

any existing chat UI, package manager, tests.

1. Ask the user only what the request and repository leave open, in one short

message, with a recommendation:

• Is each chat private to the person who started it, or shared with their

team? (Recommend private.)

• May the agent change data, and which actions need approval? (Recommend:

approve every write.)

1. Pick the shape:

• React frontend: the default below.
• An existing chat UI to keep, an assistant bound to one record, or a

custom layout: Existing chat UI.

• A plain HTML/JS site, or a widget for anonymous visitors:

Website widget.

• A non-JavaScript backend: keep the React UI and implement the

proxy contract.

• Scheduled work, or chats created by the server:

Background agents.

Decide local mechanics yourself (ports, test users, tunnels). Do not push, merge, or deploy without the user's permission.

Default integration

Install @opengeni/sdk and @opengeni/react at the same exact version, the current npm latest (see Versions and upgrades). Put OPENGENI_API_KEY in the server's git-ignored env. Self-hosted deployments also pass baseUrl: process.env.OPENGENI_API_BASE_URL.

Server, one catch-all route at /api/opengeni/* (Next.js App Router shown):

// app/api/opengeni/[...path]/route.ts
import { Opengeni } from "@opengeni/sdk/chat";
import { createSessionProxyRoute } from "@opengeni/sdk/next";
const og = new Opengeni({ apiKey: process.env.OPENGENI_API_KEY! });
export const dynamic = "force-dynamic";
export const { GET, POST, PUT, PATCH, DELETE } = createSessionProxyRoute(og, {
  resolve: async (request) => {
    const user = await getSignedInUser(request); // the product's own auth
    if (!user) return new Response("Unauthorized", { status: 401 });
    return { user: user.id, tenant: user.teamId };
  },
  createSession: ({ initialMessage, idempotencyKey }) => ({
    initialMessage,
    idempotencyKey,
    agent: { identity: "You are Acme's assistant. Friendly and brief.", capabilities: "none" },
    sandboxBackend: "none", // chat and tools only; turns start in seconds
    reasoningEffort: "medium", // faster replies; omit for the deployment default (slower, deeper)
  }),
});

Other servers: build const handler = createSessionProxyHandler(og, options) from @opengeni/sdk/session-proxy with the same options, then mount toNodeMiddleware(handler) from @opengeni/sdk/express (before any body parser), toHonoHandler(handler) from @opengeni/sdk/hono, or call handler(request) on any web-standard server. Next.js Pages Router: in pages/api/opengeni/[...path].ts, export config = { api: { bodyParser: false, externalResolver: true } } and a default (req, res) => middleware(req, res) where middleware = toNodeMiddleware(handler); resolve reads the product session from request.headers (the cookie), since next/headers is App Router only.

Browser:

import { OpenGeniChat } from "@opengeni/react/session-ui";
import "@opengeni/react/compiled.css";
<OpenGeniChat baseUrl="/api/opengeni" />;

OpenGeniChat is the user's chat list plus the conversation, with streaming, approvals, questions, and attachments. It needs no provider or workspace id: the proxy tells it which workspace the user is in. Importing from session-ui instead of the package root avoids pulling in optional heavy peers. Brand it with --og-* CSS tokens.

Bearer-token auth instead of cookies: pass the token on every request, and read it in resolve.

<OpenGeniChat
  baseUrl="/api/opengeni"
  headers={() => ({ Authorization: `Bearer ${getAccessToken()}` })}
/>

fetch replaces the request function when the token must be awaited.

Who sees what

Workspaces and memberships are created on first use (the key needs members:manage, which full-access keys have). To remove a user, stop resolving them. Chats are private to the user who started them; chats: "shared" on the handler shares them with the workspace. A tenant is the product's team, organization, or customer: the group that shares data and tools. Derive user and tenant from the product's session, never from the request body or path. Anonymous visitors on a public site share one fixed tenant; { user } alone would give every visitor a workspace of their own. Also return visitor: true for them: visitors get no file attachments unless the handler sets visitorUploads: true. Live voice is off in the stock chat unless the component turns it on (<OpenGeniChat conversationProps={{ realtimeVoice: true }} />). Server-side code gets the same workspace with og.workspaceId({ tenant }) or og.workspaceId({ user }).

The agent

The browser sends only the first message and its attached files (the proxy adds them to the chat); createSession decides the rest: agent.identity (who it is), agent.capabilities ("none" for product tools only, "all", or a mix), agent.instructions, inline product skills, and sandboxBackend. See Configure the agent. Per-message facts such as today's date or the current page go in beforeForwardMessage: () => ({ modelContext }), not in instructions.

Without reasoningEffort, chats use the deployment default, which can be high: deeper answers, slower replies. A lighter effort ("medium" or "low") suits quick end-user chat; keep the default where answer quality matters more than speed. End users do not choose models unless the handler sets modelSelection: true; the picker then lists the workspace's model catalog, so the workspace's allowed-model settings decide which models appear.

The product's tools

Expose the product's data as an MCP endpoint that acts as the signed-in user:

createSessionProxyRoute(og, {
  resolve,
  createSession,
  toolServer: { approvals: { ask: ["update_ticket"] } }, // every write tool
});

The proxy attaches the endpoint at OPENGENI_TOOL_SERVER_URL (public HTTPS) to each chat with a short-lived per-user token. The endpoint calls verifyToolRequest(request) from @opengeni/sdk/tool-auth and scopes every query to the returned user and tenant. The user approves each call to a tool in approvals.ask. See Tools and auth.

toolServer throws at startup when OPENGENI_TOOL_SERVER_URL is not an https:// URL. Until the tunnel or deployment exists, pass it only when that variable is set, so chat still works without the product's tools: ...(process.env.OPENGENI_TOOL_SERVER_URL ? { toolServer } : {}).

Verify

1. The product's typecheck, build, and tests pass.
2. Signed out, /api/opengeni/... returns 401.
3. Signed in, a real product question streams a useful answer, and the chat is

still there after reload.

1. A question that needs a product tool calls it with the right user's data; a

write asks for approval first.

1. A second user, and a user in another tenant, cannot see the first user's

chats or data.

To see which models a workspace can use, call GET /v1/config/client?workspaceId=<id> with the key. Without workspaceId, an organization key sees no models and an "unavailable" fallback; that is expected, not a blocked model. A real chat turn is the true test.

Locally, Opengeni must reach the tool endpoint over public HTTPS. Never tunnel the whole app (that publishes every page, including sign-in and admin): run the tool-only forwarder from Tools and auth, tunnel only its port, set OPENGENI_TOOL_SERVER_URL to the tunnel URL plus the tool path, and tell the user.

Before production, and for the handoff, read the Production checklist.

Rules

• The API key is used only by the server (the proxy); it never goes in browser

code.

• Never replace the proxy with a raw passthrough to the Opengeni API.
• Keep every @opengeni/* package at one pinned version. Server updates keep

that version working; upgrade all packages together when you want new features (Versions and upgrades). The SDK is ESM-only; from CommonJS, use await import("@opengeni/sdk").

• With cookie auth, pass the product's existing CSRF check as

authorizeMutation. If it has none, keep the default (it refuses cross-site mutations by Sec-Fetch-Site); a hand-written Origin/Host check breaks behind proxies, tunnels, and preview URLs.

• This skill guides the coding agent. Do not add it to the product agent's

skills.

Advanced

Products that provision workspaces and members themselves can still use ensureWorkspace, addExternalWorkspaceMember, and asUser; see the Production checklist.