# Concepts Managed Agents has a small domain model. This page covers the objects you work with and the rules that govern them. ## Agents [#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](/docs/agents/agents#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](/docs/agents/vaults-and-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](/docs/agents/environments) (template + repos) for the agent's runs. | | `metadata` | Arbitrary string key/value pairs. | | `org_id` | Optional Console grouping — **not** a security boundary (see [ownership](#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](/docs/agents/agents). ## Sessions [#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`. | | `activity` | Owner-facing read-receipt summary: `state` (`idle`, `working`, `done`, `needs_help`, `failed`, `interrupted`), `unseen` (whether you've acknowledged the latest response or approval request), and `attention_event_id` (the event to acknowledge). See [Sessions & events → Read receipts](/docs/agents/sessions-and-events#read-receipts). | | `usage` | Cumulative token usage (`input_tokens`, `output_tokens`, cache tokens). | | `vm_id` | The bound [environment's](/docs/agents/environments) VM, if any (server-internal). | | `cloned_repos` | Repos cloned into the bound VM. | | `vault_ids` | [Vaults](/docs/agents/vaults-and-mcp) 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 [#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. | | `session.context_compacted` | ← out | The runtime checkpointed older model context into a summary. The visible transcript is unaffected. | 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](/docs/agents/sessions-and-events). ## Automation [#automation] Three objects run agents without a human in the loop: * **[Schedules](/docs/agents/schedules)** — fire an agent on a cron expression in a given timezone, seeding each run with a kickoff message. * **[Triggers](/docs/agents/triggers)** — run an agent in response to GitHub events (PR opened/ready, or a `@cluster-build` mention). * **[Runs](/docs/agents/runs)** — launch a one-off, VM-backed job that provisions, executes, and tears down automatically. ## Ownership [#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.