Session event stream

Communication with Claude Managed Agents is event-based. You send user events to the agent, and receive agent and session events back to track status.

Event types

Events flow in two directions.

• User events are what you send to the agent to kick off a session and steer it as it progresses.
• Session events, span events, and agent events are sent to you for observability into your session state and agent progress.

Event type strings follow a {domain}.{action} naming convention.

Every event includes a processed_at timestamp indicating when the event was recorded server-side. If processed_at is null, it means the event has been queued by the harness and will be handled after preceding events finish processing.

Integrating events

Additional scenarios

Handling custom tool calls

When the agent invokes a custom tool:

1. The session emits an agent.custom_tool_use event containing the tool name and input.
2. The session pauses with a session.status_idle event containing stop_reason: requires_action. The blocking event IDs are in the stop_reason.requires_action.event_ids array.
3. Execute the tool in your system and send a user.custom_tool_result event for each, passing the event ID in the custom_tool_use_id param along with the result content.
4. Once all blocking events are resolved, the session transitions back to running.

Tool confirmation

When a permission policy requires confirmation before a tool executes:

1. The session emits an agent.tool_use or agent.mcp_tool_use event.
2. The session pauses with a session.status_idle event containing stop_reason: requires_action. The blocking event IDs are in the stop_reason.requires_action.event_ids array.
3. Send a user.tool_confirmation event for each, passing the event ID in the tool_use_id param. Set result to "allow" or "deny". Use deny_message to explain a denial.
4. Once all blocking events are resolved, the session transitions back to running.

Tracking usage

The session object includes a usage field with cumulative token statistics. Fetch the session after it goes idle to read the latest totals, and use them to track costs, enforce budgets, or monitor consumption.

{
  "id": "sesn_01...",
  "status": "idle",
  "usage": {
    "input_tokens": 5000,
    "output_tokens": 3200,
    "cache_creation_input_tokens": 2000,
    "cache_read_input_tokens": 20000
  }
}

input_tokens reports uncached input tokens and output_tokens reports total output tokens across all model calls in the session. The cache_creation_input_tokens and cache_read_input_tokens fields reflect prompt caching activity. Cache entries use a 5-minute TTL, so back-to-back turns within that window benefit from cache reads, which reduce per-token cost.