agtrace-sdk 0.2.1

Public SDK for building observability tools on top of agtrace
Documentation

agtrace-sdk

Installation

Add this to your Cargo.toml:

[dependencies]
agtrace-sdk = "0.2"

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

Contributing

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

License

Licensed under either of:

at your option.