Crate agtrace_sdk

Crate agtrace_sdk 

Source
Expand description

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 handle = client.sessions().get("session_id_123")?;
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::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