Python SDK¶
Wrap the operations you want to measure and export the final trace. This example uses local data and needs no model provider.
import agentloop
@agentloop.trace_tool(name="lookup_note")
def lookup_note(topic: str) -> str:
return {"quality": "Check the final answer."}[topic]
with agentloop.trace_agent("notes_agent") as trace:
output = {"note": lookup_note("quality")}
trace.metadata["output"] = output
trace.export_json("runs/notes_agent.json")
Analyze the recorded operations and open the report.
Tracing entry points¶
| Entry point | Purpose |
|---|---|
trace_agent(name) |
Open and finalize a trace context |
trace_tool(name=...) |
Decorate a sync or async tool function |
trace_model(name=...) |
Decorate a model operation |
trace_tool_call(name, ...) |
Record an explicit tool span |
trace_model_call(name, ...) |
Record an explicit model span |
record_model_call(...) |
Record a completed call with observed timing and usage |
AgentTrace.from_json(path) |
Read an existing native trace |
trace.export_json(path) |
Save a trace for analysis and comparison |
The framework integration guide includes provider and framework examples. Workflow tracing covers stages and structured decision pipelines.
Output and usage evidence¶
The example explicitly retains the final output in metadata.output so quality
checks can evaluate it. Choose the task's expected answer independently and keep
it in the quality fixture or guided task manifest.
Record token counts from their available source. Provider counts, tokenizer counts, supplied counts, estimates and unavailable usage keep their provenance. Read trace schema and pricing before interpreting cost comparisons. Trace retention covers capture controls.
Compare an applied change¶
Use guided optimization to freeze a task set and baseline findings before capturing a candidate. The intervention ledger links original predictions with outcomes, and paired studies retain repeated comparisons.
Clients and other runtimes¶
The HTTP API guide describes API v1 and client compatibility. The TypeScript SDK records native traces and provides an API client for Node.js applications.