Skip to Content

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_agent and execute_tool spans through the global tracer provider, which rius.init() installs. Agent and tool structure arrives with no wrappers.
  • Generations. Model calls go through the OpenAI client, so the openai integration 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 observe wrapper 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 calls init() has its own instance ID.

The AutoGen integration page covers what lands in the trace and the known quirks.

Set it up

  1. 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]"
  2. Call init at module level, once. Put it at the top of the module your container runs, before you create an AssistantAgent and outside any request handler. Leave the API key out of the code: init reads RIUS_API_KEY from the environment, which step 4 fills from a Secret. Keep the returned client so you can shut down later. Wrap the entrypoint with observe and the AGENT kind. Leave your tool functions unwrapped, because AutoGen runs tools in a detached context and an observe wrapper would split off as its own single-span trace. The framework’s execute_tool spans 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)
  3. Name the agent. The service_name is what Rius groups the agent under, and RIUS_AGENT_NAME overrides it if you want a different grouping name. You can also set RIUS_SERVICE_NAME and RIUS_API_KEY as environment variables on the container instead of passing them in code. Pick a stable name per deployment, such as support-agent, and keep it the same across replicas so they group together. The name you give AssistantAgent is separate: it appears in the create_agent and invoke_agent span names, so use a meaningful one. Set RIUS_MAIN_AGENT_VERSION if you want the Agents page to compare versions.

  4. Shut down on SIGTERM and deploy with a Secret. Kubernetes sends SIGTERM to 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 handles SIGTERM, such as uvicorn, call client.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 final stopped heartbeat. An unhandled SIGTERM or a SIGKILL sends no stopped ping and the instance reports gone, 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 rius with the key api-key, and reference it from the container. Kubernetes waits terminationGracePeriodSeconds (30 by default) after SIGTERM before it sends SIGKILL, 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-key

    Do not call flush() inside request handlers. It blocks until the export completes. The reliability page lists the batching settings and retry behavior.

  5. Group turns into sessions. Wrap each run in rius.session() and reuse your conversation id, so one conversation is one session.

  6. Verify. Send one request that calls a tool, then open the trace in the console. You should see the handle-ticket root, the invoke_agent and execute_tool spans, and the ChatCompletion generation 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 ChatCompletion generation 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 stopped signal when you call shutdown(), and gone when 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.

Still stuck? Get help

Last updated on