Concepts
The domain model behind Managed Agents — agents, sessions, events, ownership, and how they fit together.
Concepts
Managed Agents has a small domain model. This page covers the objects you work with and the rules that govern them.
Agents
An agent is a reusable, versioned configuration. It carries no conversation state — it's the template a session runs.
| Field | Description |
|---|---|
id | Server-assigned, immutable (e.g. agt_3f9c2a). |
name | Human-readable name. |
model | The model the agent runs on (e.g. claude-opus-4-8). See models. |
system | The system prompt — the agent's role and instructions. |
tools | Built-in tools the agent may call, as { "name": "..." } references. |
mcp_servers | Remote MCP servers for external tools. |
reasoning_effort | Per-turn reasoning depth: minimal, low, medium, high, xhigh, max (validated per model). |
environment | An optional default VM spec (template + repos) for the agent's runs. |
metadata | Arbitrary string key/value pairs. |
org_id | Optional Console grouping — not a security boundary (see ownership). |
version | Bumps on every edit. Sessions pin the version they started with. |
Editing an agent (PATCH /v1/agents/{id}) creates a new version. Existing
sessions keep running the version they were created with, so an edit never
disturbs work in flight. See Building agents.
Sessions
A session is one runtime instance of an agent — the unit that holds a conversation and runs turns.
| Field | Description |
|---|---|
id | Server-assigned, immutable (e.g. ses_8b1d4e). |
agent_id / agent_version | The agent and the exact version this session runs. |
status | idle (with an optional stop_reason), running, or terminated. |
usage | Cumulative token usage (input_tokens, output_tokens, cache tokens). |
vm_id | The bound environment's VM, if any (server-internal). |
cloned_repos | Repos cloned into the bound VM. |
vault_ids | Vaults attached for MCP credentials. |
A session moves to running while the agent works a turn and back to idle
when it finishes. The stop_reason on an idle session tells you why the turn
ended:
stop_reason | Meaning |
|---|---|
end_turn | The model finished and is awaiting input. |
max_tokens | The turn hit the model's token budget. |
interrupted | A user.interrupt stopped the turn. |
error | A recoverable error ended the turn. |
Events
A session's timeline is an ordered list of events. You append user events;
the runtime appends the agent's. Every event has an id, a type, and a
processed_at timestamp (set once the runtime handles it).
| Event type | Direction | Meaning |
|---|---|---|
user.message | → in | Your input for a turn (text content blocks). |
user.interrupt | → in | Stop the agent mid-turn; the next user.message resumes. |
agent.thinking | ← out | A reasoning block. |
agent.message | ← out | Assistant text. |
agent.tool_use | ← out | The model invoked a tool (tool, input). |
agent.tool_result | ← out | The tool's output (tool_use_id, content, is_error). |
session.status_running | ← out | The agent started processing a turn. |
session.status_idle | ← out | The turn finished (carries stop_reason). |
session.status_terminated | ← out | Unrecoverable error; the session is terminated. |
session.error | ← out | A recoverable error; the session stays alive. |
Two observability markers — span.model_request_start and
span.model_request_end (the latter carries per-call usage) — also appear on
the stream; most clients ignore them.
You submit user events as a batch ({ "events": [...] }) and read them back via
the events endpoints.
Automation
Three objects run agents without a human in the loop:
- Schedules — fire an agent on a cron expression in a given timezone, seeding each run with a kickoff message.
- Triggers — run an agent in response to GitHub
events (PR opened/ready, or a
@cluster-buildmention). - Runs — launch a one-off, VM-backed job that provisions, executes, and tears down automatically.
Ownership
Every object — agent, session, schedule, trigger, environment, vault — is owned
by the identity that created it (the JWT sub). List endpoints return only your
own objects, and fetching or modifying something you don't own returns 404.
org_id on an agent is only a Console grouping aid and a list filter. It does
not widen or restrict visibility — ownership always stays scoped to your identity.