Agents

An Agent is a workspace worker that takes one goal and executes it as a durable, inspectable run. The Workspace Agent and every custom agent are pinned to an immutable version — instructions, model, tool policy — so a chat already in flight never changes underneath you.

The roster

oxygen agent list shows the built-ins, oxygen agent custom lists yours. oxygen agent enable <slug> and disable <slug> accept built-in slugs only; a custom agent is retired with oxygen agent delete <slug> (archive — versions and runs are preserved).

Tool authority is not spend authority

A published version grants standing tool authorization. It grants no money.

Tool access is set per version. On /agents/new and on the Settings tab, the Tool access picker offers four presets:

The CLI equivalent is --tool-policy-json on agent create / agent set, with --confirm-full-access for "mode":"full".

Spend is authorized separately, every time:

• A manual run requires an explicit ceiling. oxygen agent run makes both --max-credits and --approved required flags — there is no unbounded run, and no version setting removes them.
• A cron, event, or webhook trigger persists a per-delivery ceiling: oxygen agent trigger-create also requires --max-credits and --approved, and each firing is bounded by that number, not by the run before it.

Four things are enforced outside the model and cannot be prompted away: a platform deny list (agent self-management, credentials and secrets, billing, admin, support, Copilot, org selection, integration connect/disconnect, directory publishing); a scoped policy denying anything it does not explicitly match; full mode denying everything until standing authorization is recorded on the version; and a hard per-run plan ceiling that no version setting or --max-credits can exceed — 10,000 credits per run on Starter (5,000 of them inference), 25,000 (12,500) on Pro, 50,000 (25,000) on Team, 100,000 (50,000) on Scale. A paid tool call that arrives without its own credit cap is refused with agent_paid_capability_requires_max_credits.

Create one

Web: /agents → New agent → /agents/new. Fill Name, System prompt, Model (Oxygen Fast, Oxygen Balanced — the default — or Oxygen Max), and Tool access, then Create agent. The slug is generated from the name.

CLI — free, starts no run, spends nothing:

oxygen agent create lead-research \
  --name "Lead research agent" \
  --instructions "Research inbound signups and write a one-paragraph brief onto their CRM record." \
  --model-policy-json '{"level":"medium"}' \
  --tool-policy-json '{"mode":"scoped","rules":[{"decision":"allow","effect":"read"}]}'

Editing configuration publishes a new immutable version. On /agents/<slug>?tab=settings that is the Save settings button; from the terminal it is oxygen agent set <slug> --instructions "…". Chats already running stay pinned to the version they started on.

Run it

oxygen agent run is the paid entry point — it starts the run and its spend.

oxygen agent run lead-research \
  --goal "Brief the five newest inbound signups" \
  --max-credits 200 --approved

In the web app, the Chats tab on /agents/<slug> has Start a chat: a Prompt box, a Maximum credits input, and the Start chat button. Starting approves managed inference and permitted tool actions up to that ceiling — nothing above it.

oxygen agent runs lead-research --json          # newest first
oxygen agent run-get lead-research <run-id>     # append-only event ledger
oxygen agent cancel lead-research <run-id>

Each run has a transcript at /agents/<slug>/runs/<run-id>. When an ask rule pauses a tool call, decide it there with Approve and resume or Reject, or from the terminal:

oxygen agent approval-decide lead-research <run-id> <approval-id> --decision approved

Triggers, files, MCP

Triggers have no web screen. oxygen agent triggers workspace lists them; oxygen agent trigger-set workspace <trigger-id> --status paused stops deliveries without deleting one. A new trigger carries its standing per-delivery ceiling:

oxygen agent trigger-create workspace --type cron \
  --cron "0 9 * * 1" --timezone Europe/Berlin \
  --instruction "Summarize last week's replies" \
  --max-credits 100 --approved

Attach text context with oxygen agent file-create --name notes.md --text "…", list it with oxygen agent files, pass it to a run with --file-ids.

The agent MCP tools (oxygen_agent_run, oxygen_agent_approval_decide, and the rest) are not in the default set a fresh client sees. Reconnect with ?toolset=agents to load them; they are listed in the MCP reference. An agent can never manage or run agents through them: create, update, delete, enable, disable, run, cancel, approval-decide, and trigger create/set are all on the platform deny list.

Related

• Approvals — how a paused ask rule is decided.
• Runs — the durable record an agent run produces.
• Modes — the gate on the tools an agent calls.