Tag Every Agent Run With a Trace ID

Every time your agent runs — whether it is a single LLM call, a multi-step tool-use workflow, or a multi-agent orchestration — it should be tagged with a unique trace ID. This ID follows the run through your logs, your observability platform, your cost tracker, and your evaluation results. Without it, you have a pile of uncorrelated events. With it, you have a timeline you can reconstruct.

Agent debugging is forensic work. When an agent produces a wrong output, you need to trace backward: what model was used? What tools were called? What were the intermediate outputs? What was the prompt? How many tokens were consumed? If each of these events lives in a different system — your LLM gateway, your tool execution logs, your cost tracker, your application logs — you need a shared key to join them.

The trace ID is that key.

Without it:

• A user reports "the agent gave me a weird answer yesterday" and you have no way to find which run it was
• You cannot calculate per-task cost because token usage is logged separately from task identifiers
• You cannot build an evaluation pipeline because you cannot match outputs to inputs
• You cannot detect regressions because you cannot compare runs across model versions

With it:

• "Show me trace a3f7b2c1" gives you the complete execution timeline
• Cost dashboards group by trace ID to show per-task spend
• Eval pipelines use trace IDs to link agent outputs to test cases
• Regression detection compares trace IDs from old model vs new model on the same inputs

1. Generate a trace ID at the start of every run. Use a UUID or a timestamp+random string. Do this before the first LLM call.

import uuid

trace_id = f"run_{uuid.uuid4().hex[:12]}"

2. Pass it through every system. Your LLM gateway, your tool executor, your logger, and your cost tracker should all receive the trace ID. Most observability platforms (Langfuse, Helicone, Fiddler, Pydantic Logfire) support trace-level metadata.

# Langfuse example
from langfuse import Langfuse

langfuse = Langfuse()
trace = langfuse.trace(id=trace_id, name="research-agent", user_id="user123")

# Pass trace to each LLM call
response = client.chat.completions.create(
    model="glm-5.2",
    messages=messages,
    extra_headers={"X-Trace-Id": trace_id}
)

3. Log it everywhere. Every log line, every tool call, every intermediate result should include the trace ID. This is non-negotiable.

import logging
logger = logging.getLogger(__name__)

logger.info(f"[{trace_id}] Starting research agent", extra={"trace_id": trace_id})
# ... agent runs ...
logger.info(f"[{trace_id}] Tool call: web_search query='GLM-5.2 pricing'", extra={"trace_id": trace_id})
# ... 
logger.info(f"[{trace_id}] Complete. Tokens: {total_tokens}, Cost: ${cost}", extra={"trace_id": trace_id})

4. Store it with the output. When you save agent outputs to a database, include the trace ID. When you return results to the user, include it in the response metadata. This lets users reference specific runs when reporting issues.

5. Use it in your eval pipeline. Your evaluation suite should record trace IDs alongside test case results. When a test fails, you can pull the full trace to understand why.

6. Set up trace-based dashboards. Group cost, latency, and error rate by trace ID in your observability platform. This shows you per-task metrics rather than aggregate averages, which hide outliers.

• Your LLM gateway logs do not include a trace ID field
• You can find an agent output in your database but cannot find the corresponding LLM calls
• Your cost report shows total spend but cannot break it down by task
• A user reports a bad output and you have to search timestamps across multiple systems to find the run
• Your evaluation pipeline cannot link test results back to execution traces