opengeni-client Skill verbatim. To install it, see For AI agents. Agents can fetch this page as Markdown by appending .md to its URL, then write each section to the path in its heading, relative to a directory named opengeni-client.
SKILL.md
---
name: opengeni-client
audience: integration-agent
description: >-
Add Opengeni agents to a product: the packaged chat UI behind one server
route, workspaces per tenant or user, the product's own tools with per-user
auth and approvals, background agents, and verification. Use when integrating
Opengeni into a website, backend, or app. Not for changing Opengeni itself.
---
# 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](https://docs.opengeni.ai/guides/developer-plugin)
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](https://github.com/Cloudgeni-ai/opengeni/blob/main/docs/product-integration.md).
## Decide
1. Inspect the repository: framework, auth, how users and teams are modeled,
any existing chat UI, package manager, tests.
2. 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.)
3. 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](references/existing-chat-ui.md).
- A plain HTML/JS site, or a widget for anonymous visitors:
[Website widget](references/website-widget.md).
- A non-JavaScript backend: keep the React UI and implement the
[proxy contract](https://docs.opengeni.ai/integrate/proxy-from-any-backend).
- Scheduled work, or chats created by the server:
[Background agents](references/background-agents.md).
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](references/versions-and-upgrades.md)).
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):
```ts
// 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:
```tsx
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`.
```tsx
<OpenGeniChat
baseUrl="/api/opengeni"
headers={() => ({ Authorization: `Bearer ${getAccessToken()}` })}
/>
```
`fetch` replaces the request function when the token must be awaited.
### Who sees what
| `resolve` returns | Workspace |
| ----------------------- | -------------- |
| `{ user, tenant }` | one per tenant |
| `{ user }` | one per user |
| `{ user, workspaceId }` | yours |
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. Files attached
in a private chat are the uploader's own (Only me), read by them and that chat's
agent; in shared chats they are workspace files. 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 })`.
Workspaces the product's organization key creates are managed by the product.
Organization owners and admins read those users' sessions, cost and an audit
log in Opengeni Console (console.opengeni.ai, or `/console` in the app), where
they also manage members, billing and API keys without opening the app; the
organization chooses full transcripts, metadata only or off. See
[opengeni-console.md](https://github.com/Cloudgeni-ai/opengeni/blob/main/docs/opengeni-console.md).
### 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](references/configure-the-agent.md).
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. The stock UI shows end users a model picker only when the handler sets
`modelSelection: true`; the component's `modelPicker` prop overrides this
either way. The picker lists the workspace's model catalog, so the workspace's
allowed-model settings decide which models appear. The option itself defaults
to `true`, so the relay accepts model choices a custom browser client sends;
set `modelSelection: false` to remove them.
### The product's tools
Expose the product's data as an MCP endpoint that acts as the signed-in user:
```ts
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](references/tools-and-auth.md).
`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.
4. A question that needs a product tool calls it with the right user's data; a
write asks for approval first.
5. 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](references/tools-and-auth.md#local-development), 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](references/production-checklist.md).
## 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](references/versions-and-upgrades.md)). 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](references/production-checklist.md#explicit-provisioning).
agents/openai.yaml
interface:
display_name: "Opengeni Client"
short_description: "Developer guide for adding Opengeni agents to a product; not runtime instructions."
default_prompt: "Add Opengeni agents to my product: OpenGeniChat behind one createSessionProxyHandler route, with the API key kept on the server, workspaces per tenant, and the product's own tools acting as the signed-in user."
references/background-agents.md
# Background agents
Server-side work uses the same workspaces the proxy creates. Translate the
product's ids first:
```ts
const workspaceId = await og.workspaceId({ tenant: team.id }); // or { user: user.id }
```
Ask the user for schedule details (day, time, time zone, where results go)
only when the requested feature is itself scheduled, and say why.
## A chat started by the server
Create the session as the user, with a stable idempotency key, so it appears in
their chat list. Opengeni adds the user to the workspace if needed:
```ts
const session = await og.client
.asUser(user.id, { source: og.source })
.createSession(workspaceId, {
initialMessage: `Summarize ticket ${ticket.id}.`,
idempotencyKey: `ticket-summary:${ticket.id}`,
agent: { identity, capabilities: "none" },
sandboxBackend: "none",
});
```
Render it with `SessionConversation`; see [Existing chat UI](existing-chat-ui.md).
For a text reply without UI (a bot, an email), the chat facade is shorter:
```ts
const chat = await og.chat({ tenant: team.id, user: user.id, conversation: `ticket:${ticket.id}` });
const reply = await chat.send("Summarize this ticket.");
```
## Schedules
```ts
await og.client.createScheduledTask(workspaceId, {
name: "Morning digest",
schedule: { type: "calendar", hour: 8, minute: 0, timeZone: "Europe/Oslo" },
agentConfig: {
prompt: "Summarize yesterday's new tickets and flag anything urgent.",
agent: { capabilities: { from: "none", knowledge: true } },
tools: [{ kind: "mcp", id: serverId }],
},
});
```
No user is present to refresh a per-user token, so scheduled agents reach the
product through a workspace OpenAPI Integration or MCP connection selected by
id in `tools`; see [Tools and auth](tools-and-auth.md#openapi-integrations).
Writes need `autoApprovedTools`, since nobody is there to approve them. Results
go back through the product's own tools.
## Jobs with no user
Attribute automation to a named service instead of inventing a user:
```ts
await og.client.asService("acme:reports", { jobId: job.id }).createSession(workspaceId, {
initialMessage: "Summarize the latest report changes.",
idempotencyKey: `reports:${job.id}`,
tools: [{ kind: "mcp", id: serverId }],
});
```
`asService` records who started the work; it grants no extra permissions.
## Knowing when work finishes
Subscribe a signed webhook to `turn.completed`, `turn.failed`,
`session.requiresAction`, or `session.humanInput.requested`. One organization
webhook covers every tenant workspace:
```ts
import {
createOrganizationWebhook,
verifyWebhookEvent,
} from "@opengeni/sdk/workspace-integrations";
const organizationId = await og.resolveOrganizationId(); // read from the API key
const { secret } = await createOrganizationWebhook(og.client, organizationId, {
url: "https://app.example.com/api/opengeni-events",
eventTypes: ["turn.completed", "session.requiresAction"],
workspaceFilter: null,
});
// In the receiver, with the exact raw body:
const { event } = await verifyWebhookEvent({ body, headers: request.headers, secret });
```
Store the secret once. Delivery is at least once and unordered: dedupe on
`event.id`, then read the session for current state. For one workspace,
`og.client.createWorkspaceWebhook(workspaceId, { url, eventTypes })` does the
same.
references/configure-the-agent.md
# Configure the agent
One `agent` object sets who the agent is and what it can do. The proxy's
`createSession` hook, `og.client.createSession`, scheduled tasks, and the chat
facade all accept it, and every session reports it back as `session.agent`.
<!-- doc-snippets: excerpt CreateSessionRequest from "@opengeni/sdk" -->
```ts
agent: {
identity: "You are Acme Analytics' assistant. You help customers read their dashboards.",
instructions: "Lead with the number, then one sentence of context.",
capabilities: { from: "none", webSearch: true, knowledge: true },
}
```
## Capabilities
Start from `"none"` (the session's own tools, asking the user, reading the
session's Skills) or `"all"` (everything the workspace offers; also what an
omitted `agent` gets), then switch single capabilities on or off. `"none"` adds
no Opengeni workspace tools, connectors, or bundled Opengeni guides, so it
needs no empty `tools`, `firstPartyMcpTools`, or `bundledSkillIds` lists.
| Capability | Lets the agent |
| --------------------- | ------------------------------------------------------- |
| `humanInput` | ask the user a question (on in `"none"`) |
| `notifications` | notify, call, and tidy the inbox of the user |
| `privacyFacts` | answer privacy questions from the deployment's facts |
| `skills` | `"read"` Skills (default in `"none"`), or `"manage"` |
| `webSearch` | search the web |
| `knowledge` | search and save workspace Knowledge |
| `artifacts` | publish files, documents, and Sites |
| `media` | generate images and video |
| `goals` | work toward a goal across many turns |
| `subagents` | start and follow other sessions |
| `schedules` | create scheduled tasks |
| `browser` | use a browser or desktop |
| `workspaceFiles` | read files uploaded to the workspace |
| `workspaceConnectors` | use the workspace's connected apps and integrations |
| `workspaceAdmin` | manage workspace settings, variables, and machines |
Tools you attach to the session (the proxy's `toolServer`, `mcpServers`,
integrations named in `tools`) stay available under `"none"`. Shell and file
tools come from the sandbox; `sandboxBackend: "none"` removes them.
A customer-facing assistant usually starts from `"none"` plus what it needs. An
internal operator agent usually starts from `"all"` minus what it must not do.
`"none"` pays only for what the session can use on every call. It gets a
neutral identity unless the session shares a workspace; `request_human_input`
offers the secret kind only with `secrets` and Skill reviews only with
`skills: "manage"`, and is left out when nobody can answer: pass
`unattended: true` for a session no person answers (or turn `humanInput` off);
`wait_for_input` comes only with a sandbox, `subagents`,
`goals`, `schedules`, `browser`, `media` or `workspaceAdmin` (a person needs no
wait: an answer resumes the turn), and Codemode guidance only with a sandbox or
`run_on`; tool search
only when a tool is deferred (list the product server with `eager: true`, not
`optional` and without a `connectionRef`, to avoid it); no Skill index without
Skills. Prompt sections follow their capability. Switch an item back on with
its capability, for example `{ from: "none", privacyFacts: true }`. Saved
workspace defaults and schedules keep notifications and privacy facts under
`"none"`. `getSessionModelContext` returns the latest request's provider body;
on the native Anthropic route it also lists the instructions and each tool.
## Identity, instructions, renderer
- `identity` replaces only Opengeni's introduction: name, product, voice.
- `instructions` add rules. They outrank Opengeni's default style, never its
safety rules.
- `renderer` defaults to `"opengeni"`, which suits `OpenGeniChat` and
`SessionConversation`; set `"markdown"` for your own UI, Slack, or email.
- Per-message facts go in `modelContext`, not in instructions.
## Other places to set it
```ts
// Defaults for new sessions in a workspace.
await og.client.updateWorkspaceSettings(workspaceId, {
sessionAgentDefaults: { capabilities: { from: "all", browser: false }, identity },
});
// A running session, from its next turn.
const session = await og.client.getSession(workspaceId, sessionId);
await og.client.updateSessionAgent(workspaceId, sessionId, {
agent: { capabilities: { from: "all", webSearch: false } },
expectedVersion: session.toolPolicyVersion, // 409 if it changed meanwhile
});
```
## Check the result
`session.agent` is the resolved configuration, including `unavailable`
capabilities. The packaged chat UI selects compact responses, which omit
instructions, Skill bodies and the full tool catalog. SDK defaults retain the
full response; custom chat clients can select `client.withSessionResponse("chat")`.
For an authorized settings or backend read, use
`const configuration = await og.client.getSessionConfiguration(workspaceId, sessionId)`.
This requires `sessions:control` and access to that session;
`configuration.effectiveTools?.tools` lists the tools, each with its `capability`.
Server-owned browser relays refuse this read; keep it on the backend.
Errors: 422 `agent_capability_unavailable`
(the deployment does not offer it), `agent_config_conflict` (contradictory
fields), and `agent_config_widening` (a child session asked for more than its
parent).
references/existing-chat-ui.md
# Existing chat UI and custom layouts
Use `OpenGeniChat` unless one of these applies. Styling alone is not a reason
to replace it: theme it with `--og-*` tokens, `theme`, and `labels`.
## An assistant bound to one record
For a ticket, document, or dashboard with its own conversation, create the
session on the server as the user (see
[Background agents](background-agents.md#a-chat-started-by-the-server)), keep
the session id on the record, and render only the conversation:
```tsx
import { SessionConversation } from "@opengeni/react/session-ui";
import "@opengeni/react/compiled.css";
<SessionConversation baseUrl="/api/opengeni" sessionId={ticket.openGeniSessionId} />;
```
Add `authorizeSession(sessionId, context)` to the proxy when the product must
check that this user may open this record's chat.
## A different layout in React
Compose the headless hooks from `@opengeni/react/session` (`useSession`,
`useSessionEvents`, `useTurnQueue`, `useSessionControl`,
`useHumanInputRequests`, `projectPendingApprovals`) with `MessageTimeline` from
`@opengeni/react/session-ui`, behind the same proxy. Wrap them in
`OpenGeniProvider` with `new OpenGeniClient({ baseUrl: "/api/opengeni" })` and
the `workspaceId` from that client's `getClientConfig()`, which the proxy
fills in for the signed-in user. They handle streaming,
reconnect, replay, queueing, approvals, and questions; do not rebuild those.
Wire Stop to `pauseSession`, which is resumable. `cancelSession` ends the
session for good.
## A chat UI that already speaks Vercel AI SDK or OpenAI
Keep it and point it at `createChatHandler` from `@opengeni/sdk/chat`:
```ts
import { Opengeni, createChatHandler } from "@opengeni/sdk/chat";
const og = new Opengeni({ apiKey: process.env.OPENGENI_API_KEY! });
export const handler = createChatHandler(og, {
resolve: async (request) => {
const user = await getSignedInUser(request);
if (!user) return new Response("Unauthorized", { status: 401 });
return { tenant: user.teamId, user: user.id, agent: { identity, capabilities: "none" } };
},
format: "vercel", // or "openai-chat", "openai-responses", "native"
});
```
Mount it for `GET` (history) and `POST` (messages), including the `/respond`
subpath, which answers approvals and questions. This is a text projection:
tool results, files, artifacts, and the queue do not reach the UI, and a
reopened chat restores only its text. Prefer `OpenGeniChat` when the product
can adopt it.
## A frontend that is not React
Keep the proxy on the server and build the UI natively. The
[Vue conversation recipe](https://github.com/Cloudgeni-ai/opengeni/blob/main/examples/vue-conversation/README.md)
is a runnable starting point.
references/production-checklist.md
# Production checklist
## Keys and configuration
- Use a long-lived organization API key from Organization settings > Developer,
stored in the product's secret manager. The signup setup key expires after
30 days.
- Set `OPENGENI_TOOL_SERVER_URL` to the production tool endpoint. The proxy and
`verifyToolRequest` must see the same URL and the same `OPENGENI_API_KEY`.
- Self-hosted: set `OPENGENI_API_BASE_URL` and pass it as `baseUrl`.
- Pin every `@opengeni/*` package to one exact stable version; see
[Versions and upgrades](versions-and-upgrades.md) for choosing and
upgrading it.
- Private chats need the organization's private-session setting. Organizations
created at signup have it on, so don't ask the user to check it. Without it
the SDK throws `OpenGeniSetupError`, whose message says who can enable it.
- 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.
## Tests to keep
- Every proxy and tool route rejects signed-out requests.
- Swapping in another user's or tenant's session id or record id fails.
- The tool endpoint rejects expired, forged, and wrong-audience tokens.
- Write tools ask for approval, or are deliberately auto-approved.
- No key or token appears in responses, logs, browser bundles, or prompts.
## Errors
SDK calls throw `OpenGeniApiError` with `status`, `code`, `retryable`, and
`outcomeUnknown`. Retry only when `retryable` is true. When `outcomeUnknown` is
true, the action may already have happened: read the current state before
trying again. Show users the product's own messages and keep raw errors in
server logs.
## Members and permissions
Opengeni adds a user to the workspace on their first request, with workspace
read, session create/read/control, file upload/read, and MCP attachment, and no
admin rights. The API key needs `members:manage` for this; full-access keys
have it. Change an existing member's permissions with
`og.client.updateExternalWorkspaceMember(organizationId, workspaceId, membershipId, { permissions, operationId })`
(`organizationId` from `await og.resolveOrganizationId()`). To remove a user,
stop resolving them; removing the membership alone does not stop them, because
their next request adds it again. `cancelExternalWorkspaceMemberGrant` also
stops their running turns.
## Explicit provisioning
Products that create workspaces ahead of time, or choose member permissions up
front, can call the lower-level API on `og.client`: `ensureWorkspace` (an
idempotent tenant-to-workspace mapping), `addExternalWorkspaceMember`, and
`asUser(userId, { source })` to act as a user. Return `{ user, workspaceId }`
from `resolve` to use those workspaces with the proxy. Adding a member
explicitly after their first request returns 409 when the permissions differ;
update the member instead.
## Usage and billing
Per-seat allowances, team budgets, and usage meters:
https://docs.opengeni.ai/guides/usage-allowances.
To stop one task and its child agents at an API-equivalent model-usage amount,
set `usageLimitMicros` from your server (the `createSession` hook or the server
SDK), never from the browser: https://docs.opengeni.ai/guides/task-usage-limits.
## Handoff
Tell the user what works, what you verified (including the isolation tests),
where the key lives, and what is left for them: the production key, deployment,
and any setting only an administrator can change.
references/tools-and-auth.md
# Tools and auth
Give the agent the product's data and actions through the product's own API,
not through prompts. Two ways:
| Need | Use | Credential |
| -------------------------------------------- | ------------------------------------------- | --------------------------------- |
| Chat tools that act as the signed-in user | MCP endpoint plus the proxy's `toolServer` | per-user token, minted by the proxy |
| Workspace-wide tools, or background agents | OpenAPI Integration, or a workspace MCP connection | one workspace Connection |
## Per-user MCP tools
```ts
createSessionProxyRoute(og, {
resolve,
createSession,
toolServer: {
// url defaults to OPENGENI_TOOL_SERVER_URL: public HTTPS, a tunnel when local
approvals: { ask: ["rename_post"] }, // every write tool; `true` for all tools
eager: ["search_posts"], // everyday tools on the first request; the rest stay searchable
},
});
```
The endpoint, with any MCP library (the official SDK needs zod 3.25 or later):
```ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
import { ToolRequestError, verifyToolRequest } from "@opengeni/sdk/tool-auth";
import { z } from "zod";
async function mcp(request: Request): Promise<Response> {
let user: string;
try {
({ user } = await verifyToolRequest(request));
} catch (error) {
if (error instanceof ToolRequestError) return error.toResponse(); // 401
throw error;
}
const server = new McpServer({ name: "acme", version: "1.0.0" });
server.registerTool(
"search_posts",
{ description: "Search the user's posts", inputSchema: { query: z.string() } },
async ({ query }) => ({
content: [{ type: "text", text: JSON.stringify(await db.posts.search(user, query)) }],
}),
);
const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
await server.connect(transport);
return await transport.handleRequest(request);
}
```
Mount it at the `OPENGENI_TOOL_SERVER_URL` path for every method (Next.js, in
that path's `route.ts`: `export { mcp as GET, mcp as POST }`, and keep `mcp`
itself unexported, because `next build` rejects any route export other than
HTTP methods and route config; Express: `toNodeMiddleware(mcp)`; Hono:
`toHonoHandler(mcp)`).
How it works: the proxy adds the endpoint to each chat it creates (tool names
appear to the model as `app__<tool>`; change the prefix with `toolServer.id`)
and refreshes the token on every message, approval, and answer. Tools act as
the user who started the chat, also in shared chats. The token is an HS256 JWT
signed with a key derived from `OPENGENI_API_KEY`, with `aud` set to the tool
URL, `sub` the user, and `tenant` and `workspace_id` claims.
`eager` lists the few tools nearly every chat needs (usually reads such as
search and get). The agent has them from its first request; every other tool
stays behind tool search. Keep the list short and stable: each listed schema
is sent on every request, and changing the list changes the cached prefix.
Authorize every call:
- Scope every query to the verified `user` and `tenant`. Treat ids the model
sends as lookup keys, and check they belong to that user.
- Re-check the user's current permissions before writes; the token proves who
the user is, not what they may do now.
- Accept this token only on the tool endpoint, and never accept the product's
login token there.
Shape tools around what users ask. "Show my open orders" needs a list tool,
or a search whose query is optional, with filters such as status. A search
that requires a text query leaves the model guessing at keywords and failing.
Tool endpoint in another language: run `await deriveToolTokenKey()` (from
`@opengeni/sdk/tool-auth`) once, store the hex key as its own secret, and verify
the JWT with any library: HS256, `iss` `"opengeni-session-proxy"`, `aud` the
exact tool URL, plus `exp`. Python:
`jwt.decode(token, bytes.fromhex(key), algorithms=["HS256"], issuer="opengeni-session-proxy", audience=url)`.
Your own tokens instead of `toolServer`: add the server in `createSession`
(`mcpServers: [{ id, url, headers: { Authorization: "Bearer …" } }]`, plus
`{ kind: "mcp", id }` in `tools` when you pass `tools`), and return
`{ mcpCredentialUpdates: [{ id, headers }] }` from `beforeForwardMessage` to
rotate it.
Let admins choose Allow, Ask first, or Block per tool. `approvals.ask` (or
`requireApproval`) is only the recommendation. Saved choices win, and
Opengeni enforces them; an Ask call waits for a person to approve it. Build
the settings screen on your server with the same server id and exact URL you
attach:
```ts
const server = { serverId: "app", url: process.env.OPENGENI_TOOL_SERVER_URL! };
const saved = await og.asUser(admin.id).getSessionMcpToolPermissions(workspaceId, server);
// saved.defaultPermission: "Allow all" and the like; saved.tools: per-tool choices.
await og.asUser(admin.id).updateSessionMcpToolPermissions(workspaceId, {
...server,
target: "tools", // or "default" for every tool without its own choice
toolNames: ["delete_post"],
permission: "block", // "allow" | "ask" | "block", or null to reset
expectedRevision: saved.revision,
});
```
Writes need `capabilities:manage`. Agents cannot change their own
permissions. A change applies from each chat's next run. Choices are keyed to
the exact URL string, so changing it (even a trailing slash or query) starts
from no saved choices; re-save them under the new URL when you move the server.
### Local development
Opengeni must reach the tool endpoint over public HTTPS. Never tunnel the whole
dev app (`cloudflared tunnel --url http://localhost:3000` publishes every page,
including sign-in and admin). If the tool endpoint is its own server, tunnel
only that port. Otherwise forward only the tool path, and tunnel that port:
```ts
// tool-tunnel.ts: `bun tool-tunnel.ts`, then `cloudflared tunnel --url http://localhost:3999`
const TOOL_PATH = "/api/opengeni/tools"; // the path of OPENGENI_TOOL_SERVER_URL
const APP = "http://localhost:3000"; // the local app
Bun.serve({
port: 3999,
fetch(request) {
const { pathname, search } = new URL(request.url);
if (pathname !== TOOL_PATH && !pathname.startsWith(`${TOOL_PATH}/`)) {
return new Response("Not found", { status: 404 });
}
const headers = new Headers(request.headers);
headers.delete("host");
headers.delete("accept-encoding");
return fetch(`${APP}${pathname}${search}`, {
method: request.method,
headers,
body: request.body,
redirect: "manual",
});
},
});
```
Set `OPENGENI_TOOL_SERVER_URL=https://<name>.trycloudflare.com/api/opengeni/tools`
(the tunnel URL plus `TOOL_PATH`). Any reverse proxy that forwards only that
path works.
## OpenAPI Integrations
For an existing HTTP API, publish an OpenAPI 3.x document with only the
operations the agent may use, then install it once per workspace:
1. Store the API credential as a workspace Connection, saying where it goes:
`credential: { headers: { Authorization: "Token …" } }`.
2. `og.client.previewApiIntegration(workspaceId, { source, connectionId })`
compiles the operations into tools and classifies reads and writes.
3. `og.client.installApiIntegration(workspaceId, …)` with the same `source`,
the preview's revision and digest (`expectedRevisionId`,
`expectedContentSha256`), and the tool ids you allow (`allowedTools`, from
`preview.tools[].id`). Writes ask for approval unless listed in
`autoApprovedTools`; list them only for unattended runs.
4. Select the returned server id in sessions or schedules:
`tools: [{ kind: "mcp", id: serverId }]`.
Every session in that workspace uses the same credential, so scope it to what
any member of the workspace may do. The API must be reachable from Opengeni
over public HTTPS.
## Direct current-human tools and Sites
Separate agent `toolServer` attachment above from current-human direct calls.
An authorized host's `client.tools.forWorkspace(id)` invokes known identities or
canonical symbolic paths without first loading the workspace catalog. Use
`$resolve({ identity })` plus `expectedDefinitionDigest` when code needs to pin
the complete public definition; use `$approveTarget` only after the host's human
approval UI. Never put these capabilities in iframe code. These endpoints do not
grant organization keys arbitrary human authority, and are not automatically
added to the session proxy's supported routes.
Modern `@opengeni/sdk/site` clients negotiate targeted calls. Upgraded hosts also
adapt old bundled Site clients through a bounded saved-version tool manifest;
local previews still use the frozen Codemode attempt. Use explicit
`toolGatewayMode: "catalog"` for older hosts/APIs, not speculative fallback.
Uncertain execution must be reconciled, never automatically replayed. See the SDK
README's Workspace tools section for approval and migration details.
## Credential handling
Never put tokens in prompts, Skills, `modelContext`, tool URLs, browser code,
or logs. Opengeni stores Connection and MCP header secrets encrypted and keeps
them out of the model's context.
### Your product as a vault provider
Use native vaults when the agent needs to discover and use stored credentials.
An embedding product can expose multiple remote vaults through a signed
`external` connection; an in-process host can keep using
`connectionCredentials.vaultProvider`. Keep the simple chat/tool integration
above unchanged unless the product actually needs this optional capability.
Configure remote connections on the server with `vaultsApi(client, workspaceId)`
from `@opengeni/sdk`: `installVaultProvider`, `getVaultProviderCatalog`,
`listProviderVaults`, and `linkProviderVault`. Never put provider tokens or the
signing secret in browser code, model context, or URL parameters. Verify each
request's raw-body signature and map its native account/workspace/subject to
the host's actual tenant/user before authorizing it. A shared connection must
not return a different user's inventory into the same metadata mirror; use
separate user-owned connections for user-specific stores.
Connection setup uses the existing `connections:write` and `secrets:write`
permissions and native owner checks, including authorized agent attempts for
shared connections. Personal setup requires the verified owner, and
organization setup requires its admin. List/read/write operations always use
the registered connection endpoint, not a per-call URL chosen by a tool caller.
`getVaultProviderCatalog` includes deployment availability even before anyone
connects; disable unavailable setup choices instead of collecting credentials
that this deployment cannot use. `listVaultProviderConnections` remains a
metadata-only convenience when only existing connections are needed.
For a remote host, use `createExternalVaultReceiver` from the server-only
`@opengeni/sdk/external-vault-receiver` subpath and a durable atomic replay and
mutation store. The in-memory store is only for local tests. Its
`resolveConnection` binds the native connection to one fixed host inventory;
`authorize` checks the mapped person on every operation. If the host must
register the native connection ID first, install returns saved/pending setup;
register that ID, then verify. Never accept all unknown connections into one
default tenant to avoid this registration step.
Provider capabilities are granular: do not assume every read-write vault can
update TOTP, upload files, restore history or archive items. Distinguish cached
metadata from live value reads. Incomplete discovery or an unavailable source
is not proof that the user has no matching secret. For a saved-but-pending
setup (`discoveryPending: true`), use `verifyVaultProviderConnection` with the
connection ID rather than resubmitting a consumed bootstrap token.
The native secret ask card still saves to hosted vaults only. If the host must
own collection, collect in the host UI and expose the saved item via its
provider. Keep short-lived per-attempt credentials on the existing renewable
credential callback: a stored item does not replace expiry/renewal, Git/MCP
transport bindings or cleanup. See the product's external-vault and credential
provider documentation before implementing either path.
references/versions-and-upgrades.md
# Versions and upgrades
## Pick a version
- Install the current stable release: `npm view @opengeni/sdk version` prints
the npm `latest` version. Pin `@opengeni/sdk`, `@opengeni/react` and any
other `@opengeni/*` package to that exact version (no `^` or `~` ranges).
- Do not use canary versions (`-canary.` in the version) in production.
- Source code, changelogs or docs can mention a newer version than npm
`latest`. That version is not published yet; use npm `latest`.
- If the repository enforces a minimum release age, pin an older shared
version or ask the user; do not bypass the policy.
## What stays compatible
Opengeni server updates do not break existing integrations. The routes,
fields, event types and documented behaviour that a published SDK uses keep
working, so a pinned version keeps working against app.opengeni.ai. Upgrade
for new features or fixes, not to stay compatible. Rare exceptions (an
emergency security fix or an explicit product-owner decision) are announced
with migration notes. Policy:
[api-compatibility-policy.md](https://github.com/Cloudgeni-ai/opengeni/blob/main/docs/design/api-compatibility-policy.md).
Write code that keeps it that way:
- Ignore unknown event types, enum values and response fields. Give every
`switch` over an Opengeni union a default branch.
- Branch on error codes and typed SDK errors, not on message text.
- Members marked `@deprecated` keep working. Use the replacement their docs
name in new code; existing calls need no urgent migration.
Self-hosted: run a server at least as new as the SDK. An older SDK works with
a newer server, but a newer SDK can call routes an older server does not have
yet. `/healthz` reports the server's `serverVersion`.
## Upgrade
1. Move every `@opengeni/*` package to the same new version in one change.
2. Read the `CHANGELOG.md` entries of `@opengeni/sdk` and `@opengeni/react`
between the two versions.
3. Run the typecheck and tests, then send a real chat turn through the proxy.
If something that worked stops working after an Opengeni server update, that
is an Opengeni bug. Report the SDK version, `serverVersion`, route and error;
do not work around it by calling the HTTP API directly.
references/website-widget.md
# Website widget
A chat bubble on a plain HTML/JS site (no React, no build step) whose visitors
are anonymous: a marketing site, docs, or a landing page.
## Server
Mount the text chat handler before any body parser:
```js
import { Opengeni, createChatHandler } from "@opengeni/sdk/chat";
import { toNodeMiddleware } from "@opengeni/sdk/express";
const og = new Opengeni({ apiKey: process.env.OPENGENI_API_KEY });
const chat = createChatHandler(og, {
format: "native",
resolve: (request) => {
const visitor = visitorIdFromCookie(request.headers.get("cookie"));
if (!visitor) return new Response("Unauthorized", { status: 401 });
if (request.method !== "GET" && !sameOrigin(request)) {
return new Response("Forbidden", { status: 403 });
}
return {
tenant: "website", // one workspace for every visitor
user: `visitor:${visitor}`, // each visitor sees only their own chat
conversation: `visitor:${visitor}`, // the chat's address in that workspace
agent: { identity: "You are Acme's website assistant. Brief and friendly.", capabilities: "none" },
instructions: "Answer only from these facts: … Reply in plain text, without Markdown.",
create: { sandboxBackend: "none", reasoningEffort: "low" },
};
},
});
app.use("/api/chat", ensureVisitorCookie, toNodeMiddleware(chat)); // before express.json()
```
- Always return a fixed `tenant` for anonymous visitors. `{ user }` alone gives
every visitor a workspace of their own, which fills the organization with one
workspace per browser.
- `conversation` addresses one chat inside the workspace, independent of the
user, so it must differ per visitor. A constant id makes the second visitor's
first message fail with `SESSION_CREATE_CONFLICT`.
- `ensureVisitorCookie` issues a random id (32 bytes, base64url) in an
`HttpOnly; SameSite=Lax; Path=/` cookie (`Secure` in production). Never take
the visitor id from the body, query, or a header the page sets.
- `sameOrigin` compares the request's `Origin` with the site's own origin.
- Put product facts (features, prices) in `instructions`, or give the agent a
read-only tool. Do not let the model guess them.
- Every visitor spends your organization's credits. Rate-limit `/api/chat` per
IP and set a member allowance
(https://docs.opengeni.ai/guides/usage-allowances) before going live.
## Browser
`GET /api/chat` returns `{ messages: [{ role, text }], pending, status }` to
restore the chat after a reload. `POST /api/chat` with `{ "message": "…" }`
streams SSE: `event: chunk` blocks whose JSON is `{ type: "text", text }`
(append), `{ type: "tool", … }`, `{ type: "pending", … }`, or
`{ type: "done", reply }`, and `event: error` on failure. With a bundler,
`parseChatChunkStream(response.body)` from `@opengeni/sdk/chat` reads it.
Without one, a small `fetch` reader that splits on blank lines is enough.
Replies are Markdown unless the instructions say otherwise. Either ask for plain
text (as above) or render Markdown with a sanitizer; never insert reply text as
raw HTML.
Verify: two browsers get separate chats, a reload restores the chat, a
cross-site `POST` is refused, the key is absent from everything under the
public directory, and the organization still has one website workspace.