@opengeni packages on the same version.
1
Get an API key
Sign up at app.opengeni.ai. In Organization settings → Developer → API keys, create a full-access key and put it in your server environment:Self-hosting? Also pass
baseUrl to new Opengeni(...) below.2
Add the backend route
resolve maps your signed-in user to Opengeni. Workspaces and memberships are created on first use, so there is no onboarding step. See Users & tenants for the three shapes.When the user sends their first message in a new chat, the proxy calls your backend’s createSession hook and creates the session as that user. The hook chooses the agent, tools, and model; see Choose what your agent can do below.Not on Next.js? Use the Express or Hono adapter, or createSessionProxyHandler from @opengeni/sdk/session-proxy (see Proxy from any backend).3
Render the conversation
OpenGeniChat shows the user’s chats and the open conversation. For one chat tied to a record, render <SessionConversation baseUrl="/api/opengeni" sessionId={id} />. The stylesheet is scoped and needs no Tailwind. See Conversation UI & theming.A backend on another origin
A same-origin backend route needs no CORS configuration. If your browser calls a different origin, use both SDK header lists in that backend’s CORS middleware:allowHeaders and exposeHeaders. Add any
headers your product sends itself. The packaged proxy and server-route adapters
already preserve and expose Opengeni’s response metadata; middleware outside them
must not replace that exposure list. Allowing request headers does not expose
response headers. Missing exposure breaks history paging and conversation filtering;
the SDK warns once per client when the required metadata is unreadable.
Session data and operator configuration
The packaged chat UI opts intoclient.withSessionResponse("chat"). Its SDK client sends
Accept: application/json; opengeni-session=chat; session reads, lists and
mutation responses then omit instructions, skills and effectiveTools. The
chat does not need these to render. An authorized settings
page or server-side SDK caller can explicitly use
client.getSessionConfiguration(workspaceId, sessionId) (GET .../sessions/{id}/configuration),
which returns the full session configuration and requires sessions:control plus
access to that session. There is no automatic full-configuration fallback.
The SDK default itself remains unchanged: new OpenGeniClient({ baseUrl }) returns
the full Session shape. For your own chat client, use
client.withSessionResponse("chat") to create a separate compact client without
changing existing readers. Its session methods return ChatSession, with optional
configuration fields for compatibility with older APIs.
With a server-owned createSession hook, the packaged relay also refuses browser
reads of configuration and model-context. Read operator configuration on your
backend instead. These are response projections only: the agent’s stored instructions,
skills and model input do not change. Upgrade the API as well as the SDK; older
APIs still return their historical full session payloads.
Previously shipped clients without this Accept preference keep the historical full response.
The packaged browser relay always adds the compact preference itself, even for older
browser clients. A custom relay must do the same; never pass a browser’s choice
through as a way to read the legacy configuration.
The existing Accept header works with older APIs’ CORS allowlists; they ignore
the new preference and continue to return the full response.
Choose what your agent can do
Embedded agents can use Opengeni’s built-in capabilities and your product’s own tools. Configure them on your backend; the conversation component stays the same. For example, replace the route above with this configuration to give a support agent web search and your product’s MCP tools, with approval required before updating a ticket:- Built-in capabilities:
agent.capabilitiesselects features such as web search, Knowledge, artifacts, and subagents.from: "none"starts with essentials such as asking questions and reading Skills; this example adds web search. Your attached product tools remain available. Usefrom: "all"to start with all capabilities, then turn individual ones off. See Configure the agent for the full list and how to update an existing session. - Your product’s tools:
toolServerattaches your MCP endpoint and supplies a signed user token. You implement the endpoint, verify the token, and authorize each action against your product’s data. See Give the agent your data for the matching server example, tool allowlists, per-session MCP servers, and OpenAPI integrations. - Approvals:
approvals.askrequests human approval for the named tools; the embedded conversation displays the approval. Tool selection and approval do not grant access to your data: your API still enforces the user’s permissions. See Approvals & questions for saved permission choices and approval behavior.
Next
Give the agent your data
Connect your API through MCP or OpenAPI, as the signed-in user.
Going to production
Key storage, costs, versions, and cleanup.