Skip to main content
You add one backend route and one component. The browser talks to your backend; your backend holds the API key and tells Opengeni who the user is. Everything on this page works on app.opengeni.ai today, including attachments, tool output, and approvals.
Keep all @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.
Chats are private to each user by default. That needs private chats enabled for your organization; if they are off, the proxy returns an error that says who can turn them on.

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:
Use your framework’s equivalent of 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 into client.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.capabilities selects 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. Use from: "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: toolServer attaches 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.ask requests 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.
Without an explicit agent configuration, new sessions inherit the workspace and deployment defaults. Use the backend hook to choose the capabilities appropriate for your product.

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.
The Northstar support example runs this whole path with a product MCP server.