How do I see errors and exceptions in an agent built with CrewAI?
Rius marks a CrewAI trace as failed when any span carries an OpenTelemetry ERROR status, and it highlights that span in the trace with its exception and traceback. The openai integration records CrewAI’s model calls on its own, and you wrap your entrypoint and tool bodies with observe so they show up as spans. Crews and tasks produce no spans of their own.
How it works
Trace status comes from the spans, not from anything your agent reports. A trace reads failed when at least one span carries an ERROR status, normally a recorded exception. Otherwise it reads completed, or running… while a run has started and not ended.
For CrewAI, the spans come from two places:
- The integration, on its own. CrewAI 1.x drives the OpenAI client natively, so the
openaiintegration records each model call as anLLMgeneration with model, tokens, cost and time to first token. If LiteLLM is installed, CrewAI uses it instead, and you use thelitellmintegration. - Your own spans. The crew structure runs inside the framework, where auto-instrumentation cannot see it. You wrap the entrypoint around
crew.kickoff()as the rootAGENTspan and each tool body as aTOOLspan withobserve.
Two gaps matter when you read errors. Crews and tasks have no spans, so the trace does not show which task a failing step belongs to. Generation spans are all named ChatCompletion. Wrap per-task entrypoints with observe if you need the task to be visible.
In the console, a failed trace whose root span finished without an error of its own is badged recovered. Child spans errored, the agent retried or fell back, and the run completed. The errors are still counted. CrewAI catches an exception raised in a tool and passes the error text back to the agent, so a failing tool usually shows as a failed TOOL span inside a run badged recovered, not as a failed run. Back-to-back calls of the same tool with the same input collapse into one row such as fetch_article · 3 attempts · recovered when every attempt but the last failed.
Set it up
- Install the integration and wrap your entrypoint and tools. This is the setup from the CrewAI integration page, which also covers sessions and blind spots in full.
pip install "glassflow-rius[openai]" crewaiimport rius
from crewai import Agent, Crew, Task
from crewai.tools import tool
from rius import SpanKind
rius.init(api_key="ri_...", service_name="my-agent")
def lookup(email: str) -> str:
return "active" # stand-in for your account lookup
@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
print(handle_ticket("Is the account for ana@example.com active?"))- Keep the decorator order on tools:
@tooloutermost,observeon the function body. Mark the tool with the TOOL kind so it appears as a tool span. - Set
CREWAI_TRACING_ENABLED=falsewhere no terminal is attached, so CrewAI’s own tracing prompt does not block the first run. - Run a ticket, then open Traces and filter the status to
failed. Open a trace and look for the highlighted path from the root to the failing span. The detail panel for an error span leads with the exception and traceback. - To go straight to errors, press
]efor the next failed span and[efor the previous one. On the Spans tab, filter by status, and use the All kinds menu to narrow to Tool or LLM spans. See Exploring traces for the full walkthrough.
What you get
- A trace status of
failed,completedorrunning…for every CrewAI run, derived from the spans. - Failed spans highlighted along the path from the root to the error, with the exception and traceback in the span detail.
- Error counts in the trace list and in the trace header, next to tokens and cost.
- A recovered badge when child spans errored but the run itself completed.
- Retry loops collapsed into one row, with the individual attempts one click away.
- Model calls with model, tokens, cost and time to first token, from the integration. A call that reported no token usage shows a blank cost, not $0.
- A named root
AGENTspan and namedTOOLspans from your wrappers, so you can tell which tool a failure belongs to.
For how this fits into running agents day to day, see Monitor AI agents in production.
When something else fits
- If you need to know which CrewAI task an error belongs to, add
observewrappers around per-task entrypoints, since crews and tasks have no spans of their own. - If LiteLLM is installed in your CrewAI project, follow the
litellmintegration instead ofopenai. - If your agent is built on a different framework, the integrations overview lists what each one records.