Crate gemini_adk_rs

Expand description

§gemini-adk-rs

The agent runtime for Gemini Live — layer 1 of a three-crate stack. Below it, gemini_genai_rs speaks the wire protocol. Above it, gemini-adk-fluent-rs wraps this crate in the builder API most applications should start from. Come here when you are building a custom processor, a tool backend, a persistence layer, or an evaluation harness — or when you want to see what the fluent builder actually assembles.

§What lives here

Concern	Start at
A Live session and its three-lane processor	`live::LiveSessionBuilder`, `live::LiveHandle`
Tools the model can call	`tool::ToolFunction`, `tool::SimpleTool`, `tool::TypedTool`, `tool::ToolDispatcher`
Concurrent typed state with prefix scopes	`state::State`, `state::StateKey`
Text agents and combinators	`text::LlmTextAgent` and the `*TextAgent` family in `text`
Declarative conversation phases	`live::PhaseMachine`, `live::Phase`
Governed flows enforced while the model speaks	`flow::Flow`, `flow::FlowMonitor`
Turn extraction, watchers, temporal patterns	`live::TurnExtractor`, `live::watcher`, `live::temporal`
Session persistence and telemetry	`live::persistence`, `live::SessionTelemetry`

Anything behind a Cargo feature is marked on its page — vertex-ai-sessions, database-sessions, templates, otel, and the rest — and the full list is in this crate’s Cargo.toml.

§The shape of the runtime

Every Live session runs one router and two lanes. The fast lane is synchronous and handles audio, text deltas and transcripts in under a millisecond per event; the control lane is async and runs tool calls, phase transitions, extractors and watchers. A third, independent telemetry lane observes both. The callback you register decides which lane it runs on, and the rule is written once at the top of live::callbacks.

§A first taste

state::State is the piece every layer shares — tools write it, guards read it, extractors fill it — so it is the smallest thing worth showing on its own:

use gemini_adk_rs::state::{State, StateKey};

const TURNS: StateKey<u32> = StateKey::new("session:turn_count");

let state = State::new();
state.set("user:name", "Alice");
state.modify("session:turn_count", 0u32, |n| n + 1);

assert_eq!(state.get::<String>("user:name").as_deref(), Some("Alice"));
assert_eq!(state.get_key(&TURNS), Some(1));

For a running session, see the examples/ directory of the repository or the Live::builder() walkthrough in the fluent crate’s documentation.

Re-exports§

