adk_realtime/lib.rs
1//! # adk-realtime
2//!
3//! Real-time bidirectional audio/video streaming for ADK agents.
4//!
5//! This crate provides a unified interface for building voice-enabled AI agents
6//! using real-time streaming APIs from various providers (OpenAI, Gemini, etc.).
7//!
8//! ## Architecture
9//!
10//! `adk-realtime` follows the same pattern as OpenAI's Agents SDK, providing both
11//! a low-level session interface and a high-level `RealtimeAgent` that implements
12//! the standard ADK `Agent` trait.
13//!
14//! ```text
15//! ┌─────────────────────────────────────────┐
16//! │ Agent Trait │
17//! │ (name, description, run, sub_agents) │
18//! └────────────────┬────────────────────────┘
19//! │
20//! ┌───────────────────────┼───────────────────────┐
21//! │ │ │
22//! ┌────────▼────────┐ ┌─────────▼─────────┐ ┌─────────▼─────────┐
23//! │ LlmAgent │ │ RealtimeAgent │ │ SequentialAgent │
24//! │ (text-based) │ │ (voice-based) │ │ (workflow) │
25//! └─────────────────┘ └───────────────────┘ └───────────────────┘
26//! ```
27//!
28//! ## Features
29//!
30//! - **RealtimeAgent**: Implements `adk_core::Agent` with callbacks, tools, instructions
31//! - **Multiple Providers**: OpenAI Realtime API and Gemini Live API support
32//! - **Audio Streaming**: Bidirectional audio with various formats (PCM16, G711)
33//! - **Voice Activity Detection**: Server-side VAD for natural conversations
34//! - **Tool Calling**: Real-time function execution during voice sessions
35//!
36//! ## Example - Using RealtimeAgent (Recommended)
37//!
38//! ```rust,ignore
39//! use adk_realtime::{RealtimeAgent, openai::OpenAIRealtimeModel};
40//! use adk_runner::Runner;
41//!
42//! #[tokio::main]
43//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
44//! let model = OpenAIRealtimeModel::new(api_key, "gpt-4o-realtime-preview-2024-12-17");
45//!
46//! let agent = RealtimeAgent::builder("voice_assistant")
47//! .model(Arc::new(model))
48//! .instruction("You are a helpful voice assistant.")
49//! .voice("alloy")
50//! .server_vad()
51//! .tool(Arc::new(weather_tool))
52//! .build()?;
53//!
54//! // Use with standard ADK runner
55//! let runner = Runner::new(Arc::new(agent));
56//! runner.run(session, content).await?;
57//!
58//! Ok(())
59//! }
60//! ```
61//!
62//! ## Example - Using Low-Level Session API
63//!
64//! ```rust,ignore
65//! use adk_realtime::{RealtimeModel, RealtimeConfig, ServerEvent};
66//! use adk_realtime::openai::OpenAIRealtimeModel;
67//!
68//! let model = OpenAIRealtimeModel::new(api_key, "gpt-4o-realtime-preview-2024-12-17");
69//! let session = model.connect(config).await?;
70//!
71//! while let Some(event) = session.next_event().await {
72//! match event? {
73//! ServerEvent::AudioDelta { delta, .. } => { /* play audio */ }
74//! ServerEvent::TextDelta { delta, .. } => println!("{}", delta),
75//! _ => {}
76//! }
77//! }
78//! ```
79
80pub mod agent;
81pub mod audio;
82pub mod config;
83pub mod error;
84pub mod events;
85pub mod model;
86pub mod runner;
87pub mod session;
88
89// Provider implementations
90#[cfg(feature = "openai")]
91pub mod openai;
92
93#[cfg(feature = "gemini")]
94pub mod gemini;
95
96#[cfg(feature = "livekit")]
97pub mod livekit;
98
99// Re-exports
100pub use agent::{RealtimeAgent, RealtimeAgentBuilder};
101pub use audio::{AudioEncoding, AudioFormat};
102pub use config::{RealtimeConfig, RealtimeConfigBuilder, VadConfig, VadMode};
103pub use error::{RealtimeError, Result};
104pub use events::{ClientEvent, ServerEvent, ToolCall, ToolResponse};
105pub use model::{BoxedModel, RealtimeModel};
106pub use runner::RealtimeRunner;
107pub use session::{BoxedSession, RealtimeSession, RealtimeSessionExt};