Skip to main content

Frequently Asked Questions

General​

What is TraceAgent?​

TraceAgent is an observability and tracing platform for AI agents. It captures tool calls, file operations, shell commands, and decision paths — giving you complete visibility into what your agents are doing.

Is TraceAgent open source?​

Yes. TraceAgent is released under the MIT License. You can find the source code on GitHub.

What Python versions are supported?​

TraceAgent requires Python 3.11+.

Pydantic AI and OpenTelemetry​

Can I use the capability and OpenTelemetry on the same agent?​

No, pick one per agent. Both record every model call and tool and don't know about each other, so the run would appear twice. The one valid mix is creating the run with the SDK and letting OpenTelemetry supply the spans. See Hooks or OpenTelemetry?.

Will TraceAgent slow down or break my agent if the server is down?​

No. Events are queued and sent by a background thread. After a failed delivery the integration pauses for failure_cooldown seconds, prints one warning line and keeps the agent running. With OpenTelemetry, the exporter sends spans in the background and only logs a warning if it can't reach the server.

Are my prompts and outputs stored?​

The server keeps a summary of each prompt and output. With TRACE_AGENT_CAPTURE_FULL_PAYLOADS on (the default) it also keeps the full content; set it to false to keep only summaries. With OpenTelemetry you can also stop the content from leaving the agent with include_content=False. With the capability, use redact_fields for sensitive keys.

Which Pydantic AI versions are supported?​

Pydantic AI 2.x (>=2,<3). For OpenTelemetry, the default instrumentation version of Pydantic AI 2.x is supported. Older instrumentation versions (2 to 4) use different span names and are not translated.

Why does my short script show no run when I use OpenTelemetry?​

The exporter sends spans in the background. Call provider.shutdown() (or force_flush()) before the script exits. See Troubleshooting.

Installation​

Can I install only the SDK without the server?​

Yes. Each package is independent:

pip install trace-agent-sdk
# or, with uv
uv add trace-agent-sdk

The SDK sends events to any running TraceAgent server — you don't need to install the server on the same machine.

Does it work with virtual environments?​

Yes. We recommend using venv, conda, or uv to manage your Python environment.

Server​

What databases are supported?​

  • SQLite (default) — Zero configuration, great for development
  • PostgreSQL — Recommended for production deployments

How do I change the database?​

Set the TRACE_AGENT_DATABASE_URL environment variable:

# PostgreSQL
TRACE_AGENT_DATABASE_URL=postgresql://user:password@localhost:5432/traceagent

# SQLite (default)
TRACE_AGENT_DATABASE_URL=sqlite:///./data/trace_agent.db

Troubleshooting​

TraceAgent: System error detected
Is the system misbehaving? Let's debug.

The UI is not connecting to the server​

  1. Verify the server is running: curl http://localhost:8000/health
  2. Check that TRACE_AGENT_SERVER_URL points to the correct host
  3. If using Docker, ensure the services are on the same network

I see "connection refused" errors​

The server is not running or is on a different port. Check:

  • Is the server process running?
  • Is port 8000 available?
  • Are you behind a firewall or proxy?

Events are not appearing in the UI​

  1. Verify the SDK is pointing to the correct server URL
  2. Check that run.finish() was called
  3. Refresh the UI — some views require a page reload
Getting Help

Can't find what you're looking for? Open an issue on GitHub.

💬 Comments