Skip to Content

How do I trace an agent built with AutoGen and deployed to a Docker container?

Rius traces an AutoGen agent in a Docker container when you call init once at startup, wrap the entrypoint with observe, and shut the client down when the container stops. AutoGen emits its own spans for agents and tools, and the openai integration adds each model call with tokens and cost. Set the credentials and names as environment variables on the container, so the image holds no secrets.

How it works

AutoGen sends create_agent, invoke_agent and execute_tool spans through the global tracer provider, and rius.init() installs that provider. So the one rule for placement is that init() runs before your code creates or runs an agent.

  • Call init once, at process start. Put it at module level in the file the container runs, or at the top of your main, before any AssistantAgent is built. Do not call it per request.
  • Wrap the entrypoint with observe. One observe wrapper with kind=SpanKind.AGENT groups agent creation and invocation into a single trace per unit of work.
  • Leave tools unwrapped. AutoGen runs tools in a detached context, so an observe wrapper on a tool function splits off as its own single-span trace. The framework’s execute_tool spans already cover tools.
  • Model calls need no extra code. They go through the OpenAI client from autogen-ext[openai], and the openai integration records them as ChatCompletion generations. See AutoGen for the full list of what lands where.

Spans are queued in the container and exported in batches from a background thread, so tracing does not sit on your agent’s hot path.

Set it up

  1. Add the packages to your image. The openai extra installs the instrumentation, not the OpenAI library itself.
pip install "glassflow-rius[openai]" "autogen-agentchat" "autogen-ext[openai]"
  1. Call init() with no arguments at startup. It reads RIUS_API_KEY and RIUS_SERVICE_NAME from the environment. Wrap the entrypoint, turn SIGTERM into a normal exit, and shut down in a finally block:
import asyncio import signal import sys import rius from autogen_agentchat.agents import AssistantAgent from autogen_ext.models.openai import OpenAIChatCompletionClient from rius import SpanKind client = rius.init() signal.signal(signal.SIGTERM, lambda *_: sys.exit(0)) # runs the finally block 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) if __name__ == "__main__": try: print(asyncio.run(handle_ticket("Is the account for ana@example.com in good standing?"))) finally: client.flush(timeout_millis=30_000) # force an export client.shutdown() # drain and send the final stopped ping
  1. Pass the settings to the container as environment variables. This Compose fragment takes the key from the host’s environment or an .env file, so it is never committed, names both the service and the agent, and gives the final export more than Docker’s default 10 seconds between SIGTERM and SIGKILL:
services: support-agent: build: . stop_grace_period: 30s environment: RIUS_API_KEY: ${RIUS_API_KEY} RIUS_SERVICE_NAME: support-service RIUS_AGENT_NAME: support-agent
  1. Choose how the container ends, because that decides how spans get out:
  • Long-running server. docker stop sends SIGTERM, and Python’s default response ends the process without running the exit hook, so call client.shutdown() from a SIGTERM handler, or from your server’s shutdown hook if it already handles the signal, such as a FastAPI lifespan under uvicorn. Start the app in exec form (CMD ["python", "app.py"]) so it is PID 1 and receives the signal.
  • Batch job or one-shot container. Call client.flush() before exiting, as above. A short process can finish before the first scheduled export fires.
  • Hard kill. An unhandled SIGTERM or a SIGKILL sends no stopped ping, so the instance reports gone, which is the crash signal. The last batch can also be lost, which is why the code above handles SIGTERM.

Do not call flush() inside request handlers, because it blocks until the export completes. The Reliability page covers batching, retries and the settings that tune them.

  1. Scope each run to a conversation with rius.session() and your conversation id, so one conversation is one session.

What you get

  • One trace per unit of work, rooted at handle-ticket, with create_agent support_agent, invoke_agent support_agent, a ChatCompletion generation with model, tokens and cost, and an execute_tool account_status span.
  • Cost per call, computed by Rius from the model and token counts as a list-price estimate in US dollars. You never send a cost value.
  • Naming you control in three places. RIUS_SERVICE_NAME sets service.name. RIUS_AGENT_NAME sets the name the agent is grouped under on the Agents page, and defaults to the service name. The name you give AssistantAgent and the name you give observe label the individual spans.
  • Instances on the Agents page. The heartbeat is on by default and needs credentials, so a container with RIUS_API_KEY set shows as running, and a clean shutdown() shows as stopped. An agent that sends traces without a heartbeat, because the heartbeat is off or no credentials are set, is marked no heartbeat and lists no instances.

Run one request that calls a tool, then open the trace in the console and check that the root span, the framework spans and the generation are all present.

When something else fits

  • If the container runs in a Lambda-style runtime that freezes the process between invocations, set heartbeat=False (or RIUS_HEARTBEAT=false) and call client.flush() at the end of every invocation.
  • Rius captures AutoGen’s model calls through the openai integration. If your agent reaches models another way, check the Integrations page for the integration that covers that client.

Still stuck? Get help

Last updated on