Skip to Content

How do I trace a customer support agent built with the Claude Agent SDK?

Rius traces a Claude Agent SDK support agent with an observe wrapper as the root span and a manual generation filled from the run result, which gives you one trace per ticket with tokens and cost. Add your own spans for retrieval and for any tool code that runs in your process, then scope each conversation with a session and each customer with a user. The Claude Agent SDK runs the Claude Code runtime in a separate process, so there is no automatic instrumentation for it.

How it works

The Claude Agent SDK drives the Claude Code runtime outside your process, so no model client runs in your code for Rius to hook. The Claude Agent SDK integration is therefore manual and has two pieces:

  • An observe wrapper makes each ticket the root AGENT span.
  • A manual generation wraps the query() loop. You fill it from the run’s ResultMessage with token usage, the real model id and the collected answer. Rius computes cost from those, as for any generation.

A support agent usually does more than one model turn, so the root span is also where your own steps hang. The tracing guide covers the span types you add around the generation:

  • Retrieval: a RETRIEVER span for the help-center or knowledge-base search. It records the data source, how many documents you asked for, and the ids and scores of what came back. It carries identifiers and scores, not document text.
  • Tool code you own: a function in your process, such as an order lookup, gets observe with kind=SpanKind.TOOL. A bare observe makes a CHAIN span, which the Tool kind filter in the Spans tab and the Tool Loop alert do not see.
  • Stages: any other step, such as triage or a policy check, can be a plain observe that appears as a span named after the function.

Tool calls and sub-turns that happen inside the Claude Code runtime produce no spans. The generation records the turn’s totals only.

Session and user are scopes you open around the work. A session groups the turns of one conversation. A user ties together everything one customer did across conversations. Every span started in scope carries session.id and user.id.

Set it up

  1. Install the SDK next to the Agent SDK. The base package is enough, and the claude CLI must be installed and authenticated. Integrations lists what else you can enable.
pip install glassflow-rius claude-agent-sdk
  1. Initialize Rius once at startup, then wrap the ticket handler. In this example search_help_center and lookup_order stand for your own functions, and support-agent, help-center and lookup_order are your own names.
import rius from claude_agent_sdk import ( AssistantMessage, ClaudeAgentOptions, ResultMessage, TextBlock, query, ) from rius import SpanKind rius.init(api_key="ri_...", service_name="support-agent") MODEL = "claude-haiku-4-5" @rius.observe(kind=SpanKind.TOOL, tool_name="lookup_order") def lookup_order(order_id: str) -> dict: ... # your own order system @rius.observe(name="handle-ticket", kind=SpanKind.AGENT) async def handle_ticket(question: str, order_id: str) -> str: with rius.start_as_current_span( kind=SpanKind.RETRIEVER, data_source_id="help-center", top_k=5 ) as obs: obs.set_input(question) docs = search_help_center(question) # your own search obs.set_retrieved_documents([{"id": d.id, "score": d.score} for d in docs]) order = lookup_order(order_id) prompt = f"Order: {order}\nArticles: {[d.text for d in docs]}\nQuestion: {question}" options = ClaudeAgentOptions(model=MODEL, max_turns=1) parts = [] with rius.start_as_current_generation( "claude_agent_turn", model=MODEL, provider="anthropic", input=prompt ) as gen: async for message in query(prompt=prompt, 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"), 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
  1. Open the session and user scopes where a customer message arrives, so every span of the ticket carries both ids. Use your own conversation id and an opaque customer id rather than an email. The Agent SDK’s session_id only arrives in the messages after the root span has started, so it can name the session only when you resume a stored conversation.
async def on_message(conversation_id: str, customer_id: str, question: str, order_id: str): with rius.session(conversation_id), rius.user(customer_id): return await handle_ticket(question, order_id)
  1. Use a full model id such as claude-haiku-4-5, not an alias like haiku. Cost is priced from real model ids, so an alias gives a generation with no cost. Keep provider="anthropic" and pass the cache counts as given: Rius adds them to the input tokens for you.

What you get

One trace per ticket, shaped like this:

handle-ticket AGENT ├─ retrieval help-center RETRIEVER ├─ execute_tool lookup_order TOOL └─ claude_agent_turn LLM claude-haiku-4-5, tokens + cost
  • Tokens and cost for the Claude turn, including cache reads and writes. Cost is a list-price estimate in US dollars.
  • A retrieval span showing which knowledge base you searched and which documents scored what, so you can see why a reply cited the wrong article.
  • Your own tool calls as tool spans, so they show under the Tool kind filter and count for the Tool Loop alert.
  • Traces grouped by session.id into one conversation, and by user.id per customer, so you can follow one customer’s cost and failures across tickets.

To check it, run one ticket and open the trace in the console. The root AGENT span and a generation with a full model id, tokens and cost should be there. A generation with no cost means an alias was used.

When something else fits

  • If you need to see the runtime’s own tool calls, sub-turns and file operations, Rius does not show them for this framework. You see the turn’s totals on the generation, and the tool code you wrap yourself.
  • If your agent also calls a model client directly in your process, an auto-instrumented integration records that call for you. See Integrations for the list.
  • This integration is Python only. In TypeScript, trace the calls with manual generations as shown in the tracing guide.

Still stuck? Get help

Last updated on