Crate agtrace_sdk 

agtrace-sdk: The Observability Platform for AI Agents.

Note: README.md is auto-generated from this rustdoc using cargo-rdme. To update: cargo rdme --workspace-project agtrace-sdk

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.

Quickstart

use agtrace_sdk::{Client, Lens, types::SessionFilter};

// Connect to the local workspace (uses XDG data directory)
let client = Client::connect_default().await?;

// List sessions and analyze the most recent one
let sessions = client.sessions().list(SessionFilter::all())?;
if let Some(summary) = sessions.first() {
    let handle = client.sessions().get(&summary.id)?;
    let report = handle.analyze()?
        .through(Lens::Failures)
        .report()?;
    println!("Health: {}/100", report.score);
}

For complete examples, see the examples/ directory.

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 Patterns

Real-time Monitoring

use agtrace_sdk::Client;
use futures::stream::StreamExt;

let client = Client::connect_default().await?;
let mut stream = client.watch().all_providers().start()?;
let mut count = 0;
while let Some(event) = stream.next().await {
    println!("New event: {:?}", event);
    count += 1;
    if count >= 10 { break; }
}

Session Analysis

use agtrace_sdk::{Client, Lens, types::SessionFilter};

let client = Client::connect_default().await?;
let sessions = client.sessions().list(SessionFilter::all())?;
if let Some(summary) = sessions.first() {
    let handle = client.sessions().get(&summary.id)?;
    let report = handle.analyze()?
        .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);
    }
}

Standalone API (for testing/simulations)

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

// When you have raw events without Client (e.g., testing, simulations)
let events: Vec<AgentEvent> = vec![/* ... */];
let handle = SessionHandle::from_events(events);

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

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::ClientBuilder;

pub use client::InsightClient;

pub use client::ProjectClient;

pub use client::SessionClient;

pub use client::SessionHandle;

pub use client::SystemClient;

pub use client::WatchClient;

pub use error::Error;

pub use error::Result;

pub use watch::LiveStream;

pub use watch::WatchBuilder;

Modules

analysis

client

error

types

Type re-exports for the SDK.

utils

Utility functions for building custom observability tools.

watch

Structs

AgentEvent

Agent event Maps 1:1 to database table row

AgentSession

SessionFilter

SessionSummary

Enums

EventPayload

Event payload variants

ExportStrategy

StreamId

Stream identifier for multi-stream sessions Enables parallel conversation streams within same session (e.g., background reasoning, subagents)

ToolKind

Tool classification by semantic purpose