agtrace-sdk

The Observability Platform for AI Agents (Public SDK)

agtrace-sdk provides a high-level, stable API for building observability tools on top of agtrace. It abstracts away the internal complexity of providers, indexing, and runtime orchestration, exposing only the essential primitives for monitoring and analyzing AI agent behavior.

Features

• Universal Normalization: Works with multiple AI agent providers (Claude, Codex, Gemini)
• Real-time Monitoring: Watch for live events as agents interact
• Session Analysis: Analyze agent sessions with built-in diagnostic lenses
• Clean API: Simple, type-safe interface for common observability tasks

Architecture

This SDK acts as a facade over:

• agtrace-types: Core domain models (AgentEvent, etc.)
• agtrace-providers: Multi-provider log normalization
• agtrace-engine: Session analysis and diagnostics
• agtrace-index: Metadata storage and querying
• agtrace-runtime: Internal orchestration layer

Stability Guarantee

• agtrace-sdk: Semantic Versioning (SemVer) strictly followed. Public API is stable.
• Internal crates (agtrace-runtime, agtrace-engine, etc.): Internal APIs, subject to breaking changes without notice.

If you're building tools on top of agtrace, use only the agtrace-sdk crate to ensure stability across updates.

Installation

Add this to your Cargo.toml:

[dependencies]
agtrace-sdk = "0.1.13"

Usage

Client-based API (Recommended)

For most use cases, use the Client-based API which provides stateful operations:

use agtrace_sdk::{Client, Lens};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Connect to the workspace
    let client = Client::connect("~/.agtrace")?;

    // 2. Get a specific session
    let session_handle = client.sessions().get("session_id_123")?;

    // 3. Analyze the session
    let report = session_handle.analyze()?
        .through(Lens::Failures)
        .through(Lens::Loops)
        .through(Lens::Bottlenecks)
        .report()?;

    println!("Health score: {}", report.score);
    for insight in &report.insights {
        println!("  Turn {}: {:?} - {}",
            insight.turn_index + 1,
            insight.severity,
            insight.message);
    }

    Ok(())
}

Standalone API (for testing/simulations)

For scenarios where you don't need a Client (testing, simulations, custom pipelines):

use agtrace_sdk::{SessionHandle, types::AgentEvent};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // When you have raw events without Client
    let events: Vec<AgentEvent> = vec![/* ... */];
    let handle = SessionHandle::from_events(events);

    let session = handle.assemble()?;
    println!("Session has {} turns", session.turns.len());

    Ok(())
}

Real-time Monitoring

use agtrace_sdk::Client;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect("~/.agtrace")?;

    // Watch for live events from all providers
    let stream = client.watch().all_providers().start()?;

    // Use the Iterator trait for ergonomic event processing
    for event in stream {
        println!("New event: {:?}", event);
    }

    Ok(())
}

Provider-specific Monitoring

use agtrace_sdk::Client;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect("~/.agtrace")?;

    // Watch only Claude events
    let stream = client
        .watch()
        .provider("claude")
        .start()?;

    for event in stream {
        println!("Claude event: {:?}", event);
    }

    Ok(())
}

Diagnostic Lenses

The SDK provides several built-in lenses for analyzing agent behavior:

• Failures: Detects tool execution failures
• Loops: Detects repetitive patterns that might indicate infinite loops
• Bottlenecks: Identifies slow tool executions (>10 seconds)

Use Cases

Building a Monitoring Dashboard

use agtrace_sdk::{Client, Lens};

fn check_session_health(session_id: &str) -> Result<u8, Box<dyn std::error::Error>> {
    let client = Client::connect("~/.agtrace")?;
    let session_handle = client.sessions().get(session_id)?;

    let report = session_handle.analyze()?
        .through(Lens::Failures)
        .through(Lens::Loops)
        .report()?;

    Ok(report.score)
}

Dead Man's Switch (vital-checker)

use agtrace_sdk::Client;
use std::time::{Duration, Instant};

fn monitor_activity() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect("~/.agtrace")?;
    let stream = client.watch().all_providers().start()?;

    let mut last_activity = Instant::now();
    let timeout = Duration::from_secs(180); // 3 minutes

    loop {
        if let Some(_event) = stream.try_next() {
            last_activity = Instant::now();
        }

        if last_activity.elapsed() > timeout {
            println!("WARNING: No agent activity for 3 minutes!");
            // Send alert...
        }

        std::thread::sleep(Duration::from_secs(1));
    }
}

API Reference

Client-based API (Recommended)

The primary way to interact with agtrace is through the Client-based API, which manages state (database connections, configuration) for you.

Client

• Client::connect(path): Connect to an agtrace workspace
• .sessions(): Access session operations
• .watch(): Create a watch builder for real-time monitoring
• .projects(): Access project operations
• .insights(): Access insights/analysis operations
• .system(): Access system operations

SessionClient

• .list(filter): List sessions with optional filtering
• .get(id): Get a handle to a specific session

SessionHandle

• SessionHandle::from_events(events): Create a handle from raw events (standalone use)
• .events(): Get all normalized events for the session
• .assemble(): Assemble events into a structured session
• .summarize(): Get a summary of the session
• .analyze(): Analyze session with diagnostic lenses
• .export(strategy): Export session with specified strategy

WatchBuilder

• .provider(name): Filter events by provider
• .all_providers(): Watch all configured providers
• .start(): Start monitoring and return a live stream

LiveStream

Implements the Iterator trait for ergonomic event processing.

• .next_blocking(): Block until next event arrives
• .try_next(): Try to get next event without blocking

SessionAnalyzer

Created by calling session_handle.analyze():

• .through(lens): Apply a diagnostic lens
• .report(): Generate analysis report

Low-level Utilities (Power User API)

For advanced use cases like building custom TUIs or implementing custom event processing logic, the SDK exposes stateless utility functions through the utils module.

Event Processing

• utils::extract_state_updates(&event): Extract state changes (tokens, turns, model) from a single event

Example:

use agtrace_sdk::{Client, utils};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect("~/.agtrace")?;
    let stream = client.watch().all_providers().start()?;

    for event in stream.take(10) {
        let updates = utils::extract_state_updates(&event);
        if updates.is_new_turn {
            println!("New turn started!");
        }
        if let Some(usage) = updates.usage {
            println!("Token usage: {:?}", usage);
        }
    }
    Ok(())
}

Project Management

• utils::discover_project_root(explicit_root): Discover project root from flag/env/cwd
• utils::project_hash_from_root(path): Compute canonical project hash
• utils::resolve_effective_project_hash(hash, all_flag): Resolve project scope for commands

Example:

use agtrace_sdk::utils;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let project_root = utils::discover_project_root(None)?;
    let hash = utils::project_hash_from_root(&project_root.to_string_lossy());
    println!("Project hash: {}", hash);
    Ok(())
}

Contributing

Contributions are welcome! Please see the main agtrace repository for contribution guidelines.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.