How do I see errors and exceptions in an agent built with Pydantic AI?
Rius shows errors in a Pydantic AI agent on the Traces page, where a trace with any failed span reads failed and the span’s exception and traceback lead its detail panel. Pydantic AI emits its own spans for agent runs, model requests and tool calls, so those steps arrive in the trace with no wrappers. Code of yours that runs outside those spans needs a span of its own, which you add with observe. Filter by status to find failures, then open the trace to see which step failed.
How it works
Pydantic AI is OpenTelemetry-native. rius.init() installs the global tracer provider, and Agent.instrument_all(True) tells the framework to send its spans through it. What the framework records on its own:
- An agent run is the root span, named
invoke_agentfollowed by your agent’s name. - A model request is a generation named
chatfollowed by the model, with tokens and cost. - A tool call is a span named
execute_toolfollowed by the tool name.
Rius does not take an error flag from your agent. It derives the trace status from the spans. A trace is failed when at least one span carries an OpenTelemetry ERROR status, normally a recorded exception. Otherwise it is completed. Successful Pydantic AI spans arrive with status UNSET rather than OK, and the trace still reads completed.
If a failed trace has a root span that finished without an error of its own, it is badged recovered. A child step errored, the agent retried or fell back, and the run completed. The errors are still counted.
What needs something from you:
- Your own code outside the framework’s spans. A helper that your tool calls, or a step before or after
run_sync, has no span until you wrap it withobserve. - Content in the failing span. Prompts, completions and tool arguments are controlled by Pydantic AI’s
InstrumentationSettings(for exampleinclude_content), on top of the SDK’s privacy controls. If you want to see a failing tool’s arguments, check that setting. - Runs that crash. A span reaches Rius once, when it ends, so a process that dies mid-run sends nothing for the unfinished spans. Set
RIUS_PARTIAL_SPANSto true to send a content-free snapshot when each span starts. A run that never finished then stays visible as running….
Set it up
- Install the SDK and turn on the framework’s instrumentation. No extra is needed. This is the whole shared setup, and the Pydantic AI integration page covers it in full.
pip install glassflow-rius pydantic-aiimport rius
from pydantic_ai import Agent
rius.init(api_key="ri_...", service_name="my-agent")
Agent.instrument_all(True)
support_agent = Agent(
"openai:gpt-5-mini",
instructions="Answer support questions; check accounts with the tool.",
)
def lookup(email: str) -> str:
return "active" # stand-in for your account lookup
@support_agent.tool_plain
def account_status(email: str) -> str:
"""Fetch a customer's account standing by email."""
return lookup(email)
conversation_id = "conv-123" # your own conversation id
ticket = "Is the account for ana@example.com active?"
with rius.session(conversation_id):
result = support_agent.run_sync(ticket)
print(result.output)- Wrap your own steps that sit outside the framework’s spans. A bare
observemakes a span named after the function, so the step shows up in the tree next to the framework’s spans.load_accounthere is your own function.
@rius.observe
def load_account(email: str) -> dict:
...-
Run a request that fails, then open Traces in the console. Set the status filter to
failed, or open the Spans tab and filter by status there. The All kinds menu narrows the list to one kind, such as Tool. -
Open the trace. In the waterfall, failed spans are highlighted along the path from the root to the error. Select the failed span and read the exception and traceback at the top of its detail panel.
-
Step between failures with the keyboard. Press
]efor the next failed span and[efor the previous one. Press?for the full list of keys.
For how to read the trace list, the Spans tab and the span panel in detail, see Exploring traces.
What you get
- A trace list where failed runs are one filter away, with the error count on each row.
- A waterfall that points from the root span to the span that failed, so you see whether the model request, the tool call or your own step raised it.
- The exception and traceback at the top of the failed span’s detail panel.
- Retry chains collapsed into one row such as
fetch_article · 3 attempts · recovered, when every attempt but the last failed. Expand the row for each attempt. - The recovered badge for runs where a child step failed but the run finished clean, so you can tell fallbacks from genuine failures.
- Sessions: with
rius.session()around each run, the framework’s spans inherit the conversation id, and the Session link in the trace header opens every span in that conversation. - Time to first token and reasoning tokens on the model requests, next to the errors.
- Verification in one run: a request that calls a tool should show the
invoke_agentroot, thechatgenerations and theexecute_toolspans.
When something else fits
- If your agent has several frameworks or client libraries, the Integrations page lists how each one arrives in the trace.
- If you use Pydantic AI without the Rius SDK, you can point any OpenTelemetry setup at the ingest endpoint instead, but you then set up the exporter yourself.