Skip to main content
A Console agent belongs to your organization. You set it up once (Instructions, model, built-ins, tool servers, which tools are on and which ask first) and every chat that names it runs it, in any workspace your organization manages. Settings are saved as numbered versions; one is published, and each chat stays on the version it started on until you publish with Move running chats. Console agents are turned on per organization. Ask Opengeni to enable them for yours.

Three ways to work

A code agent is read-only in Console (“Managed by code”). An organization owner can move it to Console; code deploys are then refused. Export as YAML in Console gives you a Console agent’s file to move it into Git.

Name the agent when a chat starts

A chat can change settings for itself. Extra instructions are added after the agent’s, never replacing them:
What a chat changed is shown in Console as Changed by this chat. Send agentOverrides: "reject" to refuse any change instead (422 agent_override_rejected). With the session proxy, name the agent in your createSession hook; an agent sent by the browser is dropped. Chats read back which agent and version they run in session.orgAgent.

Agent files

One file per agent, named after its key:
The first line gives editors that use the YAML language server completion and checks from the JSON Schema.

Runs on

The machine or Sandbox Environment must be your organization’s and available in the workspaces your product manages: turn on All product-managed workspaces in Available in. A deploy that names an unknown machine or environment fails with machine_not_found or environment_not_found; Personal (Only me) machines can’t be used. A chat can still pass sandboxBackend, targetSandboxId or rigId; that is recorded as a change by the chat. A Personal machine never runs these chats, whether a request, a default or a worker’s parent chat puts it there (personal_machine_not_allowed). A deployed version keeps the machine or environment by id, so renaming it or adding another with the same name doesn’t move the agent.

Deploy

Every file is checked first; nothing is deployed while one has a problem. Each agent prints one line: key, created, updated or unchanged, the version, whether it is published, and its config hash. Deploying unchanged files is a no-op. --dry-run writes nothing, says would create vN or unchanged for each agent and prints its diff against its published version; an instructions file that doesn’t exist is an error. Add --move-running-chats with --publish to move running chats to the new version too, and --json for machine-readable output. npx opengeni agents export <key> --out agents writes an existing agent’s file. From GitHub Actions:
From code, with the SDK:

End users’ own logins

For a tool server that uses each person’s own login, Opengeni asks, in order: your credential provider, then the login you stored for that end user, then the headers the chat itself sent. It never falls back to a shared key. Store a login from your backend:
Logins are encrypted, refreshed before they expire, and never readable back.