TraceRoot

Open Source AI Agent Improvement Platform

TraceRoot

Find the patterns in your agent's production issues. Ship verified fixes with your coding agent.

https://github.com/user-attachments/assets/2ecf21ce-93b3-41cb-8749-e02b77467357

Core Features

Turn production failures into tested improvements

Trace production runs, use detectors to evaluate behavior, and surface recurring patterns as improvement signals. Your coding agent uses the TraceRoot CLI to investigate those signals and make local changes, then verifies them with offline evals. After you ship, new production traces feed the next round of detection, signals, and verification—closing a continuous improvement loop.

Step	Description
Trace	See each model call, tool call, and response, with inputs, outputs, latency, and cost.
Detect	Define what good behavior looks like. Automatically flag production runs that miss the mark.
Signals	Cluster judge outputs into signals. A background coding agent investigates traces and connected GitHub code in a sandbox to suggest fixes.
Verify	Run evals against your datasets and compare versions to measure improvements and catch regressions.

⭐ Star the Repository

If you like what we’re building, give TraceRoot a star ⭐ to help more developers discover it.

Setting up TraceRoot

Once you have a TraceRoot instance (cloud or self-hosted), create a project in your dashboard and choose how to send your first trace: let your coding agent set up instrumentation through the CLI, or configure an SDK manually.

With your coding agent

Install the TraceRoot CLI and log in:

npm install -g traceroot-cli
traceroot login

Then ask your coding agent:

Use the TraceRoot CLI to set up tracing for this application.

Manually with an SDK

Prefer to configure instrumentation yourself? Use the Python SDK or TypeScript SDK. The example below sends one traced model call from a TypeScript application.

You need Node.js and npm, a TraceRoot project API key, and an OpenAI API key. For self-hosting, replace the cloud host URL below with your instance URL.

1. Install the SDK in your TypeScript project:

npm install @traceroot-ai/traceroot openai

2. Set your API keys:

export TRACEROOT_API_KEY="your-project-api-key"
export TRACEROOT_HOST_URL="https://app.traceroot.ai"
export OPENAI_API_KEY="your-openai-api-key"

3. Trace an agent call. Save this as example.ts:

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);

4. Run it with npx tsx example.ts, then open your project's Traces page to inspect the agent run. This example makes one OpenAI API call.

Getting Started With TraceRoot

TraceRoot Cloud

Create an account to get started without running the platform yourself.

Self-Hosting

With Git, Docker Compose, and Make installed, run locally:

git clone https://github.com/traceroot-ai/traceroot.git
cd traceroot
cp .env.example .env
make prod-lite

Open localhost:3000. See the self-hosting guide for configuration and deployment details.

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.

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.

Security & Privacy

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

Community

Special thanks to pi-mono, which powers our agent runtime.

Contributing 🤝: Help with code, documentation, integrations, or runnable examples. Start with the contribution guide and unassigned beginner issues that do not need approval.

Support 💬: If you need any type of support, we're typically most responsive on our Discord channel, but feel free to email us [email protected] too!

License

TraceRoot uses Apache 2.0 for code outside directories named ee. Those directories are covered by the Enterprise License.

Star History

Contributors