Metadata-Version: 2.4
Name: trace-agent-server
Version: 0.3.0
Summary: TraceAgent FastAPI backend server.
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
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: fastapi<1.0.0,>=0.115.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: openai<4.0.0,>=1.52.0
Requires-Dist: opentelemetry-proto<2.0.0,>=1.28.0
Requires-Dist: pydantic<3.0.0,>=2.8.0
Requires-Dist: pydantic-settings<3.0.0,>=2.3.0
Requires-Dist: sqlalchemy<3.0.0,>=2.0.32
Requires-Dist: uvicorn[standard]<1.0.0,>=0.30.0
Provides-Extra: dev
Requires-Dist: pytest<9.0.0,>=8.3.2; extra == "dev"
Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == "dev"
Provides-Extra: providers
Requires-Dist: anthropic>=0.42.0; extra == "providers"
Requires-Dist: google-generativeai>=0.8.0; extra == "providers"
Provides-Extra: langchain
Requires-Dist: trace-agent-langchain; extra == "langchain"
Provides-Extra: pydantic-ai
Requires-Dist: trace-agent-pydantic-ai; extra == "pydantic-ai"

# TraceAgent Server

![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)
![Docker Build](https://github.com/LixusSoftware/TraceAgent/actions/workflows/build-docker.yml/badge.svg)
[![Website](https://img.shields.io/badge/website-traceagent.vercel.app-blue)](https://traceagent.vercel.app)

FastAPI backend for TraceAgent. Stores runs, generates timelines, execution graphs, and explanations.

## Install

```bash
pip install trace-agent-server[providers]
```

## Run

```bash
# With the included CLI
trace-agent-server --host 0.0.0.0 --port 8000

# Or directly with uvicorn
uvicorn trace_agent_server.main:app --reload
```

## Tracing agents through OpenTelemetry

The server is also an OTLP/HTTP receiver: an agent that already emits OpenTelemetry spans following the
[GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) (Pydantic AI does) is
traced by pointing its exporter at `POST /v1/traces`, with nothing from TraceAgent installed in the agent.

```python
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from pydantic_ai import Agent
from pydantic_ai.capabilities import Instrumentation
from pydantic_ai.models.instrumented import InstrumentationSettings

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:8000/v1/traces")))

agent = Agent("openai:gpt-4o", capabilities=[Instrumentation(settings=InstrumentationSettings(tracer_provider=provider))])
agent.run_sync("hello")
provider.shutdown()  # a short script must flush before exiting
```

- One run is created per trace (the trace id is the run id), named after `gen_ai.agent.name`. Add a `trace_agent.run_id`
  resource attribute to attach the spans to a run you created with the SDK instead.
- `invoke_agent` spans become chain steps, `chat` spans model calls and `execute_tool` spans tools. Event times and
  durations come from the spans; the run gets its provider, model, token totals and tool counters. Other spans are ignored.
- The run ends when its last agent span ends, also when the agent runs under a web server span or calls other agents.
- An agent whose output goes through an output function (`output_type=my_function`) also records that function as a tool
  (`final_result` by default), because Pydantic AI emits an `execute_tool` span for it. It counts in the run's tool total
  and shows up as a tool choice. The framework capability only records the agent's regular tools, so the two routes differ
  by that one tool for such agents. Structured output (`output_type=SomeModel`) is not affected.
- Prompts and outputs are summarized. Full payloads are stored only if `TRACE_AGENT_CAPTURE_FULL_PAYLOADS` is on.
- Protobuf and JSON bodies are accepted, gzip included. Use either this or the framework integrations for an agent, not
  both, or its run is recorded twice.

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `TRACE_AGENT_DATABASE_URL` | `sqlite:///./trace_agent.db` | Database URL (SQLite or PostgreSQL) |
| `TRACE_AGENT_OTLP_ENABLED` | `true` | Accept OpenTelemetry traces on `POST /v1/traces` |
| `TRACE_AGENT_OTLP_MAX_BODY_BYTES` | `10000000` | Largest accepted OTLP request, after decompression |
| `TRACE_AGENT_CAPTURE_FULL_PAYLOADS` | `true` | Keep full payloads, not only summaries |
| `TRACE_AGENT_OPENAI_API_KEY` | - | OpenAI API key |
| `TRACE_AGENT_OPENAI_BASE_URL` | - | OpenAI-compatible base URL (e.g. LM Studio) |
| `TRACE_AGENT_AUDIT_ENABLE_GUARDRAILS` | `false` | Enable prompt injection and PII checks |
| `TRACE_AGENT_AUDIT_METRICS_ENABLED` | `true` | Expose Prometheus `/metrics` endpoint |

## License

MIT
