AI Agents & MCP Support
Relevant source files
The following files were used as context for generating this wiki page:
Pydantic Logfire provides specialized observability for AI Agents and the Model Context Protocol (MCP). This support allows developers to trace complex multi-agent workflows, tool calls, handoffs, and guardrails across various frameworks including OpenAI Agents, Pydantic AI, and DSPy. By integrating deeply with these frameworks, Logfire captures the nuances of LLM reasoning and agentic behavior, presenting them as structured, queryable telemetry.
The instrumentation focuses on high-level agent operations while maintaining compatibility with the underlying OpenTelemetry signals. This includes specialized span types for agent runs, tool executions, and MCP interactions, ensuring that the relationships between different parts of an AI system are preserved in the trace hierarchy.
Sources: mkdocs.yml:118-128, tests/otel_integrations/test_openai_agents.py:53-154
OpenAI Agents Integration
Logfire integrates with the OpenAI Agents SDK to provide automated tracing of agent lifecycles. This is primarily achieved through the instrument_openai_agents() function, which wraps the Agents SDK tracing providers with Logfire-specific implementations.
Instrumentation Architecture
The integration wraps the Agents SDK Trace and Span objects. When a trace is started in the Agents SDK, Logfire creates a corresponding OpenTelemetry span with metadata such as the agent_trace_id and group_id.
The diagram shows how Logfire wraps internal Agents SDK entities to generate structured OpenTelemetry spans.
Sources: logfire/_internal/integrations/openai_agents.py:18-132, tests/otel_integrations/test_openai_agents.py:55-68
Captured Agent Spans
Logfire categorizes different agentic operations into specific span types. This allows the UI to render them with appropriate icons and metadata.
| Span Name Template | Purpose | Key Attributes |
|---|---|---|
OpenAI Agents trace: {name} | Root of an agent workflow | agent_trace_id, group_id, metadata |
Agent run: {name!r} | Execution of a specific agent | name, handoffs, tools, output_type |
Function: {name} | Execution of a tool/function | name, input, output, mcp_data |
Handoff: {from_agent} → {to_agent} | Transfer of control between agents | from_agent, to_agent |
Guardrail {name!r} {triggered=} | Validation of inputs or outputs | name, triggered |
Sources: tests/otel_integrations/test_openai_agents.py:73-154, tests/otel_integrations/test_openai_agents.py:535-618
Model Context Protocol (MCP) Support
MCP support in Logfire allows for the observability of external tools and resources provided via MCP servers. Logfire captures tool listings and tool executions performed through MCP.
MCP Tracing Logic
When an agent interacts with an MCP server, Logfire records the details of the tool negotiation and the subsequent results. This is often visible within Function spans where mcp_data is populated.
The sequence shows the data flow when an agent invokes a tool via an MCP server under Logfire instrumentation.
Sources: tests/otel_integrations/test_openai_agents.py:760-770, tests/otel_integrations/cassettes/test_pydantic_ai_mcp/test_pydantic_ai_mcp_sampling.yaml:1-125
CLI and Server Interaction
The Logfire CLI provides utilities for interacting with MCP, such as creating read tokens specifically for MCP environments. This is often used to allow agentic IDEs like Claude Code to access Logfire data via a dedicated MCP bridge.
- Command:
logfire read-tokens --project <org>/<project> create - Usage: Generates a token to be used by
uvx logfire-mcp@latest.
Sources: logfire/_internal/cli/init.py:186-192, mkdocs.yml:195
Specialized AI Telemetry Features
Guardrails and Exceptions
Logfire specifically monitors agent guardrails. If a guardrail "tripwire" is triggered, the span is marked with a failure status (level 17/Error) and includes details about the triggered guardrail. Standard exceptions within tool calls are also captured as OpenTelemetry events.
Sources: tests/otel_integrations/test_openai_agents.py:535-618, tests/otel_integrations/test_openai_agents.py:840-966
Voice and Multimodal Support
Instrumentation extends to voice pipelines, including speech-to-text (transcription) and text-to-speech (synthesis) operations. These are recorded as structured spans with attributes defining audio formats and model configurations.
| Feature | Span Name | Relevant Attributes |
|---|---|---|
| Transcription | Speech → Text with {model} | input.format, output (text) |
| Synthesis | Text → Speech | input (text), output.format |
| Pipeline | Text → Speech group | Aggregate container for synthesis |
Sources: tests/otel_integrations/test_openai_agents.py:1010-1110
Configuration and Setup
To enable AI agent tracing, developers typically call the specific instrumentation function for their framework. This must be done after logfire.configure().
import logfire
from agents import Runner
logfire.configure()
logfire.instrument_openai_agents()
# Agent workflows now automatically generate traces
Sources: logfire/_internal/config.py:347-440, tests/otel_integrations/test_openai_agents.py:55-58
Resource Attributes for AI
Logfire adds specific resource attributes to telemetry generated by AI agents to provide context about the environment and the service.
- service.name: The identifier for the agentic service.
- gen_ai.system: Set to
openaior other providers to identify the LLM backend. - process.runtime.name: Identifies the Python implementation (e.g.,
cpython).
Sources: logfire/_internal/config.py:507-550, tests/otel_integrations/test_openai_agents.py:73-154
Summary
AI Agents & MCP Support in Logfire transforms raw LLM logs into structured agentic traces. By wrapping framework-specific tracing providers and adding rich metadata to spans, Logfire enables developers to visualize handoffs, tool executions, and guardrail triggers. This specialized support ensures that the unique architectural patterns of AI applications are first-class citizens within the observability platform.