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