README.md

July 2, 2026 · View on GitHub

TraceRoot is an open-source observability platform for AI agents — Capture traces, monitors production issues, and debug with AI that sees your source code and Github history.

Features

Feature	Description
Detectors	LLM-as-judge evaluator monitors incoming trace for hallucinations, tool/logic failures, safety violations, and intent drift — surfaces findings and auto-triggers root cause analysis with email and slack alerts.
Agentic Debugging	AI that sees all your traces, connects to a sandbox with your production source code, identifies the exact failing line, and correlates the failure with your GitHub commits, PRs, and issues. BYOK support for any model provider.
Tracing	Capture LLM calls, agent actions, and tool usage via OpenTelemetry-compatible SDK. Intelligently surfaces the traces that matter — noise filtered, signal prioritized.

Why TraceRoot?

Traces alone don't scale.

As AI agent systems grow more complex, manually sifting through every trace is unsustainable. TraceRoot's Detectors selectively screen incoming traces — flagging hallucinations, tool failures, logic errors, and safety issues automatically, so you spend time fixing problems, not hunting for them.
Debugging AI agent systems is painful.

Root-causing failures across agent hallucinations, tool call instabilities, and version changes is hard. TraceRoot's AI connects to a sandbox running your production source code, identifies the exact failing line, and cross-references your GitHub history — commits, PRs, open issues and creates PR to fix it.
Fully open source, no vendor lock-in.

Both the observability platform and the AI debugging layer are open source. BYOK support for any model provider — OpenAI, Anthropic, Gemini, xAI, DeepSeek, OpenRouter, Kimi, GLM and more.

Documentation

Full documentation available at traceroot.ai/docs.

Getting Started

TraceRoot Cloud

The fastest way to get started. Ample storage and LLM tokens for testing, no credit card needed. Sign up here!

Self-Hosting

Developer mode: Run TraceRoot locally to contribute.

# Get a copy of the latest repo
git clone https://github.com/traceroot-ai/traceroot.git
cd traceroot

# Host the infra in Docker and the app itself locally
make dev

For more details, see CONTRIBUTING.md.

Local docker mode: Run TraceRoot locally to test.

# Get a copy of the latest repo
git clone https://github.com/traceroot-ai/traceroot.git
cd traceroot

# Host everything in Docker
make prod

Terraform (AWS): Run TraceRoot on k8s with Helm and Terraform. This is for production hosting. Still in experimental stage.

Integrations

Native SDKs

Language	Repository
Python	traceroot-py
TypeScript	traceroot-ts

Agent Frameworks

Integration	Supports	Description
Agno	Python	Automated instrumentation of agent runs, tool calls, and multi-step reasoning.
AutoGen	Python	Automated instrumentation of multi-agent conversations, agent loops, and tool calls.
Claude Agent SDK	Python, JS/TS	Automated instrumentation of agent invocations, subagent delegations, tool calls, and token usage.
CrewAI	Python	Automated instrumentation of multi-agent collaborative workflows and task executions.
DSPy	Python	Automated instrumentation of module executions, signature predictions, and underlying LLM calls.
Google ADK	Python	Automated instrumentation of agent runs, tool executions, and the multi-turn agent loop.
LangChain & LangGraph	Python, JS/TS	Automated instrumentation by passing callback handler to LangChain application.
LangChain DeepAgents	Python, JS/TS	Automated instrumentation by passing callback handler to DeepAgents pipeline.
LlamaIndex	Python	Automated instrumentation of RAG pipelines, document ingestion, retrieval, and LLM synthesis.
Microsoft Agent Framework	Python	Automated instrumentation of agent runs, model calls, and tool executions via Agent Framework's built-in OpenTelemetry emission.
Mastra	JS/TS	Automated instrumentation via the TraceRoot OTLP exporter.
OpenAI Agents SDK	Python, JS/TS	Automated instrumentation of agent runs, tool executions, and handoff transitions.
Pydantic AI	Python	Automated instrumentation of agent runs, LLM calls, and tool invocations via pydantic-ai's native OpenTelemetry support.
Vercel AI SDK	JS/TS	Native OpenTelemetry tracing via `experimental_telemetry` — no `instrumentModules` config required.

Model Providers

Integration	Supports	Description
Anthropic	Python, JS/TS	Automated instrumentation of the Messages API.
Google Gemini	Python	Automated instrumentation via the Google GenAI SDK.
Mistral	Python	Automated instrumentation of Mistral chat completions, tool calls, and streaming responses.
OpenAI	Python, JS/TS	Automated instrumentation of Chat Completions and Responses API.
OpenRouter	Python, JS/TS	OpenAI-compatible tracing via the OpenAI SDK base URL; see the Python and TypeScript examples.

Don't see your framework or provider? Request an integration.

Python SDK Quickstart

pip install traceroot openai

import traceroot
from traceroot import Integration, observe
from openai import OpenAI

traceroot.initialize(integrations=[Integration.OPENAI])
client = OpenAI()

@observe(name="my_agent", type="agent")
def my_agent(query: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": query}],
    )
    return response.choices[0].message.content

if __name__ == "__main__":
    my_agent("What's the weather in SF?")

TypeScript SDK Quickstart

npm install @traceroot-ai/traceroot openai

import OpenAI from 'openai';
import { TraceRoot, observe } from '@traceroot-ai/traceroot';

TraceRoot.initialize({ instrumentModules: { openAI: OpenAI } });
const openai = new OpenAI();

const myAgent = observe({ name: 'my_agent', type: 'agent' }, async (query: string) => {
  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: query }],
  });
  return response.choices[0].message.content;
});

async function main() {
  try {
    await myAgent("What's the weather in SF?");
  } finally {
    await TraceRoot.shutdown();
  }
}

main().catch(console.error);

Security & Privacy

Your data security and privacy are our top priorities. Learn more in our Security and Privacy documentation.

Community

Special Thanks for pi-mono project, which powers the foundation of our agentic debugging runtime!

Contributing 🤝: If you're interested in contributing, you can check out our guide here. All types of help are appreciated :)

Support 💬: If you need any type of support, we're typically most responsive on our Discord channel, but feel free to email us founders@traceroot.ai too!