Agent Run Tracing
Agent run tracing connects individual AI requests to the larger task they belong to.
Request logs are useful, but production agents often execute multi-step work: a model call, a tool call, a retry, a workflow branch, a policy decision, and sometimes a payment event. Alephant treats that activity as a run so teams can understand what happened end to end.
Trace Model
What A Run Can Include
A run trace can include:
- Model calls and selected providers
- Tool calls and external API calls
- Workflow steps and branch outcomes
- Prompt template IDs and versions
- Token usage, latency, errors, and retry behavior
- Policy decisions such as allowed, blocked, throttled, or escalated
- Budget consumption and remaining budget context
- Paid endpoint payment events, revenue, and margin data
- Audit events for security and compliance review
Tracking Headers
Gateway requests can include optional headers that help Alephant group requests into sessions and runs:
Use these headers when an application, framework, or workflow engine already knows the task context. If no session headers are present, Alephant still records request-level metadata for the Virtual Key.
For a detailed setup guide with curl, TypeScript, Python, and n8n examples, see Agent IDs And Run IDs.
Common Questions
Why not just use request logs?
Request logs show individual model calls. Run tracing explains the larger execution context: which agent acted, which workflow step created the call, which policy decision applied, and how the total run cost was built.
What is the difference between a session and a run?
A session is a broader interaction or workflow context. A run is one execution inside that context. For example, a support automation session can include several agent runs, tool calls, and follow-up model requests.
How does this connect to cost?
Each step can contribute model cost, tool cost, payment cost, or revenue. Alephant rolls those signals up to agents, workflows, sessions, departments, and workspaces.