Seclai

Seclai

Sign inStart for free

Documentation

Agent Traces

Agent traces are the per-run execution history for an agent. Every run creates a trace that records what happened from start to finish.

What Are Agent Traces?

A trace is a structured execution record for a single run. It helps you understand:

  • Whether the run succeeded or failed
  • Which step produced which output
  • Where errors happened and why
  • How long each step took
  • How many credits were consumed

If you want to answer "what happened during this run?", traces are the source of truth.

Where to Find Agent Traces

You can view traces in the UI and query run data via the API.

  • Per-agent path: Account → Agents → [Agent Name] → Traces
  • Account-wide path: Dashboard → Agents Tab → All Traces

Use the per-agent Traces tab when you need step-by-step detail for a single agent. Use the Dashboard's All Traces section when you need to search, filter, or compare runs across multiple agents — for example, to spot cross-agent failures or run retroactive governance evaluations on a selection of runs.

What Traces Include

Typical trace details include:

  • Run status (pending, processing, completed, failed)
  • Step-level status and execution order
  • Step input and output payloads
  • Error messages and failure context
  • Duration and timing data
  • Credit usage per run and per step

Why Agent Traces Matter

Traces are designed for operational visibility and confidence. They are most useful for:

  • Debugging: Find the exact failing step and error details
  • Validation: Confirm outputs match expectations
  • Performance tuning: Identify slow steps and bottlenecks
  • Cost monitoring: See credit usage over time
  • Auditability: Keep a reliable record of run behavior

Common Workflows

  1. Open the most recent failed trace for an agent.
  2. Inspect the first step with a failed status.
  3. Review that step's inputs, outputs, and error message.
  4. Update the relevant step, prompt, model, or metadata.
  5. Re-run the agent and compare the new trace.

This loop makes troubleshooting fast and repeatable.

Exporting

Export an agent's trace history as a downloadable file. Supported formats are JSON and JSONL.

  • UI: Open the agent's Traces tab and click the Export button. You'll see an estimate of the export size before confirming.
  • API: POST /authenticated/resource-exports with resource_type: "agent_traces" and the agent ID.
  • MCP: Use the create_resource_export tool with resource_type: "agent_traces".

Exports include run status, step-level inputs/outputs, errors, timing, and credit usage for each run.

See Export Formats → Agent Traces for the full file schema and available filter options.

Next Steps