How to Trace LLM Agent Runs

How to Trace LLM Agent Runs

Tracing an LLM agent run means recording every meaningful step the agent takes while completing a task. For a production agent, that usually includes the user input, system prompt, model calls, tool calls, retrieval results, action summaries, retries, errors, state changes, and final response.

Agent failures rarely come from one bad completion. A customer support agent might call the right tool with the wrong account ID. A coding agent might read the correct file, skip a failing test, then submit a patch that looks reasonable. A research agent might retrieve stale context and produce a confident answer. Without a trace, you only see the final output. With a trace, you can inspect the path that produced it.

What an agent trace should capture

A useful trace gives you enough detail to replay, debug, and evaluate a run without guessing. At minimum, record these fields:

• Run ID: A unique identifier for the full agent run.
• Parent run ID: The calling run, if this agent was started by another workflow.
• User input: The original task or message that started the run.
• System and developer prompts: The instructions sent to the model.
• Model calls: Model name, parameters, messages, response text, token usage, latency, and cost.
• Tool calls: Tool name, arguments, response, latency, status, and error details.
• Retrieval events: Query text, retrieved document IDs, scores, snippets, and filters.
• State updates: Memory writes, scratchpad changes, plan updates, and step counters.
• Decision points: Why the agent chose a tool, retried, escalated, or stopped.
• Final output: The response returned to the user or downstream system.
• Metadata: Environment, app version, prompt version, user ID, tenant ID, session ID, and feature flag state.

You do not need to store every byte forever, but you do need enough structure to answer a simple question: “What happened during this run, and why?”

Use a trace hierarchy

Agent runs are easier to inspect when you model them as nested spans. A top-level run contains child spans for model calls, tool calls, retrieval, routing, planning, validation, and final response generation.

A simple hierarchy might look like this:

agent_run
  plan_task
    model_call
  retrieve_context
    vector_search
  call_tool
    crm_lookup
  validate_answer
    model_call
  final_response
    model_call

This structure helps you find slow steps, failed tools, prompt regressions, and loops. It also makes multi-step agents easier to compare across versions.

Define a consistent trace schema

Before you instrument your agent, define a schema your team can use across environments. Consistency matters more than complexity. A small, stable schema will beat a large one that each service writes differently.

Here is a practical event shape:

{
  "trace_id": "tr_123",
  "span_id": "sp_456",
  "parent_span_id": "sp_001",
  "span_type": "tool_call",
  "name": "search_orders",
  "status": "success",
  "started_at": "2026-05-28T14:03:21.120Z",
  "ended_at": "2026-05-28T14:03:21.940Z",
  "latency_ms": 820,
  "inputs": {
    "customer_id": "cust_789"
  },
  "outputs": {
    "order_count": 3
  },
  "metadata": {
    "environment": "production",
    "prompt_version": "support-agent-v12",
    "model": "gpt-4.1",
    "tenant_id": "tenant_abc"
  }
}

For model calls, add token usage, temperature, response format, tool choice, and finish reason. For retrieval, add document IDs, ranking scores, collection names, and filters. For tools, add sanitized arguments and typed error codes.

Instrument the agent at each boundary

Trace the boundaries where the agent makes decisions or communicates with another system. These are the points where failures usually appear.

1. Start a trace when the task begins. Create a trace ID as soon as the user request enters your system.
2. Attach the trace ID to every step. Pass it through model calls, tool calls, queues, workers, and callbacks.
3. Create spans for each meaningful operation. Use separate spans for planning, retrieval, tool execution, validation, and final response generation.
4. Record inputs and outputs carefully. Store enough data to debug behavior, but redact secrets and sensitive user data.
5. Close spans with status and timing. Every span should end with success, error, timeout, cancellation, or skipped.
6. Store prompt and model versions. You need version data when comparing runs before and after a prompt change.

If your agent uses asynchronous jobs, background workers, or queues, propagate the trace ID in the job payload. Otherwise, you will lose the connection between the user request and later agent actions.

Trace prompts as versioned artifacts

Prompt changes can alter agent behavior as much as code changes. Store the prompt name, version, rendered input variables, and final message payload for every model call.

For example, a support agent trace should show whether the model received:

• The current refund policy or an older policy.
• The correct user subscription tier.
• The full conversation history or a truncated version.
• The right tool instructions for order lookup and refund creation.

This lets you separate prompt issues from retrieval issues, tool issues, and model behavior. It also makes rollbacks safer because you can compare runs by prompt version.

Capture tool calls with typed errors

Tool calls are one of the highest-value parts of an agent trace. A model can choose the wrong tool, pass invalid arguments, ignore a tool result, retry too aggressively, or continue after a failed call.

For each tool call, record:

• Tool name and version: For example, create_refund:v3.
• Arguments: Redacted when needed, but still structured.
• Validation result: Whether arguments matched the expected schema.
• Execution result: The returned payload or failure.
• Error type: Such as validation_error, auth_error, rate_limit, timeout, or upstream_500.
• Retry count: How many times the agent retried and why.

Typed errors help you build dashboards and alerts. If 40% of failed runs come from validation_error on one tool, you probably need better tool instructions, stricter schemas, or a repair step before execution.

Record retrieval context

If your agent uses RAG, trace the retrieval layer. A bad answer often starts with missing, stale, or irrelevant context.

Record the search query, embedding model, collection name, filters, returned document IDs, chunk text or references, rank, score, and reranker output. If you cannot store full chunks because of data policies, store document IDs and safe snippets.

