agtrace_sdk/
lib.rs

1//! agtrace-sdk: The Observability Platform for AI Agents.
2//!
3//! # Overview
4//!
5//! `agtrace-sdk` provides a high-level, stable API for building observability
6//! tools on top of agtrace. It abstracts away the internal complexity of
7//! providers, indexing, and runtime orchestration, exposing only the essential
8//! primitives for monitoring and analyzing AI agent behavior.
9//!
10//! # Architecture
11//!
12//! This SDK acts as a facade over:
13//! - `agtrace-types`: Core domain models (AgentEvent, etc.)
14//! - `agtrace-providers`: Multi-provider log normalization
15//! - `agtrace-engine`: Session analysis and diagnostics
16//! - `agtrace-index`: Metadata storage and querying
17//! - `agtrace-runtime`: Internal orchestration layer
18//!
19//! # Usage
20//!
21//! ```no_run
22//! use agtrace_sdk::{Client, Lens};
23//!
24//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
25//! // 1. Connect to the workspace
26//! let client = Client::connect("~/.agtrace")?;
27//!
28//! // 2. Watch for live events (Real-time monitoring)
29//! let stream = client.watch().all_providers().start()?;
30//! for event in stream.take(10) {
31//!     println!("New event: {:?}", event);
32//! }
33//!
34//! // 3. Analyze a specific session (Diagnosis)
35//! let events = client.session("session_id_123").events()?;
36//! if let Some(session) = agtrace_sdk::assemble_session(&events) {
37//!     let report = agtrace_sdk::analyze_session(session)
38//!         .through(Lens::Failures)
39//!         .through(Lens::Loops)
40//!         .report()?;
41//!
42//!     println!("Health score: {}", report.score);
43//!     for insight in &report.insights {
44//!         println!("Turn {}: {:?} - {}",
45//!             insight.turn_index + 1,
46//!             insight.severity,
47//!             insight.message);
48//!     }
49//! }
50//! # Ok(())
51//! # }
52//! ```
53
54pub mod analysis;
55pub mod client;
56pub mod error;
57pub mod watch;
58
59// Re-export core domain types for convenience
60pub use agtrace_engine::session::summarize;
61pub use agtrace_engine::{AgentSession, assemble_session};
62pub use agtrace_index::SessionSummary;
63pub use agtrace_types::event::AgentEvent;
64pub use agtrace_types::tool::ToolKind;
65
66// Public facade
67pub use analysis::{AnalysisReport, Insight, Lens, Severity};
68pub use client::{Client, SessionHandle};
69pub use error::{Error, Result};
70pub use watch::{LiveStream, WatchBuilder};
71
72// Helper function for analysis
73pub fn analyze_session(session: AgentSession) -> analysis::SessionAnalyzer {
74    analysis::SessionAnalyzer::new(session)
75}