Skip to Content

I trace the Claude Agent SDK with Traceloop. How do I switch to Rius?

To switch to Rius, you remove Traceloop’s init call and decorators and wrap each Claude Agent SDK task in an observe wrapper plus a manual generation. Each task then arrives as one trace with the model, tokens and cost. The generation is filled from the run’s result message. This is the Claude Agent SDK integration, and it is available in Python.

How it works

The Claude Agent SDK drives the Claude Code runtime in a separate process, so no model client runs in your process and Rius auto-instrumentation has nothing to hook. Coverage is manual, in two explicit pieces:

  • An observe wrapper with the AGENT kind makes each task the root span.
  • A manual generation wraps the query() loop. You fill it from the run’s ResultMessage with the token usage, the real model id and the collected answer. Rius computes cost from the model and token counts, so you never send a cost value.

Your Traceloop decorators map onto Rius like this:

  • Traceloop.init(app_name=...) becomes rius.init(api_key=..., service_name=...).
  • @agent(name=...) becomes @rius.observe(kind=SpanKind.AGENT, ...).
  • @tool(name=...) becomes @rius.observe(kind=SpanKind.TOOL, tool_name=...), for tools you run in your own process.
  • @workflow and @task become a plain @rius.observe, which makes a CHAIN span.
  • @conversation and set_conversation_id become with rius.session(...).
  • Association properties such as user_id become with rius.user(...), which sets user.id on every span in scope.

Rius span names follow the GenAI conventions rather than OpenLLMetry’s .agent and .tool suffixes, so update any saved searches that match on span names.

Set it up

  1. Remove the Traceloop setup from one service first. Leave the others reporting to Traceloop while you compare. Delete the Traceloop.init() call, the OpenLLMetry decorators on these functions, and the TRACELOOP_API_KEY, TRACELOOP_BASE_URL and TRACELOOP_HEADERS settings from your deployment. Run OpenLLMetry or the Rius SDK in a process, not both, because both instrument the same client libraries and produce duplicate LLM spans.

  2. Install the SDK. The base package is enough, and no extra applies. The claude CLI must be installed and authenticated.

    pip install glassflow-rius claude-agent-sdk
  3. Wrap the task and the query() loop. Copy this and change your own names and key:

    import rius from claude_agent_sdk import ( AssistantMessage, ClaudeAgentOptions, ResultMessage, TextBlock, query, ) from rius import SpanKind rius.init(api_key="ri_...", service_name="my-agent") MODEL = "claude-haiku-4-5" @rius.observe(name="handle-task", kind=SpanKind.AGENT) async def handle_task(task: str) -> str: options = ClaudeAgentOptions(model=MODEL, max_turns=1) parts = [] with rius.start_as_current_generation( "claude_agent_turn", model=MODEL, provider="anthropic", input=task ) as gen: async for message in query(prompt=task, options=options): if isinstance(message, AssistantMessage): parts.extend( b.text for b in message.content if isinstance(b, TextBlock) ) elif isinstance(message, ResultMessage): usage = message.usage or {} gen.set_usage( input_tokens=usage.get("input_tokens"), output_tokens=usage.get("output_tokens"), cache_read_input_tokens=usage.get("cache_read_input_tokens"), # Anthropic's payload still calls the write count "cache creation" cache_write_input_tokens=usage.get("cache_creation_input_tokens"), ) models = list((message.model_usage or {}).keys()) if models: gen.set_response_model(models[0]) answer = "".join(parts) gen.set_output(answer) return answer
  4. Use a full model id and keep the provider. Use claude-haiku-4-5, not an alias such as haiku, for both the CLI option and the generation. The pricing table matches real model ids only, so an alias gives a generation with no cost. Keep provider="anthropic" and pass the cache counts as they are. Rius then adds them to the input tokens for you, which matters because cache-heavy runs would otherwise undercount badly.

  5. Carry over conversations and users. Scope each conversation with rius.session(). The SDK’s own session_id makes a natural session id. Wrap user-facing work in rius.user().

  6. Verify. Run one task and open the trace in the console. You should see the root AGENT span and a generation with the full model id, tokens and cost. A generation without cost means an alias was used.

If you would rather keep OpenLLMetry for other code and only change where it exports, see Migrate from Traceloop. The Claude Agent SDK still needs the manual pieces above.

What you get

Each task shows as a two-level trace:

handle-task AGENT 5.0s └─ claude_agent_turn LLM 5.0s claude-haiku-4-5, tokens + cost
  • A root AGENT span for the task, from your observe wrapper.
  • One generation for the whole runtime turn, with model, input and output tokens, cache reads and writes, and cost computed by Rius.
  • Sessions from rius.session() and users from rius.user().

The runtime’s inner work is invisible. Tool calls, sub-turns and file operations happen inside the Claude Code process and produce no spans, so the generation records the turn’s totals only. Auth is the CLI’s: an exported ANTHROPIC_API_KEY takes precedence over a claude.ai login.

You can send the same traffic to both backends while you compare, and cut over when Rius shows what you need. The migration overview covers both routes.

When something else fits

  • If you depend on Traceloop’s platform features such as evaluators, guardrails, prompt registry or datasets, keep them there. Rius does not offer them.
  • For other frameworks, Rius has integrations that instrument model calls automatically, so most of this manual setup is not needed.
  • For a TypeScript agent, the Claude Agent SDK integration is not available. Trace those calls with manual generations.

Still stuck? Get help

Last updated on