This is especially useful when a model gives an answer that seems wrong but was reasonable given the retrieved context. In that case, the fix belongs in indexing, chunking, permissions, retrieval ranking, or context selection.

Trace loops and stopping conditions

Agents need clear stopping rules. Your trace should show when the agent stops, why it stops, and whether it hit a limit.

Track these counters:

• Number of model calls.
• Number of tool calls.
• Number of retrieval calls.
• Total tokens used.
• Total cost.
• Total runtime.
• Retries per step.
• Max planning iterations reached.

If an agent keeps calling the same tool with slightly different arguments, the trace should make that obvious. You can then add loop detection, stronger stop conditions, or a validation step that forces the agent to explain what new information it expects from another call.

Support multi-agent workflows

Tracing becomes more important when multiple agents coordinate. In multi-agent systems, you should record which agent performed each step, what message it received, what it returned, and how control moved between agents.

Use fields such as agent_name, agent_role, handoff_reason, and recipient_agent. If you run an agent swarm, also track fan-out count, aggregation logic, voting behavior, and which outputs were discarded.

When a system uses an orchestration layer or an LLM compiler pattern, trace the generated plan, the compiled steps, and the runtime execution separately. This helps you determine whether the plan was wrong or the execution failed.

Use traces for debugging

A good trace turns debugging into a direct inspection task. Instead of asking “Why did the agent do that?”, you can review the sequence:

1. The user asked for a refund.
2. The agent retrieved the refund policy.
3. The retrieved policy was outdated.
4. The model called create_refund with the wrong reason code.
5. The tool returned a validation error.
6. The agent retried with a guessed reason code.
7. The final response told the user the refund had been processed, even though the tool failed.

That trace points to several concrete fixes: refresh the policy index, improve the tool schema, prevent unsupported retries, and require tool success before claiming completion.

Use traces for evaluation

Traces are also useful for LLM evaluation. Final-answer grading can miss important failures inside the run. A response may look correct while the agent used the wrong source, skipped a required tool, or exposed data it should not have accessed.

Run evaluations at multiple levels:

• Final output: Was the answer correct, complete, and safe?
• Tool usage: Did the agent call the required tool with valid arguments?
• Retrieval: Did the agent use the right documents?
• Policy compliance: Did the agent follow business rules?
• Efficiency: Did the agent complete the task within cost and latency targets?

For example, you can grade whether a support agent must call get_order_status before answering a shipping question. If the final answer is correct but the agent guessed without calling the tool, the trace should mark that as a process failure.

Use traces for production monitoring

Tracing also supports LLM observability. Once your traces use a consistent schema, you can track trends across production runs.

Useful metrics include:

• Agent success rate by prompt version.
• Error rate by tool.
• Average model calls per run.
• Runs that hit max iteration limits.
• Token cost per successful task.
• Latency by span type.
• Retrieval miss rate.
• Fallback and escalation rate.

These metrics help you catch regressions after prompt edits, model changes, retrieval updates, or tool releases. For example, if average tool calls per run jumps from 3 to 11 after a prompt change, you may have introduced unclear instructions or a loop.

Handle privacy and security carefully

Agent traces can contain sensitive data. Treat them as production data, not debug logs.

Use these practices:

• Redact secrets: Never store API keys, auth tokens, passwords, or private credentials.
• Minimize sensitive fields: Store IDs instead of full personal data when possible.
• Apply access controls: Limit who can view traces with user data or customer content.
• Set retention periods: Keep detailed traces only as long as you need them.
• Separate environments: Do not mix development traces with production traces.
• Audit access: Record who viewed or exported trace data.

If you need traces for long-term analysis, consider storing sanitized versions. Keep raw payloads for a shorter window, such as 7 to 30 days, and retain structured metrics for longer periods.

Common tracing mistakes

• Only logging the final answer: You cannot debug agent behavior if you skip the intermediate steps.
• Dropping failed calls: Failed spans are often the most useful part of the trace.
• Missing prompt versions: Without versions, you cannot connect behavior changes to prompt edits.
• Storing unstructured text only: Freeform logs are hard to query and compare.
• Ignoring retries: Retries can hide flaky tools, unclear schemas, and looping behavior.
• Not propagating trace IDs: Async jobs and background workers need the same trace context.

A practical rollout plan

If you do not have tracing yet, start small. You can add useful tracing in a few stages:

1. Week 1: Add trace IDs, top-level run records, final outputs, latency, model name, token usage, and errors.
2. Week 2: Add spans for model calls, tool calls, and retrieval events.
3. Week 3: Add prompt versions, tool versions, retry tracking, and typed error codes.
4. Week 4: Add dashboards for success rate, cost, latency, tool errors, and max-iteration runs.
5. Week 5: Connect traces to evaluation datasets and regression tests.

This phased approach gives your team value quickly without requiring a full observability rebuild.

Final checklist

Before you ship an agent to production, make sure your traces can answer these questions:

• What did the user ask?
• Which prompt version ran?
• Which model calls happened?
• Which tools did the agent call?
• What arguments did it pass?
• What did each tool return?
• Which documents did retrieval return?
• Where did retries happen?
• What errors occurred?
• Why did the agent stop?
• What did the user receive?
• How much did the run cost?

If you can answer those questions quickly, you can debug failures, evaluate behavior, and improve your agent with confidence.

PromptLayer helps AI teams trace agent runs, manage prompt versions, evaluate outputs, and monitor production behavior in one place. To start tracing your LLM applications, create a PromptLayer account.