rollout
Sign up free
SDKCLICookbook

CookbookObserve

Trace an agent end to end

Wrap your provider client and decorate your entry point — two calls — and every run shows up as a trace with messages, LLM spans, tool calls, and token usage. No manual span plumbing required.

1. Install & set your key

The base install is lightweight; the openai extra adds automatic parsing for the OpenAI client. Set ROLLOUT_API_KEY in the environment.

shell
pip install "mv37-rollout[openai]"export ROLLOUT_API_KEY="..."

2. Instrument the agent

Call rollout.init() once, wrap() your provider client so every call is recorded as an llm span, and decorate your entry point with @rollout.agent to group the whole run into one trace.

agent.py
import mv37.rollout as rolloutfrom openai import OpenAIrollout.init(agent_name="support_agent", environment="production")openai_client = rollout.wrap(OpenAI())@rollout.agentdef run_agent(user_message: str) -> str:    response = openai_client.responses.create(        model="gpt-4.1-mini",        input=user_message,    )    return response.output_text

Tool calls come for free

Any tool the wrapped client invokes is recorded as a paired tool.call / tool.result span. To record tools you call yourself, see Tools.

3. View the trace

Run your agent, then open Traces in the workspace. Each run is one trace you can replay — messages, every LLM and tool span, latency, and token counts pulled straight off the provider response. Add feedback & signals to label which runs actually went well.

shell
python agent.py# → trace support_agent  ·  1 llm span  ·  512→128 tok  ·  840ms