Skip to Content

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

Rius traces a CrewAI agent in a Docker container when you call init once at the container’s entrypoint, before you build the crew. Set the agent’s name with the service name, and shut the client down when the container stops. Model calls arrive as generations with tokens and cost, and your observe wrappers give the run and its tools their shape.

How it works

CrewAI 1.x drives the OpenAI client natively, so the openai integration captures its model calls. If LiteLLM is installed in the image, CrewAI uses it instead and the litellm integration captures the calls. With a global init(), every installed integration turns on automatically, so there is nothing else to enable. The CrewAI integration page covers what lands in the trace.

Three things matter in a container:

  • Where init runs. Call it at module level in the file the container starts, before any crew or agent is created. It reads RIUS_API_KEY and RIUS_SERVICE_NAME from the container’s environment, so the key stays out of the image.
  • The agent name. The service name is the agent’s name in Rius. RIUS_AGENT_NAME overrides the name the agent is grouped under, and it defaults to the service name. Agents are found from traces and heartbeats, so there is nothing to register.
  • How spans leave. Spans are queued in memory and exported in batches from a background thread. Python flushes pending spans at a normal interpreter exit, but docker stop sends SIGTERM, and Python’s default response ends the process without running that exit hook, so the last batch is lost unless you handle the signal.

Set it up

  1. Install the SDK with the openai extra and CrewAI in your image. The extra adds the instrumentation, not the library.

    pip install "glassflow-rius[openai]" crewai
  2. Set environment variables on the container: RIUS_API_KEY with your ri_ key and RIUS_SERVICE_NAME with the agent’s name. Also set CREWAI_TRACING_ENABLED=false. CrewAI asks about its own tracing on first run, and in a container no terminal is attached to answer. Set RIUS_MAIN_AGENT_VERSION to your image tag if you want the Agents page to compare versions.

  3. Call init() at the top of the entrypoint, wrap the run as an AGENT span, and wrap each tool body as a TOOL span. Put @tool outermost and observe on the function body.

    import signal import sys import rius from crewai import Agent, Crew, Task from crewai.tools import tool from rius import SpanKind client = rius.init() # reads RIUS_API_KEY and RIUS_SERVICE_NAME signal.signal(signal.SIGTERM, lambda *_: sys.exit(0)) # runs the finally block @tool("account_status") @rius.observe(kind=SpanKind.TOOL) def account_status(email: str) -> str: """Fetch a customer's account standing by email.""" return lookup(email) support_agent = Agent( role="Support specialist", goal="Answer support tickets accurately and concisely.", backstory="You resolve product and account questions.", tools=[account_status], llm="gpt-5-mini", ) @rius.observe(name="handle-ticket", kind=SpanKind.AGENT) def handle_ticket(ticket: str) -> str: task = Task( description=f"Resolve this support ticket: {ticket}", expected_output="A short, direct answer.", agent=support_agent, ) return Crew(agents=[support_agent], tasks=[task]).kickoff().raw if __name__ == "__main__": try: print(handle_ticket("My invoice shows the wrong plan.")) finally: client.flush(timeout_millis=30_000) # force an export client.shutdown() # drain and stop cleanly
  4. Shut down according to how the container runs. A one-shot job flushes and shuts down in the finally block, as above, and the SIGTERM handler turns docker stop into a normal exit so that block runs. A long-running service exports batches continuously and needs client.shutdown() when it stops: call it 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. Docker waits 10 seconds before SIGKILL; raise that with --stop-timeout or stop_grace_period in Compose if needed. Never call flush() inside a request handler, because it blocks until the export completes. The reliability page lists the batching settings.

  5. Run one ticket that calls a tool and open the trace in the console. You should see the root AGENT span named handle-ticket, the LLM generations and your TOOL span.

What you get

  • One trace per run, with the root AGENT span, a generation for each model call with model, tokens, cost and time to first token, and a TOOL span for each tool.
  • Cost as a list-price estimate in US dollars, computed by Rius. You never send a cost value.
  • The agent under your service name on the Agents page. With the heartbeat on (the default) and an API key set, each running container shows as an instance.
  • A clean stop that is distinguishable from a crash. shutdown() sends a final stopped ping. An unhandled SIGTERM or a SIGKILL sends none, and the instance reports gone.

Crews and tasks produce no spans of their own, and generation spans carry the generic name ChatCompletion. If you need to see which task a generation belongs to, wrap per-task entrypoints with observe.

When something else fits

  • If your CrewAI project is not Python, the CrewAI integration does not apply, since it covers only the Python framework. See Integrations for what each language supports.
  • If the container runs in a Lambda-style runtime that freezes the process between invocations, flush at the end of every invocation and turn the heartbeat off, as the reliability page describes.

Still stuck? Get help

Last updated on