Inspect agent runs
Use session events and traces to investigate an individual interaction. Start from a known session when possible. Metrics describe aggregate behavior, while inspection helps explain the observations behind those aggregates.
Before you begin
You need permission to inspect the agent and its sessions. Metric-viewing permission alone does not grant trace access. The trace API accepts the account roles agent_viewer, agent_developer, agent_administrator, viewer, administrator, and owner. Its list operation also supports agent-scoped authorization.
Record the agent key, session key, and relevant UTC window. Treat session content and tool arguments as potentially sensitive. Do not include credentials or unnecessary content when sharing diagnostic evidence.
Inspect a session in the Console
- Open Dev tools > Agents, select the agent, and open Sessions. Open the conversation you want to inspect.
- Select the Debug action, identified by a bug icon. The Debug drawer lists the available events with their types and timestamps.
- Expand an event to inspect its JSON. Use Expand all or Collapse all to control the list. The ordering choices are Order most recent events at top and Order first events at top.
- Compare the event types, recorded timestamps, and payloads relevant to the issue. An empty drawer displays No events found. It is not evidence that an unrelated metric has a zero value.
- With an existing session open, select View traces. The action opens the trace view filtered to the session and, when available, its agent and session-creation time range.
Expected result: you can identify the relevant event payloads and trace records for that session. These are different views of the activity, not interchangeable counters. For creating new activity rather than inspecting existing activity, see Agent sessions.
Retrieve traces and spans
Use GET /v2/agent_analytics/traces to list trace records with optional agent_key, session_key, status, and time filters. Use a returned trace ID with GET /v2/agent_analytics/traces/{trace_id}/spans to read its spans. The trace-list response is not the span list.
Follow metadata.page_key when another page is present. A span's parent_span_id identifies its parent so you can reconstruct the tree. Do not assume one trace per session or equate all spans with agent invocations. See the measurement model.
Span content is excluded by default. Set include_content=true only when the available input/output messages or tool arguments are needed. This can expose more sensitive data than aggregate metric reads.
Use the generated List agent traces, Get agent trace, and List spans in a trace references for operation-specific parameters and authorization.
Use inspection to check a metric
- Match the agent and operation to the metric definition. An
invoke_agentcount and anexecute_toolcount measure different observations. - Match the depth population. A custom metric with Top-level sessions only excludes sub-agent sessions and missing depth values.
- Match the metric's time window and returned bin boundaries. A custom metric uses the end of the span to assign a time bin. A trace-list filter on start time is not an equivalent metric filter.
- Account for backfill and coverage limits. Use inspection to explain a discrepancy, not to assume that every older span remains available for reconciliation.
- Check whether the metric selects
evaluate_run_condition. Trace reads currently omit that operation, so inspection cannot confirm those observations. See requests rejected before an agent runs.
When reporting an unresolved issue, share the metric name if relevant, agent/session keys, UTC window, status/error detail, and trace IDs. Include event content only as necessary.