Metadata-Version: 2.4
Name: trace-agent-pydantic-ai
Version: 0.6.0
Summary: Pydantic AI capability integration for TraceAgent.
Author-email: Enrique Javier Villar Cea <villarcea.enriquejavier@gmail.com>, Javier Rodriguez Castellano <javirodriguezcastellano@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/LixusSoftware/TraceAgent
Project-URL: Repository, https://github.com/LixusSoftware/TraceAgent
Project-URL: Issues, https://github.com/LixusSoftware/TraceAgent/issues
Keywords: agent,observability,tracing,llm,tools,pydantic-ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: trace-agent-sdk
Requires-Dist: pydantic-ai-slim<3.0.0,>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest<9.0.0,>=8.3.2; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: trace-agent-server; extra == "dev"
Requires-Dist: opentelemetry-sdk>=1.28.0; extra == "dev"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.28.0; extra == "dev"

# TraceAgent Pydantic AI Integration

![GitHub Release](https://img.shields.io/github/v/release/LixusSoftware/TraceAgent)
![GitHub Stars](https://img.shields.io/github/stars/LixusSoftware/TraceAgent)
![GitHub License](https://img.shields.io/github/license/LixusSoftware/TraceAgent)
![Tests](https://github.com/LixusSoftware/TraceAgent/actions/workflows/test.yml/badge.svg)
[![Website](https://img.shields.io/badge/website-traceagent.vercel.app-blue)](https://traceagent.vercel.app)

Pydantic AI capability that streams agent runs, model requests and tool calls into TraceAgent.
Requires Pydantic AI 2.x.

## Install

```bash
pip install trace-agent-pydantic-ai
```

## Usage

```python
from pydantic_ai import Agent
from trace_agent_sdk import TraceAgentClient

client = TraceAgentClient("http://localhost:8000")
run = client.start_run("my-agent", "Do something")

agent = Agent("openai:gpt-4o", capabilities=[run.as_pydantic_ai_capability()])
result = agent.run_sync("hello")

run.finish(result.output)
```

The capability never breaks or slows the agent. Events are delivered by a background thread; if the backend is unreachable or hangs, a one-line warning is printed, trace delivery pauses for a while, and the agent keeps running. Events produced while paused are dropped. The end of the outermost run waits a few seconds at most for pending events, so `run.finish()` is delivered after them.

Pydantic AI prints a startup banner suggesting Logfire while its own observability is off. It is unrelated to TraceAgent and can be silenced with `PYDANTIC_AI_NO_BANNER=1`.

## Without any code: OpenTelemetry

Pydantic AI already emits OpenTelemetry spans, and the TraceAgent server can receive them, so an agent can be traced
without this package at all: export its spans over OTLP to `http://<server>/v1/traces`. See the
[server README](../trace-agent-server/README.md#tracing-agents-through-opentelemetry) and
[`examples/pydantic_ai_otel_agent.py`](../../examples/pydantic_ai_otel_agent.py).

Pick one route per agent. The capability above records more detail you control (redaction, node events) and works
without OpenTelemetry; the OpenTelemetry route needs no change to the agent. Using both records the run twice.

## Options

`run.as_pydantic_ai_capability(...)` accepts:

| Option | Default | Description |
|---|---|---|
| `record_model_events` | `True` | Record each model request as an LLM call (tokens, model, requested tools) |
| `record_tool_events` | `True` | Record each tool execution (args, output summary, duration, errors) |
| `record_node_events` | `False` | Record every agent graph node |
| `redact_fields` | `[]` | Argument / output keys replaced with `[redacted]` |
| `failure_cooldown` | `30.0` | Seconds to stop sending (and drop events) after a failed delivery. `0` retries every event |
| `flush_timeout` | `5.0` | Maximum seconds the end of the outermost run waits for pending events |

## License

MIT
