Why Traces Matter
Government AI deployments require explainability and audit trails. When an AI agent makes a decision — whether it is approving a permit, classifying a document, or answering a citizen's question — stakeholders need to understand exactly how that decision was reached.
Execution traces capture every step of an agent's reasoning process: what the LLM considered, which tools it called, what data it received, and how it arrived at its final response.
Trace Structure
Each agent run produces a trace containing an ordered list of steps. Every step records:
| Field | Description |
|---|---|
step_number | Sequential position in the reasoning chain |
type | thought, tool_call, tool_result, or response |
content | The LLM's reasoning text or tool output |
tool_name | Which tool was called (for tool_call steps) |
tool_input | Parameters passed to the tool |
tool_output | Data returned by the tool |
tokens | Token count for this step |
duration_ms | Execution time for this step |
Example Trace
When a citizen asks "What's the status of my visa application VA-2024-001?", the agent produces a trace like:
Step 1 [thought]: The citizen is asking about a specific visa application. I need to look up the status using the application ID.
Step 2 [tool_call]: check_application_status(application_id="VA-2024-001")
Step 3 [tool_result]: {"status": "under_review", "submitted": "2024-01-10", "estimated_completion": "2024-01-20"}
Step 4 [response]: Your visa application VA-2024-001 is currently under review. It was submitted on January 10, 2024, and the estimated completion date is January 20, 2024.
Querying Traces
List All Runs for an Agent
curl http://localhost:8005/api/v1/agents/agt-001/runsResponse:
[
{
"id": "run-001",
"agent_id": "agt-001",
"input": "What's the status of my visa application VA-2024-001?",
"output": "Your visa application VA-2024-001 is currently under review...",
"status": "completed",
"steps_count": 3,
"total_tokens": 450,
"duration_ms": 1200,
"started_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T10:30:01Z"
}
]Get a Specific Trace
curl http://localhost:8005/api/v1/agents/agt-001/traces/run-001This returns the full step-by-step trace with all tool calls, intermediate reasoning, and the final response.
Run Metadata
Each run records aggregate metrics alongside the trace:
| Field | Description |
|---|---|
status | running, completed, failed, or timeout |
steps_count | Total number of reasoning steps |
total_tokens | Combined input + output tokens across all steps |
duration_ms | Wall-clock time from start to completion |
started_at | ISO timestamp of run start |
completed_at | ISO timestamp of run completion |
Performance Monitoring
Use total_tokens and duration_ms from run metadata to monitor agent efficiency. Agents that consistently use many steps or high token counts may benefit from system prompt refinement or additional tools to reduce reasoning loops.
Dashboard Trace Viewer
The Traces page in the Agents dashboard renders execution traces as a visual timeline. Each step is displayed as a card showing:
- The step type (thought, tool call, tool result, response)
- The full content of the step
- Token count and duration
- Tool name and parameters for tool call steps
This visualization makes it straightforward for non-technical stakeholders to review how an agent reached its conclusion.
Compliance and Audit
Traces are immutable once a run completes. They cannot be edited or deleted, ensuring the audit trail remains intact for compliance reviews. Combined with Anar Guard's policy enforcement, traces provide end-to-end accountability for every AI decision in the system.
Key compliance properties:
- Immutability — Completed traces cannot be modified
- Completeness — Every LLM call and tool invocation is recorded
- Traceability — Each trace links to its agent definition, input, and user context
- Queryability — Filter runs by agent, status, date range, and duration