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 anyAssistantAgentis built. Do not call it per request. - Wrap the entrypoint with observe. One
observewrapper withkind=SpanKind.AGENTgroups agent creation and invocation into a single trace per unit of work. - Leave tools unwrapped. AutoGen runs tools in a detached context, so an
observewrapper on a tool function splits off as its own single-span trace. The framework’sexecute_toolspans already cover tools. - Model calls need no extra code. They go through the OpenAI client from
autogen-ext[openai], and theopenaiintegration records them asChatCompletiongenerations. 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
- Add the packages to your image. The
openaiextra installs the instrumentation, not the OpenAI library itself.
pip install "glassflow-rius[openai]" "autogen-agentchat" "autogen-ext[openai]"- Call
init()with no arguments at startup. It readsRIUS_API_KEYandRIUS_SERVICE_NAMEfrom the environment. Wrap the entrypoint, turnSIGTERMinto a normal exit, and shut down in afinallyblock:
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- Pass the settings to the container as environment variables. This Compose fragment takes the key from the host’s environment or an
.envfile, so it is never committed, names both the service and the agent, and gives the final export more than Docker’s default 10 seconds betweenSIGTERMandSIGKILL:
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- Choose how the container ends, because that decides how spans get out:
- Long-running server.
docker stopsendsSIGTERM, and Python’s default response ends the process without running the exit hook, so callclient.shutdown()from aSIGTERMhandler, 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
SIGTERMor aSIGKILLsends nostoppedping, so the instance reportsgone, which is the crash signal. The last batch can also be lost, which is why the code above handlesSIGTERM.
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.
- 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, withcreate_agent support_agent,invoke_agent support_agent, aChatCompletiongeneration with model, tokens and cost, and anexecute_tool account_statusspan. - 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_NAMEsetsservice.name.RIUS_AGENT_NAMEsets the name the agent is grouped under on the Agents page, and defaults to the service name. Thenameyou giveAssistantAgentand thenameyou giveobservelabel the individual spans. - Instances on the Agents page. The heartbeat is on by default and needs credentials, so a container with
RIUS_API_KEYset shows as running, and a cleanshutdown()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(orRIUS_HEARTBEAT=false) and callclient.flush()at the end of every invocation. - Rius captures AutoGen’s model calls through the
openaiintegration. If your agent reaches models another way, check the Integrations page for the integration that covers that client.