Embed manually

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.

bun add @opengeni/sdk @opengeni/react

Keep all @opengeni packages on the same version.

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:

OPENGENI_API_KEY=ogk_...   # server only

Self-hosting? Also pass baseUrl to new Opengeni(...) below.

Add the backend route

// lib/opengeni.ts (server only)
import { Opengeni } from "@opengeni/sdk/chat";

export const og = new Opengeni({ apiKey: process.env.OPENGENI_API_KEY! });

// app/api/opengeni/[...path]/route.ts
import { createSessionProxyRoute } from "@opengeni/sdk/next";
import { og } from "@/lib/opengeni";

export const dynamic = "force-dynamic";
export const { GET, POST, PUT, PATCH, DELETE } = createSessionProxyRoute(og, {
  resolve: async (request) => {
    const me = await authenticate(request); // your existing session check
    if (!me) return new Response("Unauthorized", { status: 401 });
    return { user: me.id, tenant: me.orgId }; // or { user: me.id } | { user: me.id, workspaceId }
  },
  // A lighter reasoning effort replies faster; omit it for the deployment
  // default (often higher: deeper answers, slower replies).
  createSession: (input) => ({ reasoningEffort: "medium", ...input }),
});

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).

Render the conversation

"use client";
import { OpenGeniChat } from "@opengeni/react";
import "@opengeni/react/compiled.css";

export function Assistant() {
  return <OpenGeniChat baseUrl="/api/opengeni" />;
}

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.

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:

// app/api/opengeni/[...path]/route.ts
import { createSessionProxyRoute } from "@opengeni/sdk/next";
import { og } from "@/lib/opengeni";

export const dynamic = "force-dynamic";
export const { GET, POST, PUT, PATCH, DELETE } = createSessionProxyRoute(og, {
  resolve: async (request) => {
    const me = await authenticate(request); // your existing session check
    if (!me) return new Response("Unauthorized", { status: 401 });
    return { user: me.id, tenant: me.orgId };
  },
  createSession: (input) => ({
    ...input,
    agent: {
      identity: "You are Acme's support assistant.",
      capabilities: { from: "none", webSearch: true },
      renderer: "opengeni",
    },
    sandboxBackend: "none", // this agent uses API tools, without shell or compute tools
  }),
  toolServer: {
    url: "https://app.example.com/api/mcp", // your product's MCP endpoint
    approvals: { ask: ["update_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.

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.

Get started

Build

Concepts

Guides

Reference

Examples

Further reading

Choose what your agent can do

Next

Give the agent your data

Going to production

​Choose what your agent can do

​Next

Give the agent your data

Going to production

Choose what your agent can do

Next