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.

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.

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 for sending, streaming, and listing events.

User 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 for the agent to work toward.
user.tool_result	For sessions with self_hosted environments only, your integration is responsible for providing agent_toolset results. The SDK helpers and CLI do this automatically.

Agent events

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 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 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.

Session events

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, or null when the session has none.
session.thread_created	A multiagent thread was created.
session.thread_status_running	A session thread began executing. Every session emits this for its primary thread; in multiagent 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

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 evaluation has started.
span.outcome_evaluation_ongoing	Heartbeat during an ongoing outcome evaluation.
span.outcome_evaluation_end	An outcome evaluation cycle has completed. A needs_revision result means another cycle follows; satisfied, max_iterations_reached, failed, and interrupted are terminal.

System events

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

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 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 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 that expose an HTTP endpoint, or to private MCP servers through MCP tunnels. 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 for declaring servers on an agent.

For more information on MCP and building MCP servers, see the MCP documentation.

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 also apply.