Skip to main content
Every session takes one agent object:
Use it when creating a session, in the proxy’s createSession hook, in the chat facade, on schedules, as the workspace default, and on a running session.

Capabilities

Start from "all" (the default) or "none" (the session’s own tools plus asking questions and reading Skills), then switch single capabilities:
Your own MCP servers and the integrations you name in tools stay available under "none". "none" adds no bundled Opengeni guides unless bundledSkillIds lists them, so it needs no empty tools, firstPartyMcpTools, or bundledSkillIds lists. Shell, file, and background-command tools come with the sandbox or a Connected Machine; sandboxBackend: "none" removes them. Requesting a capability the server doesn’t offer fails with agent_capability_unavailable.

What "none" sends on every call

Under "none" the agent pays only for what the session can use. Every model call carries the system prompt and the built-in tools, so each one is left out when its feature is absent:
  • Identity: a neutral introduction instead of the Opengeni workspace assistant, unless you set identity or the session shares a workspace (a sandbox, Knowledge, files, connectors, artifacts and similar).
  • request_human_input: only when someone can answer, and only the question kinds the session can use. A session your backend starts with no person behind it should pass unattended: true (see Nobody watching); it then gets no question tool, and humanInput: false removes it too. A session started over the API otherwise keeps it, since your backend can answer with submitHumanInputResponse, and a child session keeps it for its parent agent. The secret question appears only with secrets, Skill reviews only with skills: "manage", and the parent-agent guidance only in a child session.
  • wait_for_input: only when something can resume the agent: a sandbox or Connected Machine, subagents, goals, schedules, browser, media, or workspaceAdmin (a run_on command on another machine finishes later). A person needs no wait: an answer to request_human_input resumes the turn, and a new message starts one. The waiting guidance follows the tool, so the prompt is the same whether the API or a person started the turn.
  • Codemode guidance: only with a sandbox or Connected Machine to run it from, or run_on (workspaceAdmin).
  • Tool search (tool_search, tool_invoke, tool_list and their guidance): only when a tool is deferred, for example an MCP server that is not eager or a searchable Opengeni tool. List your product server with eager: true to keep every tool in the first request; an optional or connection-backed server is prepared in the background, so it keeps tool search. Without tool search, Opengeni titles the session itself.
  • Skill index: left out when the session has no Skills.
  • Prompt sections about web search and reporting web sources (webSearch or browser), answering in chat rather than in a document (artifacts), learning, monitoring, designing with workspace tools, and goal audits appear only with the capability they describe.
Switch any item back on with its capability, for example { from: "none", privacyFacts: true, notifications: true }, or schedules: true for waiting and monitoring. Sessions with a feature get the same prompt as before; outside child sessions, request_human_input no longer carries the parent-agent guidance. Saved workspace defaults and schedules that start from "none" keep notifications and privacy facts, as they did when saved. getSessionModelContext returns the latest request’s provider body on every route; on the native Anthropic route it also lists the instructions, their layers and each tool with its size, so you can see what each call costs.

Identity and instructions

  • identity is who the agent is: its name, your product, its domain and voice. Defaults to the workspace’s identity.
  • instructions are rules for this agent. They override Opengeni’s default working style, but not its safety rules.
Put facts about the current page in the message’s modelContext, not in instructions.

Title instructions

Opengeni titles each new chat automatically, in the language the person writes in. titleInstructions tells that title request how your product wants titles written. It is added after the request’s fixed rules, for example:
Use it for what the messages alone cannot tell the title request, such as the language to use when someone sends only a link, a file or code. It does not change the agent’s instructions. Child sessions inherit it, a running session can change it, and null removes it. Up to 8,000 characters. It is not part of the workspace default.

Renderer

  • "opengeni" for OpenGeniChat and SessionConversation: files, artifacts, and visuals render inline.
  • "markdown" for your own chat UI, Slack, or email. The chat facade uses it by default.

Where it goes

A change to a running session applies from its next turn. Sessions an agent creates inherit their parent’s settings and can only narrow them.

Check what the agent can do

effectiveTools.tools is a flat list; group it yourself as above. The configuration read requires sessions:control and access to that session; ordinary chat reads do not include the catalog. A missing effectiveTools or tenancy on an older session means unknown, not off. The Opengeni web app shows the same settings in the session’s Agent panel, and the prompt sent in Debug > Context.
Using a coding agent? The opengeni-client skill walks it through these choices and inspects your existing setup first.