| name | agentpond |
| description | Inspect and analyze AgentPond traces, observations, sessions, and scores with focused CLI commands and DuckDB SQL. Use when investigating agent behavior, querying trace data, comparing sessions, reviewing annotations, or diagnosing failures after traces have already been collected. |
AgentPond trace analytics
Use AgentPond to inspect collected trace data.
Read only the references relevant to the current task. Provider-specific
references are authoritative for project selection, target selection, and
credential access:
Select the data source
Determine the provider before syncing:
Do not create provider-choice state. Select the provider's environment with
npx agentpond env use <name>: a Firebase alias or project ID, an exact Vercel
target, or a manual AgentPond environment. Use --env <name> only for a
one-command override. Confirm the selection with npx agentpond env current.
Inspect traces
Start with focused commands:
npx agentpond traces list --limit 25
npx agentpond traces get <trace-id>
npx agentpond observations list --traceId <trace-id>
npx agentpond scores list --traceId <trace-id>
Inspect a session when behavior spans multiple traces:
npx agentpond sessions list
npx agentpond sessions get <session-id>
Use SQL for joins, aggregation, time windows, raw event inspection, or cost analysis:
npx agentpond sql "select id, name, session_id, total_cost from traces order by start_time desc limit 10"
Report findings
Separate confirmed observations from inference. Include the provider and target inspected, trace or session IDs, commands or SQL used, the observed pattern, the likely cause, and the smallest useful code, prompt, or workflow change.
