Mobius

Sign inGet started
GuidesAPI Reference
Sign inGet started

Concepts

Agents

An agent is a named AI actor inside a project. It has instructions, a default model, optional toolkits and skills, optional table access, and optional managed environment access. You'll use agents in two shapes:

  • As steps inside an automation, where the runtime runs one bounded agentic turn and saves the result for later steps.
  • As a session for exploration, coaching, inbox work, or ad-hoc collaboration.

An agent is also a machine principal. The agent's principal_id is the durable identity that receives role assignments, appears in audit logs, owns its private tables and artifacts, and runs actions.

What to think about when you design one

Instructions (system_prompt). Treat this like a CLAUDE.md: the durable, project-specific behavior of this agent. Keep it terse. The prompt for any specific job lives on the step or session message, not here.

Default model. Pick the cheapest model that does the job well, then override on a per-step basis where reasoning quality matters more than cost. Steps can pin a different model than the agent's default.

Roles. Role assignments on the agent principal decide which Mobius resources it can read, which runs it can operate, and which actions it may invoke.

Toolkits. Toolkits are allowlists for action-catalog tools the agent can call during a turn. Smaller toolkits mean a smaller tool manifest and cheaper, clearer turns.

Skills. Skills are reusable instruction snippets with optional tool requirements. Think of them as project-approved chapters the agent can load into a turn.

Tables and environments. Grant table access when the agent needs structured memory. Attach a managed environment when the agent's work involves a filesystem, repository checkout, generated files, or a worker-backed model route.

Working with agents from the CLI

# Inventory
mobius agents list
mobius agents get agt_triager
 
# Sessions
mobius agents list-sessions agt_triager
mobius agents stream-session-events agt_triager ses_abc...
 
# Configuration
mobius agents replace-toolkits agt_triager --file toolkits.json
mobius agents replace-skills agt_triager --file skills.json
mobius agents provision-inbox agt_triager

Provisioning an inbox gives the agent an email address. Inbound mail to that address creates email.received source events and can also appear in agent session history.

Agents in automation steps

The common shape is a single agent step with a templated prompt:

- name: triage
  type: agent
  agent_id: agt_ticket_triager
  prompt: "Classify {{ .inputs.issue.title }} and recommend a label."
  save_as: triage_result

The step runs one bounded turn. The agent may call tools, and those tool calls land on the run event stream. The final result is saved under triage_result. Later steps can reference {{ .context.triage_result.label }}.

Sessions vs. runs

A session is open-ended chat. Use it for coaching the agent, debugging behavior, or asking it to do ad-hoc work. Sessions keep their own transcript and event stream; they do not advance automation runs.

Automation runs are structured executions. Use runs when the agent work should follow a versioned process, emit durable events, and hand results to later steps.