Skip to main content

gemini_adk/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![forbid(unsafe_code)]
3//! Build Gemini agents in Rust, from one crate.
4//!
5//! ```toml
6//! [dependencies]
7//! gemini-adk = "3"
8//! tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
9//! ```
10//!
11//! Each step below adds one idea to the one before.
12//!
13//! **Ask.** A model from the environment (`GEMINI_API_KEY`, or Vertex AI via
14//! `GOOGLE_GENAI_USE_VERTEXAI` and `GOOGLE_CLOUD_PROJECT`), an agent, a
15//! question:
16//!
17//! ```no_run
18//! use gemini_adk::prelude::*;
19//!
20//! # async fn run() -> Result<(), AgentError> {
21//! let agent = AgentBuilder::new("assistant")
22//!     .instruction("Answer in one sentence.")
23//!     .build(GeminiLlm::from_env()?)?;
24//!
25//! println!("{}", agent.ask("What is the Gemini Live API?").await?);
26//! # Ok(()) }
27//! ```
28//!
29//! **Get a typed answer.** The type is the schema. Typed answers and tool
30//! argument types derive `serde::Deserialize` and `schemars::JsonSchema`, so
31//! add `serde = { version = "1", features = ["derive"] }` and
32//! `schemars = "0.8"` to use them.
33//!
34//! ```no_run
35//! # use gemini_adk::prelude::*;
36//! #[derive(serde::Deserialize, schemars::JsonSchema)]
37//! struct City {
38//!     name: String,
39//!     country: String,
40//! }
41//!
42//! # async fn run(agent: impl TextAgent) -> Result<(), AgentError> {
43//! let city: City = agent.ask_as("Which city hosts the Louvre?").await?;
44//! # Ok(()) }
45//! ```
46//!
47//! **Hold a conversation, and stream it.**
48//!
49//! ```no_run
50//! # use gemini_adk::prelude::*;
51//! # async fn run(agent: impl TextAgent) -> Result<(), AgentError> {
52//! let mut chat = agent.chat();
53//! chat.send("Hi, I'm Ada.").await?;
54//! let mut reply = chat.send_stream("What's my name?");
55//! while let Some(event) = reply.next().await {
56//!     if let RunEvent::TextDelta(text) = event? {
57//!         print!("{text}");
58//!     }
59//! }
60//! # Ok(()) }
61//! ```
62//!
63//! **Give it a tool.** A documented `async fn` is a tool; the doc comment is
64//! what the model reads:
65//!
66//! ```no_run
67//! # use gemini_adk::prelude::*;
68//! /// Get the current temperature for a city, in Celsius.
69//! ///
70//! /// # Arguments
71//! ///
72//! /// * `city` - The city name, e.g. "Paris".
73//! #[tool]
74//! async fn temperature(city: String) -> f64 {
75//!     # let _ = city;
76//!     21.5
77//! }
78//!
79//! # fn run() -> Result<(), AgentError> {
80//! let agent = AgentBuilder::new("weather")
81//!     .tool(temperature())
82//!     .build(GeminiLlm::from_env()?)?;
83//! # Ok(()) }
84//! ```
85//!
86//! **Test it without a model.** [`testing::MockLlm`] replies from a script
87//! and records what the agent sent.
88//!
89//! From there: live voice sessions ([`live`], `Live::builder()`), governed
90//! conversations that enforce which tools a step admits ([`conversation`],
91//! [`flow`]), and model-free conversation tests ([`simulation`]).
92//!
93//! **One error type.** Every SDK error converts into [`Error`], so a function
94//! that compiles a conversation, calls a model and reads a file can return
95//! [`gemini_adk::Result`](Result) and use `?` throughout.
96//!
97//! This crate re-exports [`gemini-adk-fluent-rs`](gemini_adk_fluent_rs); its
98//! features have the same names here, plus `memory`, which adds
99//! `gemini_adk::memory` (contextual memory for Live sessions).
100
101#[doc(inline)]
102pub use gemini_adk_fluent_rs::*;
103
104mod error;
105pub use error::{Error, Result};
106
107/// Everything most applications import: the fluent prelude, plus the
108/// facade's [`Error`], which every SDK error converts into.
109pub mod prelude {
110    #[doc(inline)]
111    pub use gemini_adk_fluent_rs::prelude::*;
112
113    pub use crate::Error;
114}
115
116/// Contextual memory for Live sessions (feature `memory`).
117#[cfg(feature = "memory")]
118#[doc(inline)]
119pub use gemini_memory_rs as memory;