pub use a2a::A2aMessage;
pub use a2a::A2aPart;
pub use a2a::to_a2a_message;
pub use a2a::to_a2a_parts;
pub use a2a::to_adk_event;
pub use a2a::to_genai_parts;
pub use agent::Agent;
pub use agent_tool::AgentTool;
pub use agents::LoopAgent;
pub use agents::ParallelAgent;
pub use agents::SequentialAgent;
pub use artifacts::GcsArtifactService;
pub use artifacts::Artifact;
pub use artifacts::ArtifactService;
pub use artifacts::FileArtifactService;
pub use artifacts::InMemoryArtifactService;
pub use auth::AuthConfig;
pub use auth::AuthHandler;
pub use auth::AuthScheme;
pub use auth::CredentialExchanger;
pub use auth::CredentialExchangerRegistry;
pub use auth::OAuthGrantType;
pub use code_executors::BuiltInCodeExecutor;
pub use code_executors::CodeExecutionInput;
pub use code_executors::CodeExecutionResult;
pub use code_executors::CodeExecutor;
pub use code_executors::CodeFile;
pub use confirmation::ConfirmationProvider;
pub use confirmation::ConfirmationRequest;
pub use confirmation::StaticConfirmation;
pub use confirmation::ToolConfirmation;
pub use context::AgentEvent;
pub use context::CallbackContext;
pub use context::InvocationContext;
pub use context::ToolContext;
pub use credentials::AuthCredential;
pub use credentials::CredentialError;
pub use credentials::CredentialService;
pub use credentials::InMemoryCredentialService;
pub use error::AgentError;
pub use error::AgentResult;
pub use error::ConfigError;
pub use error::ToolError;
pub use events::Event;
pub use events::EventActions;
pub use events::EventType;
pub use events::StructuredEvent;
pub use extract::Extract;
pub use extract::Recognizer;
pub use extract::RecordExtractor;
pub use flow::CompiledFlow;
pub use flow::Enforcement;
pub use flow::Flow;
pub use flow::FlowError;
pub use flow::FlowErrors;
pub use flow::FlowExplanation;
pub use flow::FlowMonitor;
pub use flow::Guard;
pub use flow::SharedFlowMonitor;
pub use flow::StepAction;
pub use flow::ToolSurface;
pub use flow::Verdict;
pub use flow::Violation;
pub use flow::on_enter;
pub use frame::ConfirmPolicy;
pub use frame::Frame;
pub use frame::FrameSpec;
pub use frame::SlotRecognizer;
pub use frame::SlotSpec;
pub use frame::SlotValidator;
pub use instruction::inject_session_state;
pub use live::EventCallbacks;
pub use live::ExecutionMode;
pub use live::LiveHandle;
pub use live::LiveSessionBuilder;
pub use live::LlmExtractor;
pub use live::PersistenceError;
pub use live::SessionHook;
pub use live::ToolCallSummary;
pub use live::TranscriptBuffer;
pub use live::TranscriptTurn;
pub use live::TurnExtractor;
pub use llm::BaseLlm;
pub use llm::GeminiLlm;
pub use llm::GeminiLlmParams;
pub use llm::LlmRegistry;
pub use llm::LlmRequest;
pub use llm::LlmResponse;
pub use llm_agent::LlmAgent;
pub use llm_agent::LlmAgentBuilder;
pub use memory::InMemoryMemoryService;
pub use memory::MemoryEntry;
pub use memory::MemoryService;
pub use middleware::Middleware;
pub use middleware::MiddlewareChain;
pub use orchestration::AgentMode;
pub use orchestration::Resolver;
pub use orchestration::call_agent;
pub use orchestration::provenance;
pub use plugin::Plugin;
pub use plugin::PluginManager;
pub use plugin::PluginResult;
pub use processors::ContentFilter;
pub use processors::InstructionInserter;
pub use processors::RequestProcessor;
pub use processors::RequestProcessorChain;
pub use processors::ResponseProcessor;
pub use processors::ResponseProcessorChain;
pub use router::AgentRegistry;
pub use run_config::RunConfig;
pub use run_config::StreamingMode;
pub use runner::Runner;
pub use session::DatabaseSessionService;
pub use session::InMemorySessionService;
pub use session::Session;
pub use session::SessionId;
pub use session::SessionService;
pub use session::db_schema;
pub use state::FileJournalSink;
pub use state::JournalSink;
pub use state::MemoryJournalSink;
pub use state::PrefixedState;
pub use state::ReadOnlyPrefixedState;
pub use state::StateError;
pub use state::SlotEvidence;
pub use state::State;
pub use state::StateMutation;
pub use state::StateMutationOrigin;
pub use text::DispatchTextAgent;
pub use text::FallbackTextAgent;
pub use text::FnTextAgent;
pub use text::JoinTextAgent;
pub use text::LlmTextAgent;
pub use text::LoopTextAgent;
pub use text::MapOverTextAgent;
pub use text::ParallelTextAgent;
pub use text::RaceTextAgent;
pub use text::RouteRule;
pub use text::RouteTextAgent;
pub use text::SequentialTextAgent;
pub use text::TapTextAgent;
pub use text::TaskRegistry;
pub use text::TextAgent;
pub use text::TimeoutTextAgent;
pub use text_agent_tool::TextAgentTool;
pub use text_runner::RunEvent;
pub use text_runner::TextRunner;
pub use tool::SimpleTool;
pub use tool::ToolDispatcher;
pub use tool::ToolFunction;
pub use tool::ToolPolicy;
pub use tool::TypedTool;
pub use tools::GoogleSearchTool;
pub use tools::long_running::LongRunningFunctionTool;
pub use tools::mcp::McpConnectionParams;
pub use tools::mcp::McpTool;
pub use tools::mcp::McpToolset;
pub use toolset::StaticToolset;
pub use toolset::Toolset;
pub use utils::model_name::extract_model_name;
pub use utils::model_name::is_gemini_model;
pub use utils::model_name::is_gemini2_or_above;
pub use utils::variant::GoogleLlmVariant;
pub use utils::variant::get_google_llm_variant;
pub use a2a::AgentCard;
pub use a2a::AgentSkill;
pub use a2a::RemoteA2aAgent;
pub use a2a::RemoteA2aAgentConfig;
pub use evaluation::EvalCase;
pub use evaluation::EvalMetric;
pub use evaluation::EvalResult;
pub use evaluation::EvalSet;
pub use evaluation::Evaluator;
pub use evaluation::Invocation;
pub use evaluation::LlmAsJudge;
pub use evaluation::PerInvocationResult;
pub use evaluation::ResponseEvaluator;
pub use evaluation::TrajectoryEvaluator;
pub use planners::BuiltInPlanner;
pub use planners::PlanReActPlanner;
pub use planners::Planner;
pub use planners::PlannerError;
pub use optimization::AgentOptimizer;
pub use optimization::EvalSample;
pub use optimization::OptimizerError;
pub use optimization::OptimizerResult;
pub use optimization::Sampler;
pub use optimization::SimplePromptOptimizer;
pub use optimization::SimplePromptOptimizerConfig;
pub use code_executors::ContainerCodeExecutor;
pub use code_executors::ContainerCodeExecutorConfig;
pub use code_executors::UnsafeLocalCodeExecutor;
pub use code_executors::VertexAiCodeExecutor;
pub use code_executors::VertexAiCodeExecutorConfig;
pub use plugin::ContextFilterPlugin;
pub use plugin::GlobalInstructionPlugin;
pub use plugin::ReflectRetryToolPlugin;
pub use memory::VertexAiMemoryBankConfig;
pub use memory::VertexAiMemoryBankService;
pub use memory::VertexAiRagMemoryConfig;
pub use memory::VertexAiRagMemoryService;
pub use session::PostgresSessionConfig;
pub use session::PostgresSessionService;
pub use session::SqliteSessionConfig;
pub use session::SqliteSessionService;
pub use session::VertexAiSessionConfig;
pub use session::VertexAiSessionService;
pub use tools::retrieval::BaseRetrievalTool;
pub use tools::retrieval::FilesRetrievalTool;
pub use tools::retrieval::RetrievalResult;
pub use tools::retrieval::VertexAiRagConfig;
pub use tools::retrieval::VertexAiRagRetrievalTool;
pub use tools::BashToolPolicy;
pub use tools::DiscoveryEngineSearchTool;
pub use tools::Example;
pub use tools::ExampleTool;
pub use tools::ExecuteBashTool;
pub use tools::ExitLoopTool;
pub use tools::GetUserChoiceTool;
pub use tools::LoadMemoryTool;
pub use tools::PreloadMemoryTool;
pub use tools::TransferToAgentTool;
pub use tools::UrlContextTool;
pub use tools::VertexAiSearchConfig;
pub use tools::VertexAiSearchTool;
pub use agent_config::AgentConfig;
pub use agent_config::AgentConfigError;
pub use agent_config::ToolConfig as AgentToolConfig;
pub use agent_config::discover_agent_configs;
pub use gemini_genai_rs;

