Quickstart

1. Install

uv add mv37-rollout# or: pip install mv37-rollout

The base package depends only on httpx and pydantic. If you are instrumenting a provider client, add the matching extra so the SDK can parse its responses:

uv add "mv37-rollout[openai]"      # or [anthropic]

2. Get an API key

Create a project in your Rollout workspace and copy its API key. The SDK reads ROLLOUT_API_KEY from the environment by default, so the cleanest setup is to export it and pass nothing in code:

export ROLLOUT_API_KEY="sk_rollout_..."export ROLLOUT_ENVIRONMENT="production"   # optional

3. Initialize a client

You can either create a Rollout client and pass it around, or call rollout.init() once to set up a global client that the module-level helpers and decorators route through. Both read the same options from arguments or the environment.

from mv37.rollout import Rollout# explicit clientclient = Rollout(agent_name="support_agent", environment="production")# — or — one global client for the whole processimport mv37.rollout as rolloutrollout.init(agent_name="support_agent", environment="production")

4. Send your first trace

A trace is one agent run. Open it with a with block, record the conversation with trace.message(...), wrap model calls in an llm span, and let the helper pull token usage straight off the response. The trace flushes automatically when the block exits.

from mv37.rollout import Rollout, usage_from_openaifrom openai import OpenAIclient = Rollout(agent_name="support_agent")openai_client = OpenAI()with client.trace("support_agent", conversation_id="thread_123", user_id="cus_123") as trace:    trace.message(role="user", content="Where is my order?")    with trace.llm("openai.responses", model="gpt-4.1-mini") as span:        span.record_input({"messages": [{"role": "user", "content": "Where is my order?"}]})        response = openai_client.responses.create(model="gpt-4.1-mini", input="Where is my order?")        span.record_output(response)                 # pydantic responses serialize automatically        span.set_usage(**usage_from_openai(response)) # token counts off the response    trace.message(role="assistant", content="Your order has shipped.")    trace.feedback("thumbs_up", True)

5. Verify the connection

check() sends a diagnostic trace through the real ingest path and prints a one-line summary. It is the fastest way to confirm your key, network, and base URL are all working.

client.check()# ✓ Rollout connected — 3 event(s) accepted

It also returns a CheckResult (ok, accepted, rejected, errors, message); pass verbose=False to silence the print and inspect the result yourself.

Next steps

• Wrap your provider client to instrument every LLM call without writing span blocks by hand.
• Use the decorators — @rollout.agent turns an entry point into a fully traced run.
• Run benchmarks with trace context so each attempt links to the trace that explains what happened.
• Wire up shutdown for long-running or async services so no events are lost on exit.