How do I trace an agent built with AutoGen and deployed to a Kubernetes deployment?
Rius traces an AutoGen agent in a Kubernetes deployment when you call rius.init once at process start, before you build any agents, and give it a service name. AutoGen’s own spans and the OpenAI generations then arrive in one trace per unit of work. Kubernetes stops a pod with SIGTERM, and Python’s default response skips the exit hook, so you call client.shutdown() in a SIGTERM handler to send the last spans and a clean stop.
How it works
- Framework spans. AutoGen emits
create_agent,invoke_agentandexecute_toolspans through the global tracer provider, whichrius.init()installs. Agent and tool structure arrives with no wrappers. - Generations. Model calls go through the OpenAI client, so the
openaiintegration records each one with model, tokens and cost. Rius computes cost from the model and token counts, so you never send it. - One root per unit of work. A single
observewrapper on your entrypoint groups agent creation and invocation into one trace. - Background export. Spans are queued in the process and sent in batches from a background thread, so tracing never sits on your agent’s hot path. A batch goes out every 5 seconds by default (
OTEL_BSP_SCHEDULE_DELAY). - Heartbeat. The SDK sends a heartbeat for the whole life of the process, so the agent appears on the Agents page when
init()runs. Each process that callsinit()has its own instance ID.
The AutoGen integration page covers what lands in the trace and the known quirks.
Set it up
-
Install the SDK in your image. Add the package and the AutoGen packages to your dependencies. The integrations overview explains the extras.
pip install "glassflow-rius[openai]" "autogen-agentchat" "autogen-ext[openai]" -
Call
initat module level, once. Put it at the top of the module your container runs, before you create anAssistantAgentand outside any request handler. Leave the API key out of the code:initreadsRIUS_API_KEYfrom the environment, which step 4 fills from a Secret. Keep the returned client so you can shut down later. Wrap the entrypoint withobserveand the AGENT kind. Leave your tool functions unwrapped, because AutoGen runs tools in a detached context and anobservewrapper would split off as its own single-span trace. The framework’sexecute_toolspans already cover them.import rius from autogen_agentchat.agents import AssistantAgent from autogen_ext.models.openai import OpenAIChatCompletionClient from rius import SpanKind client = rius.init(service_name="support-agent") # reads RIUS_API_KEY from the environment def account_status(email: str) -> str: """Fetch a customer's account standing by email.""" return lookup(email) @rius.observe(name="handle-ticket", kind=SpanKind.AGENT) async def handle_ticket(ticket: str) -> str: agent = AssistantAgent( name="support_agent", model_client=OpenAIChatCompletionClient(model="gpt-5-mini"), tools=[account_status], system_message="Answer support questions; check accounts with the tool.", ) result = await agent.run(task=ticket) return str(result.messages[-1].content) -
Name the agent. The
service_nameis what Rius groups the agent under, andRIUS_AGENT_NAMEoverrides it if you want a different grouping name. You can also setRIUS_SERVICE_NAMEandRIUS_API_KEYas environment variables on the container instead of passing them in code. Pick a stable name per deployment, such assupport-agent, and keep it the same across replicas so they group together. Thenameyou giveAssistantAgentis separate: it appears in thecreate_agentandinvoke_agentspan names, so use a meaningful one. SetRIUS_MAIN_AGENT_VERSIONif you want the Agents page to compare versions. -
Shut down on
SIGTERMand deploy with a Secret. Kubernetes sendsSIGTERMto stop a pod. Python’s default response ends the process without running the exit hook, and the SDK installs no signal handlers, so handle the signal yourself. If your server already handlesSIGTERM, such as uvicorn, callclient.shutdown()in its shutdown hook instead, for example a FastAPI lifespan. Start the process in exec form (CMD ["python", "app.py"]) so it receives the signal as PID 1.shutdown()drains the queue and sends the finalstoppedheartbeat. An unhandledSIGTERMor aSIGKILLsends nostoppedping and the instance reportsgone, which is the crash signal by design.import signal import sys def on_sigterm(signum, frame): client.shutdown() # drain queued spans, send the stopped heartbeat sys.exit(0) signal.signal(signal.SIGTERM, on_sigterm)Store the API key in a Secret named
riuswith the keyapi-key, and reference it from the container. Kubernetes waitsterminationGracePeriodSeconds(30 by default) afterSIGTERMbefore it sendsSIGKILL, so leave room for the final export.spec: template: spec: terminationGracePeriodSeconds: 60 containers: - name: agent image: registry.example.com/support-agent:1.4.0 env: - name: RIUS_SERVICE_NAME value: support-agent - name: RIUS_API_KEY valueFrom: secretKeyRef: name: rius key: api-keyDo not call
flush()inside request handlers. It blocks until the export completes. The reliability page lists the batching settings and retry behavior. -
Group turns into sessions. Wrap each run in
rius.session()and reuse your conversation id, so one conversation is one session. -
Verify. Send one request that calls a tool, then open the trace in the console. You should see the
handle-ticketroot, theinvoke_agentandexecute_toolspans, and theChatCompletiongeneration with model, tokens and cost.
What you get
- One trace per unit of work, with your entrypoint as the root AGENT span and AutoGen’s agent and tool spans beneath it.
- Each model call as a
ChatCompletiongeneration with tokens and a list-price cost estimate in US dollars. - The agent listed on the Agents page under the name you chose, with instances from the heartbeat when an API key is set.
- A clean
stoppedsignal when you callshutdown(), andgonewhen the process dies without it. - Conversations grouped by session id.
When something else fits
- If your service runs in a different language, AutoGen has no TypeScript integration in Rius. Trace those calls with manual generations instead, as the integrations overview describes.
- If a process is short-lived, such as a batch job, call
client.flush()before it exits rather than relying on the exit hook.