DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS
AI AGENTS·SUPERAGENT

Superagent

The Superagent is the workspace orchestrator. It's the bot that runs when you talk to Onnie AI, and it's the one that knows about every Onniebot in your workspace and can involve them in its work.

What the Superagent does

The Superagent is an engine_bots row with is_superagent = true and no tool restrictions. Unlike Onniebots, it receives a bot directory as part of its system prompt — a listing of all active Onniebots in the workspace, including each bot's id, name, and whether it accepts delegated work.

With that directory, the Superagent can:

  • Consult a Onniebot (consult_bot) — run a bounded sub-call to a named bot synchronously within the current turn and incorporate its response. The sub-call is capped at 5 iterations and 60 seconds.
  • Delegate a Task (create_task with assignee_bot_id) — create a Task assigned to a bot that accepts delegated work. The dispatch cron picks it up and runs the bot autonomously.
  • Manage Onniebots — create, update, or delete bots via create_bot, update_bot, delete_bot (admin or editor role required).
  • Update workspace context — write workspace or project onnie_md via set_workspace_md / set_project_md (admin or editor role required).

When the Superagent fires

The Superagent runs on every user-initiated chat turn where the chat's bot_id resolves to the Superagent row. This is the default for all new chats — when no bot is selected in the bot picker, the engine uses the workspace Superagent.

The Superagent also runs as the agent in Task dispatch: when Onnie AI delegates a Task to itself (rather than to a Onniebot), the cron-dispatched run uses the Superagent loop. In practice, Tasks assigned to bots run under that bot's loop; Tasks assigned to users are human-handled.

Routing rules

The Superagent does not follow a rigid routing table. Its routing behavior is driven by its onnie_md instructions (the default is empty — the workspace admin can customize it), the bot directory in its system prompt, and its general reasoning about which bot is best suited for a request.

At a high level:

  • If a user message mentions @BotName, the Superagent can look up that bot's id in its directory and call consult_bot with it.
  • If the request involves work that should be tracked asynchronously on the task board, the Superagent can create a Task with assignee_bot_id pointing to a bot that accepts delegated work.
  • If no Onniebot fits the request, or if the request is general-purpose, the Superagent handles it directly.

The Superagent matches requests to Onniebots based on their names, instructions, and whether they accept delegated work. To make routing more predictable, write clear onnie_md instructions for each Onniebot and (optionally) for the Superagent itself.

Observability

Each turn the Superagent runs produces an engine_executions row. You can see the execution status (running / completed / interrupted / failed) in the chat thread. The kind field on the execution is turn for user-initiated runs, consultation for consult_bot sub-calls, and task_run for cron-dispatched Task runs.

Granular events stream into engine_execution_events during a turn — tool calls, tool results, plan step updates, consultation start/end, tier upgrade suggestions. These are surfaced in the chat UI as narration text under the active bot message (the trace tail).

When the Superagent runs consult_bot, the child execution is recorded with parent_execution_id pointing to the parent turn. This lets you trace the full call chain: which turn triggered which consultation, which tool calls each step made.

Token and credit usage is recorded per iteration in engine_token_ledger, tagged by execution_id. The context stats popover in the composer toolbar shows a breakdown for the active execution.