Monitor sessions and agents

This page covers the operator-side view of agent resources: what the registry exposes for inspecting sessions, what session-level signals to watch, and where to look when something goes wrong.

Get your registry endpoint

Where activity goes

Every Agent Engine operation produces signals you can inspect:

The registry normalizes and persists provider events before it exposes them. Default list and stream responses keep only the Claude event taxonomy and remove Orca envelope fields. With orca-beta, event lists return the complete indexed public transcript, while streams retain the full envelope only for public events. The list is the durable projected view, while SSE is the live delivery view.

Session-level observability

A session's lifecycle is observable end-to-end through three fields and one endpoint.

Status

The status field on a session reports what the agent is currently doing. See Session statuses for the values. A session record is only idle or running; watch for sessions stuck in idle after work should have started. Provider retries appear as session.status_rescheduled events, not as a persisted rescheduling status.

curl -fsS "$ORCA_REGISTRY_URL/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN" \
  | jq '.status'

Stats

session.stats reports session-level timing:

Compare active_seconds to duration_seconds to see how much of a session's lifetime is spent idle versus working.

Usage

session.usage reports token-level usage:

Use these to spot runaway sessions, attribute spend to teams (via metadata), and forecast capacity.

Events

The event list is the highest-fidelity record of what the agent did. Pull a session's full event history with:

curl -fsS "$ORCA_REGISTRY_URL/v1/sessions/$SESSION_ID/events?limit=100&order=asc" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN"

Look for agent.tool_use and agent.mcp_tool_use events to see what tools the agent invoked, the session.status_* events to follow the lifecycle, and session.error for typed failures.

Agent-level observability

To observe activity across many sessions for a single agent, list the sessions filtered by agent_id and aggregate the usage fields client-side. There is no metadata filter on the list endpoint, so select on metadata with jq after fetching:

curl -fsS "$ORCA_REGISTRY_URL/v1/sessions?agent_id=$AGENT_ID&limit=100" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN" \
  | jq '[.data[] | select(.metadata.team == "support") | {id, status, input: .usage.input_tokens, output: .usage.output_tokens}]'

Tag sessions with agent-specific metadata (for example, team, channel, customer_id) so you can slice usage by dimension without scanning every session.

Alerts

Agent Engine does not ship session-level alerting today. To wire up alerts:

• Forward lifecycle changes to your alerting pipeline by tailing the events stream and matching session.status_rescheduled, session.error, and session.deleted. Do not match session.status_terminated - it is reserved and never emitted, so an alert keyed to it never fires.
• Scrape session usage fields on a schedule and alert on cost or token-burn anomalies.
• For registry, harness, or sandbox process alerts, use the service-level metrics and logs exposed by your deployment.

Permissions

Treat every Workspace API key as full access to its Workspace's resources, and separate access with Workspaces. See Control registry access.

What's next