Crate agtrace_sdk

Expand description

agtrace-sdk: SDK for AI agent observability.

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 tools on top of agtrace. It powers agtrace’s MCP server (letting agents query their execution history) and CLI tools, and can be embedded in your own applications. The SDK normalizes logs from multiple providers (Claude Code, Codex, Gemini) into a unified data model, enabling cross-provider analysis.

§Quickstart

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

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

// List sessions and browse 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 session = handle.assemble()?;

    println!("Session: {} turns, {} tokens",
        session.turns.len(),
        session.stats.total_tokens);

    // Browse tool calls
    for turn in &session.turns {
        for step in &turn.steps {
            for tool in &step.tools {
                println!("  {} ({})",
                    tool.call.content.name(),
                    if tool.is_error { "failed" } else { "ok" });
            }
        }
    }
}

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 assembly and analysis
agtrace-index: Metadata storage and querying
agtrace-runtime: Internal orchestration layer

§Usage Patterns

§Session Browsing

Access structured session data (Turn → Step → Tool hierarchy):

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

let client = Client::connect_default().await?;
let sessions = client.sessions().list(SessionFilter::all())?;

for summary in sessions.iter().take(5) {
    let handle = client.sessions().get(&summary.id)?;
    let session = handle.assemble()?;
    println!("{}: {} turns, {} tokens",
        summary.id,
        session.turns.len(),
        session.stats.total_tokens);
}

§Real-time Monitoring

Watch for events as they happen:

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

let client = Client::connect_default().await?;
let mut stream = client.watch().all_providers().start()?;
while let Some(event) = stream.next().await {
    println!("Event: {:?}", event);
}

§Diagnostics

Run diagnostic checks on sessions:

use agtrace_sdk::{Client, Diagnostic, 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()?
        .check(Diagnostic::Failures)
        .check(Diagnostic::Loops)
        .report()?;

    println!("Health: {}/100", report.score);
    for insight in &report.insights {
        println!("  Turn {}: {}", insight.turn_index + 1, 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::Diagnostic;
pub use analysis::Insight;
pub use analysis::Severity;
pub use client::ChildSessionInfo;
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 providers::Providers;
pub use providers::ProvidersBuilder;
pub use watch::LiveStream;
pub use watch::WatchBuilder;
pub use query::EventType;
pub use query::Provider;

Modules§

analysis
client
error
mcp: MCP (Model Context Protocol) server implementation.
providers: Lightweight provider operations without database.
query: Query types for session filtering and data retrieval.
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: Complete agent conversation session assembled from normalized events.
SessionFilter
SessionSummary: Lightweight session summary for list operations.

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