Skip to main content
The traceroot Agent is built into traceroot and serves as both an investigative trace debugger and an interactive project assistant. The agent can analyze execution traces, clone production code into sandboxes to locate root causes, and open fix pull requests on GitHub. Beyond investigation, the agent can also modify your project by creating, updating, and deleting monitoring resources—in an attended chat session every change is proposed for your approval before it runs, and a delete never runs without one.
traceroot Home page assistant with three starter prompts and the chat input

Home: starter prompts and the chat input

The Home Page & Persistent Chat

The first item in the traceroot project sidebar is Home, a full-page AI assistant with starter prompts for common tasks:
  • “Investigate the most recent errored trace”
  • “Summarize today’s sessions”
  • “What did detector findings flag this week?”

Conversation Persistence

Chat state lives in the app-wide assistant provider, scoped to the project you are in:
  • Navigates with you: A conversation started on the Home page survives navigating across different pages (such as Traces, Dashboards, or Detectors) and remains accessible in the right-hand assistant drawer.
  • Stored sessions: Conversations are saved as project sessions, allowing you to review past debugging trajectories and findings at any time.
  • Turn-level trace links: Assistant responses include a View trace button when their trace is available or still uploading; failed trace exports are marked unavailable.

Investigative Capabilities

When debugging issues in your AI applications, the agent provides four core investigation capabilities:
  • Trace analysis — Ask natural language questions about your traces, error trends, latencies, and token costs without writing manual ClickHouse queries.
  • Root cause analysis (RCA) — The agent clones your production repository into an isolated sandbox, reads the exact source file and line where an error occurred, and correlates git commit history with trace failures.
  • Automated fix PRs — After diagnosing a failure, the agent can implement a code fix on a new branch and open a GitHub pull request for human review. The agent never pushes directly to your default branch.
  • Parallel runs — Launch multiple debugging sessions concurrently to investigate separate traces and failure patterns simultaneously.

Changing Project Resources (Write Actions)

In addition to querying telemetry, the agent binds 13 write tools capable of modifying project resources directly through conversation:

Scope Boundary: No Workspace or Project Writes

The agent operates strictly within the project tenancy injected by the active chat session:
  • The agent cannot create, update, or delete workspaces.
  • The agent cannot create, update, or delete projects.
Administrative changes to workspaces and projects are intentionally restricted to the CLI, Public REST API, and workspace settings.

Safety: Interactive Approvals and Timeouts

In an attended chat session, every write the agent proposes pauses for your decision before it runs:

Confirmation Cards

Whenever the agent decides to invoke a write tool, execution pauses and presents an interactive confirmation card in the chat:
  • Creates and Updates: You can choose to Approve (execute the change), Skip (cancel the change), or Revise (provide feedback or changes in natural language so the agent re-proposes the action with adjustments).
  • Deletes: To protect against accidental deletions, destructive actions offer only Approve or Skip. A skipped deletion is never re-proposed from revisions.
If you skip or decline an action, the agent acknowledges the skip and continues the conversation without retrying the tool call.
For creates and updates, the confirmation card is a review gate rather than a security control: a session with no user attached to it, such as a system-initiated run, executes them without showing a card. Deletes fail closed instead — with nobody there to approve one, the call is blocked rather than executed.

10-Minute Timeout

Approval cards will not wait indefinitely. If an approval proposal is left unanswered for 10 minutes, traceroot automatically skips that pending action. No change from the unanswered proposal is applied; earlier approved actions in the same turn remain in effect.

Audit Logging

Writes executed by the agent are recorded on your workspace’s append-only audit trail:
  • Transport distinction: Audit rows created by the agent are marked with transport: "agent" (differentiating them from "public-api" or manual UI writes).
  • Session correlation: Each entry stores the agentSessionId, linking the modified resource to the agent conversation that authorized the change.
  • Persistence: Audit rows survive resource deletion, so administrators keep a historical record of who approved what change, when, and through which conversation.
The audit row is written after the resource change itself commits, and a failed audit write is logged rather than rolled back — so the trail is append-only but not a guarantee that every write has a row.

Where to start

GitHub Integration

Connect your repositories to enable source code access and PR creation.

BYOK

Use your own API keys to choose which model powers the agent.

Trace Analysis

Ask the agent questions about your traces in natural language.

Root Cause Analysis

Learn how the agent identifies the root cause of failures.