> ## Documentation Index
> Fetch the complete documentation index at: https://oma-codex-339-workspace-permissions.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Reference
> Event types, self-hosted worker CLI flags, supported MCP server types, and rate limits for Open Managed Agents.
This page collects reference material for Open Managed Agents. For task-oriented guides, follow the links in each section. For the operations on the session resource, see [Session operations](/docs/en/session-operations).
Managed Agents API requests require the `managed-agents-2026-04-01` beta header, except memory store endpoints, which use `agent-memory-2026-07-22` instead. The SDK sets the correct beta header automatically. See [Beta headers](/docs/en/api/versioning-beta).
## Event types
Persisted event type strings follow a `{domain}.{action}` naming convention; the stream-only event deltas (see the Event deltas tab) are the exception. See [Session event stream](/docs/en/events-and-streaming) for sending, streaming, and listing events.
| Type | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user.message` | A user message with text, image, or document content. |
| `user.interrupt` | Stop the agent mid-execution. |
| `user.custom_tool_result` | Response to a custom tool call from the agent. |
| `user.tool_confirmation` | Approve or deny an agent or MCP tool call when a permission policy requires confirmation. |
| `user.define_outcome` | Define an [outcome](/docs/en/define-outcomes) for the agent to work toward. |
| `user.tool_result` | For sessions with `self_hosted` [environments](/docs/en/self-hosted-sandboxes) only, your integration is responsible for providing `agent_toolset` results. The SDK helpers and CLI do this automatically. |
| Type | Description |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agent.message` | Agent response content blocks. |
| `agent.thinking` | Signals the agent is making forward progress through extended thinking. This is a progress signal only and does not carry the thinking content. |
| `agent.tool_use` | Agent invokes a pre-built agent tool (bash, file operations, and so on). |
| `agent.tool_result` | Result of a pre-built agent tool execution. |
| `agent.mcp_tool_use` | Agent invokes an MCP server tool. |
| `agent.mcp_tool_result` | Result of an MCP tool execution. |
| `agent.custom_tool_use` | Agent invokes one of your custom tools. Respond with a `user.custom_tool_result` event. |
| `agent.thread_context_compacted` | Conversation history was compacted to fit the context window. |
| `agent.thread_message_received` | In a [multiagent](/docs/en/multiagent-orchestration) session, a message from another thread arrived on the thread whose stream carries this event; on the primary thread, an agent sent a report or question to the coordinator. |
| `agent.thread_message_sent` | In a [multiagent](/docs/en/multiagent-orchestration) session, the thread whose stream carries this event sent a message to another thread; on the primary thread, the coordinator sent a task or follow-up message to another agent. |
Message content in these events can include a `redacted` content block, `{"type": "redacted"}`: a placeholder for content withheld by OMA model policy. The block carries no other fields. Redacted blocks appear only in content the platform emits; a user event that includes one is rejected with a 400 error.
| Type | Description |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session.status_running` | Agent is actively processing. |
| `session.status_idle` | Agent finished its current task and is waiting for input. Includes a `stop_reason` indicating why the agent stopped. |
| `session.status_rescheduled` | A transient error occurred and the session is retrying automatically. |
| `session.status_terminated` | Session ended, either because of an unrecoverable error or because it was archived. |
| `session.deleted` | Session was deleted. Terminates any active event stream; no further events are emitted for this session. |
| `session.updated` | Session update request changed at least one field. Includes only the fields that changed. Updates apply on the next turn. |
| `session.error` | An error occurred during processing. Includes a typed `error` object with a `retry_status`. |
| `session.usage` | Snapshot of the session's cumulative usage and tracked list cost. Carries the session's usage totals and an echo of the session's [budget](/docs/en/budgets), or `null` when the session has none. |
| `session.thread_created` | A [multiagent](/docs/en/multiagent-orchestration) thread was created. |
| `session.thread_status_running` | A session thread began executing. Every session emits this for its primary thread; in [multiagent](/docs/en/multiagent-orchestration) sessions, child-thread transitions are also cross-posted to the primary stream. |
| `session.thread_status_idle` | A session thread finished its turn and is awaiting input. Includes `stop_reason`. |
| `session.thread_status_rescheduled` | A session thread hit a transient error and is retrying automatically. |
| `session.thread_status_terminated` | A session thread was archived or reached a terminal error. |
Span events are observability markers that wrap activity for timing and usage tracking.
| Type | Description |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `span.model_request_start` | A model inference call has started. |
| `span.model_request_end` | A model inference call has completed. Includes `model_usage` with token counts. |
| `span.outcome_evaluation_start` | [Outcome](/docs/en/define-outcomes) evaluation has started. |
| `span.outcome_evaluation_ongoing` | Heartbeat during an ongoing [outcome](/docs/en/define-outcomes) evaluation. |
| `span.outcome_evaluation_end` | An [outcome](/docs/en/define-outcomes) evaluation cycle has completed. A `needs_revision` result means another cycle follows; `satisfied`, `max_iterations_reached`, `failed`, and `interrupted` are terminal. |
| Type | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `system.message` | Append privileged system-level context that applies to the accompanying turn and all subsequent turns. Supported on `claude-opus-4-8`, `claude-fable-5`, `claude-mythos-5`, and `claude-opus-5`; on an unsupported primary model the event is rejected with `model_does_not_support_mid_conversation_system`. |
Event deltas are stream-only preview events. They are emitted on stream connections (session-level or per-thread) that opt in with the `event_deltas[]` parameter, and they are never persisted to the session's event history. See [Event deltas](/docs/en/events-and-streaming#event-deltas) for opting in, accumulating, and reconciling them.
| Type | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `event_start` | A previewed event has started generating. Carries the upcoming event's `type` and `id`. Stream-only and never persisted. |
| `event_delta` | Incremental content for a previewed event, identified by `event_id`. Stream-only and never persisted. |
## Self-hosted worker
These are the `ant beta:worker` CLI flags for the pre-built worker that drives a `self_hosted` environment. See [Self-hosted sandboxes](/docs/en/self-hosted-sandboxes) for setting up the environment, running a worker, and the SDK helper options.
| Flag | Description |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--environment-id` | The environment to poll for work. Also reads from `ANTHROPIC_ENVIRONMENT_ID`. |
| `--environment-key` | Authenticates the worker with this environment. Also reads from `ANTHROPIC_ENVIRONMENT_KEY`. |
| `--workdir` | Directory where skills are downloaded and tools read and write files. Defaults to `.` (the current directory); the system default working directory is `/workspace`. |
| `--on-work` | Script to call for each claimed work item instead of running tools in-process. Receives session details as environment variables. |
| `--unrestricted-paths` | Allow the file tools to read and write paths outside `--workdir`. The workdir check is a guardrail for the file tools only, not a sandbox; it does not constrain bash. |
| `--max-idle` | How long to wait after the session goes idle with an `end_turn` stop reason before shutting down. Defaults to `60s`. |
| `--log-format` | Log output format. Use `json` for structured log ingestion. Defaults to `text`. |
## Supported MCP server types
Open Managed Agents connects to [remote MCP servers](/docs/en/mcp-connector) that expose an HTTP endpoint, or to private MCP servers through [MCP tunnels](/docs/en/mcp-connector). The server should support the MCP protocol's streamable HTTP transport; servers that only support the deprecated SSE transport still work through an automatic fallback. See [MCP connector](/docs/en/mcp-connector) for declaring servers on an agent.
For more information on MCP and building MCP servers, see the [MCP documentation](https://modelcontextprotocol.io).
## Rate limits
Managed Agents endpoints are rate-limited per organization:
| Operation | Limit |
| ------------------------------------------------------------- | ------------------------- |
| Create endpoints (such as agents, sessions, and environments) | 300 requests per minute |
| Read endpoints (such as retrieve, list, and stream) | 1,200 requests per minute |
Organization-level [spend limits and usage-tier rate limits](/docs/en/reference#rate-limits) also apply.