How do I switch from Helicone to Rius for the Claude Agent SDK?
Rius replaces your Helicone setup for the Claude Agent SDK with an observe wrapper for each task and a manual generation filled from the run result. You get one trace per task with the model, tokens and cost. Your sessions and users move over with rius.session() and rius.user(), and your existing history stays in Helicone.
How it works
The Claude Agent SDK drives the Claude Code runtime in a separate process. No model client runs in your own process, so Rius auto-instrumentation has nothing to hook, and coverage is explicit. Two pieces make up the trace:
- An
observewrapper with theAGENTspan kind makes each task the root span. - A manual generation wraps the
query()loop. You fill it from the run’sResultMessagewith token usage, the real model id and the collected answer.
Rius then computes cost on its side from the model and the token counts, as for any generation. You never send a cost value.
This is a different shape from Helicone, which is mainly a proxy: requests go through a Helicone base URL and Helicone logs them on the way. Rius is OpenTelemetry-based. The Rius SDK creates spans inside your process and exports them, so nothing sits between your code and the provider. The general mapping from Helicone headers to Rius is in Migrate from Helicone, and the wider picture is in Migrate to Rius.
Set it up
-
Install the SDK. The base package is enough, and no extra applies. The
claudeCLI must be installed and authenticated.pip install glassflow-rius claude-agent-sdk -
Add the wrapper and the generation. Leave the Helicone base URL and
Helicone-Authheader in the runtime’s configuration for now: the generation is filled from the run result in your process, whatever base URL the runtime calls, so both tools record the same tasks while you compare. Trace each task like this: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 -
Use a full model id such as
claude-haiku-4-5, not an alias such ashaiku, for both the CLI option and the generation. Cost is computed from the requested model, and an alias produces a generation with no cost. Keepprovider="anthropic"and pass the cache counts as shown. Rius then adds the cache counts to the input tokens for you, so cache-heavy runs are not undercounted. -
Move your Helicone session and user headers onto Rius scopes.
Helicone-Session-Idbecomesrius.session(), and the SDK’s ownsession_idmakes a natural Rius session id.Helicone-User-Idbecomesrius.user().with rius.session(session_id): with rius.user(user_id): await handle_task(task)Replace
Helicone-Property-*values with span attributes. Set per-request values on a span withspan.set_attribute. Per-deployment values go on the resource, as described in the Helicone guide. -
Run one task and open the trace in the console. Check for the root
AGENTspan and a generation with a full model id, tokens and cost. Compare token totals and cost with Helicone on the same tasks, and keep Helicone in place until you are satisfied. Then remove its base URL and headers and revoke the Helicone API key once nothing sends to it.
What you get
A task shows up in Rius like this:
handle-task AGENT 5.0s
└─ claude_agent_turn LLM 5.0s claude-haiku-4-5, tokens + cost- One root span per task, with one generation for the whole runtime turn. It carries the model, input, output and cache tokens, and the answer.
- Cost per turn, computed by Rius. Costs are list-price estimates in US dollars, not billed amounts.
- Sessions from
rius.session()and users fromrius.user(), which feed the trace list and the Users page. - The same Integrations support matrix as every other framework, where the Claude Agent SDK is listed as manual tracing for Python.
When something else fits
- 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.
- Rius is not a gateway. If you rely on Helicone for caching, rate limits, retries or fallbacks, keep it for those and add Rius for tracing. Rius does not import Helicone history, so old traces stay in Helicone and Rius starts from the first span you send.
- Rius has no prompt management, scores, datasets or evals. Keep those workflows in the tool you use for them today.