Crate agtrace_sdk 

agtrace-sdk: The Observability Platform for AI Agents.

Overview

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.

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

Usage

use agtrace_sdk::{Client, Lens};

// 1. Connect to the workspace
let client = Client::connect("~/.agtrace")?;

// 2. Watch for live events (Real-time monitoring)
let stream = client.watch().all_providers().start()?;
for event in stream.take(10) {
    println!("New event: {:?}", event);
}

// 3. Analyze a specific session (Diagnosis)
let events = client.session("session_id_123").events()?;
if let Some(session) = agtrace_sdk::assemble_session(&events) {
    let report = agtrace_sdk::analyze_session(session)
        .through(Lens::Failures)
        .through(Lens::Loops)
        .report()?;

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

Re-exports

pub use analysis::AnalysisReport;

pub use analysis::Insight;

pub use analysis::Lens;

pub use analysis::Severity;

pub use client::Client;

pub use client::SessionHandle;

pub use error::Error;

pub use error::Result;

pub use watch::LiveStream;

pub use watch::WatchBuilder;

Modules

analysis

client

error

watch

Structs

AgentEvent

Agent event Maps 1:1 to database table row

AgentSession

SessionSummary

Enums

ToolKind

Tool classification by semantic purpose

Functions

analyze_session

assemble_session

summarize