Configure the agent

Every session takes one agent object:

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 },
  renderer: "opengeni",
}

The same object works when you create a session, in the proxy’s createSession hook, in the chat facade, on schedules, as the workspace default, and for a running session. Every session reports what it resolved to.

Agent settings need the deployment switch OPENGENI_AGENT_CONFIG_ADMISSION_ENABLED. When it is off, getClientConfig() reports agentConfig.enabled: false and a request with agent is refused with agent_config_not_enabled. Use firstPartyMcpTools: [] and tools to narrow an agent until then.

Capabilities

Start from "all" (everything the workspace offers, which is what a session without agent gets) or "none" (the session’s own tools plus asking questions and reading Skills). Then switch single capabilities:

capabilities: "none"
capabilities: { from: "none", webSearch: true, knowledge: true }
capabilities: { from: "all", browser: false, workspaceAdmin: false }

Capability	Lets the agent	In `"none"`
`humanInput`	Pause and ask the person for a decision or missing detail	On
`webSearch`	Search the public web	Off
`media`	Generate images and videos	Off
`goals`	Work toward a goal across many turns	Off
`subagents`	Start, message, and follow other sessions; list models	Off
`skills`	`"read"` installed Skills, or `"manage"` them too	`"read"`
`artifacts`	Publish files, documents, and Sites people can open	Off
`browser`	Use a browser or desktop computer	Off
`schedules`	Create and manage scheduled tasks	Off
`knowledge`	Search and save workspace knowledge, task notes, and instructions	Off
`workspaceFiles`	Read files uploaded to the workspace	Off
`workspaceConnectors`	Use the workspace’s connected apps and integrations	Off
`workspaceAdmin`	Manage variable sets, projects, rigs, machines, and connector setup	Off

Some tools are never toggled:

Your own tools. MCP servers you attach to the session and integrations you name in tools stay available under "none".
Sandbox tools. The shell and file editing come with a sandbox. sandboxBackend: "none" removes them.
Runtime mechanics. Waiting for input, reading background commands, and titling the session.

A capability the server does not offer shows as off in agent.unavailable, and asking for it is refused with agent_capability_unavailable.

Identity and instructions

identity replaces how OpenGeni introduces the agent: its name, your product, its domain and voice. Leave it out to use the workspace’s identity, or OpenGeni’s.
instructions are the session’s instructions: rules for this agent.

The prompt order is identity, OpenGeni’s working style, your organization’s identity, workspace instructions, then session instructions. Instructions take priority over OpenGeni’s default working style (“answer in one sentence” wins), never over its safety rules or how it runs tools. Put facts about the current page in the message’s modelContext, not in instructions.

Renderer

"opengeni" for OpenGeniChat and SessionConversation: the agent can link files and artifacts and show visuals inline.
"markdown" for your own chat UI, Slack, or email: ordinary Markdown links only. The chat facade uses it by default.

Where it goes

createSession: async ({ initialMessage, idempotencyKey }, { user }) => ({
  initialMessage,
  idempotencyKey,
  agent: { identity, capabilities: "none" }, // only your tools plus the essentials
  mcpServers: [{ id: "acme", url: ACME_MCP_URL, headers: await userHeaders(user) }],
  tools: [{ kind: "mcp", id: "acme" }],
  sandboxBackend: "none",
}),

await og.updateWorkspaceSettings(workspaceId, {
  sessionAgentDefaults: {
    capabilities: { from: "all", browser: false, workspaceAdmin: false },
    identity: "You are Acme's operations agent.",
  },
});

await og.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: "acme" }],
  },
});

const session = await og.getSession(workspaceId, sessionId);
await og.updateSessionAgent(workspaceId, sessionId, {
  agent: { capabilities: { from: "all", webSearch: false } },
  expectedVersion: session.toolPolicyVersion, // 409 when someone changed it first
});

A change to a running session applies from its next turn. Sessions created by an agent inherit their parent’s settings and can only narrow them. A goal turns goals on.

Check what the agent can do

const session = await og.getSession(workspaceId, sessionId);
session.agent; // the resolved settings, or null for sessions created before them
session.effectiveTools; // every known tool, its capability, and whether it is sent up front

A connected app’s own tools are listed once a turn starts. The OpenGeni web app shows the same in the session’s Agent panel, and the exact instructions sent in Debug > Context.

Using a coding agent? The opengeni-client skill walks it through these choices and inspects your existing setup first.

Get started

Build

Concepts

Guides

Reference

Examples

Further reading

Configure the agent

Capabilities

Identity and instructions

Renderer

Where it goes

Check what the agent can do

​Capabilities

​Identity and instructions

​Renderer

​Where it goes

​Check what the agent can do

Capabilities

Identity and instructions

Renderer

Where it goes

Check what the agent can do