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
observewrapper makes each ticket the rootAGENTspan. - 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 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
RETRIEVERspan 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
observewithkind=SpanKind.TOOL. A bareobservemakes aCHAINspan, 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
observethat 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
- Install the SDK next to the Agent SDK. The base package is enough, and the
claudeCLI must be installed and authenticated. Integrations lists what else you can enable.
pip install glassflow-rius claude-agent-sdk- Initialize Rius once at startup, then wrap the ticket handler. In this example
search_help_centerandlookup_orderstand for your own functions, andsupport-agent,help-centerandlookup_orderare 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- 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_idonly 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)- Use a full model id such as
claude-haiku-4-5, not an alias likehaiku. Cost is priced from real model ids, so an alias gives a generation with no cost. Keepprovider="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.idinto one conversation, and byuser.idper 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.