Modules§

a2a: Agent-to-Agent (A2A) protocol types and converters.
agent: The core Agent trait.
agent_config: YAML/TOML agent configuration — define agents without code.
agent_session: AgentSession — intercepting wrapper around SessionHandle.
agent_tool: AgentTool — wraps an Agent as a ToolFunction for “agent as a tool” dispatch.
agents: Agent composition primitives — Sequential, Parallel, Loop.
artifacts: Artifact service — versioned binary/JSON artifact storage.
auth: Auth module — credential types, security schemes, and auth configuration.
code_executors: Code execution infrastructure — sandboxed code execution for agents.
confirmation: Tool confirmation — user confirmation for sensitive tool calls.
context: InvocationContext — the session state container flowing through agent execution.
credentials: Credential service — secure storage and retrieval of auth credentials.
error: Error types for the agent runtime.
evaluation: Evaluation framework — evaluate agent quality using various metrics.
events: Event system — structured events for agent invocations.
expr: Expr — a closed, serializable expression vocabulary over session state.
extract: The extraction kit — Extract records with deterministic recognizers.
flow: Flow — a governed conversation/tool DAG.
frame: Frames & slots — typed, first-class fields for conversation authoring.
instruction: Instruction templating — inject state values into instruction strings.
live: Live session management — callback-driven full-duplex event handling.
llm: LLM abstraction — decouples agents from specific model providers.
llm_agent: LlmAgent — concrete Agent implementation with builder pattern.
memory: Memory service — session-scoped memory for agents.
middleware: Middleware trait and chain — wraps agent execution at lifecycle points.
optimization: Agent optimization framework — iteratively improve agent prompts.
orchestration: Agent orchestration — invoke an agent in a AgentMode.
planners: Planner system — enables agents to generate plans before acting.
plugin: Plugin system — lifecycle hooks with control-flow capabilities.
primitives: The L1 contract — the conversation runtime
processors: Request/response processors — middleware for LLM request pipelines.
router: Agent registry and transfer routing.
run_config: RunConfig — configuration for agent execution runs.
runner: Runner — orchestrates agent execution across Gemini Live sessions.
session: Session persistence — multi-session, multi-turn CRUD.
skills: Skill registry — centralized publish/discover for agent capabilities, the ADK skills-registry pattern.
state: Typed key-value state container for agents.
telemetry: Agent-level observability — OpenTelemetry tracing, structured logging, Prometheus metrics.
text: Text-based agent execution — request/response LLM pipelines.
text_agent_tool: TextAgentTool — wraps a TextAgent as a ToolFunction for voice orchestration.
text_runner: TextRunner — runs TextAgents with session management and services.
tool: Tool dispatch — regular, streaming, and input-streaming tools.
tools: Built-in tools — server-side tools, callable tools, and retrieval tools.
toolset: Toolset trait — collections of tools that can be enumerated and filtered.
utils: Utility helpers for model name parsing and platform variant detection.
workflow: Workflow graph runtime — the ADK 2.0 “graph execution” pattern.

Type Aliases§

AsyncSourceFn: An async source of a JSON value — the seam for a tool call, an HTTP fetch, an MCP request, or a workflow function node. In is what the source is bound from: the whole State by default, or a pre-bound args Value for extraction-kit field resolvers.
BoxFuture: A boxed, sendable, 'static future — the return type of every async callback and hook in the runtime.
StatePredicate: A synchronous predicate over shared State: true admits (a phase transition, a workflow node, a guard).

Attribute Macros§

tool: The #[tool] attribute macro — turns an async fn into a registrable Gemini tool.

Derive Macros§

Extract: The #[derive(Extract)] macro — builds an extract::Extract record from a struct’s #[recognize(..)] fields. Shares the name Extract with the struct (macro vs type namespace), so both can be imported together.
Frame: Derive macro that generates a frame::Frame impl from a struct’s #[slot(..)] fields. Shares the name Frame with the trait (macro vs type namespace), so both can be imported together. Derive a Frame impl from a struct’s #[slot(..)] fields.