Follow the Python path behind an agent action.

An unexpected tool call

Consider a hypothetical Python agent that asks a model what to do with an order. The model returns an instruction to update it. The application checks the response, chooses the update_order branch and calls a tool. Later, a team member asks why the order changed. A fresh run may receive a different model response or different tool data, so it cannot reliably reproduce the Python path that ran originally.

def handle_model_reply(reply, tools):
    if reply["action"] == "update_order" and reply["confidence"] >= 0.8:
        return tools.update_order(reply["order_id"], reply["new_status"])
    return {"status": "review_required"}

This example illustrates the investigation; it is not a tested Retrace integration with any particular model provider, agent framework or order system. The important evidence is the response the Python application actually received, the branch conditions it evaluated and any external tool response it then consumed.

Record first, then replay the application

Retrace’s record-replay architecture intercepts supported external boundary calls during a recorded Python run. Recording executes the external call and keeps its result. During replay, the same Python code receives the captured result instead of contacting that external service again.

If a model client and tool client use supported, recorded boundaries, a replay could present the original model response and tool result to the agent’s Python code. An engineer could pause in the documented debugger, inspect the response fields and call stack, and follow the branch that selected update_order. That can help separate a surprising model output from an application validation error, retry or tool-selection bug. It does not require asking the model to generate the same response again.

The recording must exist before the action under investigation. Keep the relevant source, Python version and dependencies available for replay. Recordings may contain prompts, responses, identifiers or other sensitive data, so access and retention need to be planned for the workload.

What this can and cannot explain

Replay can help show what the Python application did with the external response it received. It cannot reveal an LLM’s hidden reasoning or private model state. It cannot recover an agent run that was never recorded, and it cannot promise that every model SDK, framework, asynchronous path or tool integration is supported. A boundary missed by the current recorder can cause replay to diverge rather than produce a faithful investigation.

Start with how Python record-replay works and the public compatibility notes. The pytest quickstart demonstrates the current supported recording and debugger workflow. To evaluate an agent application, discuss a specific investigation and test its actual clients and boundaries before relying on replay.