Tracing Agents and Tool Calls

Agents are loops, so trace the loop

An agent repeatedly asks the model what to do next, runs the chosen tool, feeds the result back, and stops when the model produces a final answer or a limit is reached. Agents fail in characteristic ways: calling the wrong tool, passing malformed arguments, looping on the same tool, ignoring a tool error, or running out of steps. A good agent trace has one span per iteration (or per graph node), a generation for each model decision showing the tool call it requested, and a tool span showing the exact arguments and the result or error. Add the step number and the stop reason as metadata. Then common questions become easy: how many steps does a typical task take, which tool fails most, which prompt change reduced loops. Watch cost too: each iteration re-sends the growing conversation, so token usage per step tends to rise as the loop goes on.

A traced agent loop (LangSmith)

Schematic loop with a hard step limit. decide() stands for a model call that returns either a tool request or a final answer.

from langsmith import traceable

MAX_STEPS = 5

@traceable(run_type="tool")
def get_order_status(order_id: str) -> dict:
    return {"order_id": order_id, "status": "shipped"}

TOOLS = {"get_order_status": get_order_status}

@traceable(name="support-agent")
def run_agent(question: str) -> str:
    messages = [{"role": "user", "content": question}]
    for step in range(MAX_STEPS):
        action = decide(messages)  # llm run: returns tool call or final answer
        if action["type"] == "final":
            return action["text"]
        result = TOOLS[action["tool"]](**action["args"])
        messages.append({"role": "tool", "content": str(result)})
    return "Sorry, I could not finish this request."  # step limit reached

A delivery rider's route log

If a Swiggy rider takes 50 minutes, the order total tells you nothing. The route log shows the wrong turn, the closed gate and the second loop around the same block. An agent trace is that route log for every decision.

Make stop reasons visible

Record why the loop ended: final answer, step limit, tool error or timeout. A dashboard filtered on "step limit reached" quickly surfaces prompts or tools that make the agent go round in circles.

त्वरित जाँच: An agent's traces show the same search tool called eight times with nearly identical arguments. What does this most likely indicate?

• The tracing SDK is duplicating spans
• The agent is looping without making progress; check tool results and prompt instructions
• The tool is working perfectly
• Token counting is broken