An agent is a named, observable identity backed by a service account. Workers register agents to claim jobs from Mobius and report connection state through sessions. Mobius derives an agent's presence from its most recent sessions rather than storing it directly.

The model

Each agent has:

• A service account that supplies authentication credentials. One service account can back multiple agents; each agent belongs to exactly one service account for its lifetime. A service account can read and update its own backing agent without the agent.read or agent.manage permission, enabling self-registration at worker startup.
• A name — project-scoped unique identifier used when targeting the agent for job assignment.
• A kind — freeform classification (e.g., llm, rpa) for tooling and filtering.
• Capabilities — an arbitrary map that orchestrators use to select suitable agents.
• Config — an opaque configuration blob stored on the agent and returned as-is.
• Status (active or inactive). Setting status to inactive stops new job claims but does not terminate active sessions.
• Presence (online, stale, or offline) — computed from the most recent 20 sessions across all transports, not stored on the agent record.

Sessions are the runtime connection records that live under an agent. A worker registers a session at startup, sends periodic heartbeats to maintain online presence, and disconnects on graceful shutdown.

Registering an agent and starting a session

# 1. Create the agent
curl -X POST "$MOBIUS_API/v1/projects/acme/agents" \
  -H "Authorization: Bearer $MOBIUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_account_id": "sa_abc123",
    "name": "doc-summarizer",
    "kind": "llm",
    "capabilities": { "model": "claude-3-5-haiku", "max_tokens": 4096 }
  }'
 
# 2. Register a session at worker startup (use the id returned above)
curl -X POST "$MOBIUS_API/v1/projects/acme/agents/$AGENT_ID/sessions" \
  -H "Authorization: Bearer $MOBIUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "transport": "sse", "metadata": { "hostname": "worker-1" } }'

After step 2, the session enters the connected state and the agent's presence becomes online. Call POST /v1/projects/{project}/agents/sessions/{sessionId}/heartbeat every 30 seconds to keep that presence current. On graceful shutdown, call POST /v1/projects/{project}/agents/sessions/{sessionId}/disconnect to close the session cleanly rather than letting it go stale.

Lifecycle

Session states:

Agent presence (computed from the most recent 20 sessions across all transports):

Agent status:

Where you see it

• Dashboard — Projects → <project> → Agents lists all agents with their presence and status. Click New agent to register one through the UI.
• API — the Agents tag group covers create, update, delete, and session management operations.

See also

• Workflows — the sequences whose steps produce the jobs agents claim.
• Runs — individual workflow executions that generate jobs.
• Triggers — rules that start runs and indirectly generate work for agents.