adk_core/
lib.rs

1//! # adk-core
2//!
3//! Core traits and types for ADK agents, tools, sessions, and events.
4#![allow(clippy::result_large_err)]
5//!
6//! ## Overview
7//!
8//! This crate provides the foundational abstractions for the Agent Development Kit:
9//!
10//! - [`Agent`] - The fundamental trait for all agents
11//! - [`Tool`] / [`Toolset`] - For extending agents with custom capabilities
12//! - [`Session`] / [`State`] - For managing conversation context
13//! - [`Event`] - For streaming agent responses
14//! - [`AdkError`] / [`Result`] - Unified error handling
15//! - [`SharedState`] / [`SharedStateError`] - Thread-safe key-value store for parallel agent coordination
16//! - [`ToolConfirmationPolicy`] / [`ToolConfirmationRequest`] - Human-in-the-loop tool authorization
17//!
18//! ## What's New in 0.6.0
19//!
20//! - **`SharedState`**: Concurrent key-value store with `set_shared`, `get_shared`, and
21//!   `wait_for_key` (timeout-based blocking) for cross-agent coordination in `ParallelAgent`.
22//! - **`shared_state()` on `CallbackContext`**: Default method returning `None` — tools and
23//!   callbacks can access `SharedState` when running inside a `ParallelAgent` with shared state enabled.
24//! - **`ToolConfirmationPolicy`**: Built-in HITL mechanism — `Never`, `Always`, or `PerTool`
25//!   policies that pause execution and emit `ToolConfirmationRequest` events for user approval.
26//!
27//! ## Quick Start
28//!
29//! ```rust,no_run
30//! use adk_core::{Agent, Tool, Event, Result};
31//! use std::sync::Arc;
32//!
33//! // All agents implement the Agent trait
34//! // All tools implement the Tool trait
35//! // Events are streamed as the agent executes
36//! ```
37//!
38//! ## Core Traits
39//!
40//! ### Agent
41//!
42//! The [`Agent`] trait defines the interface for all agents:
43//!
44//! ```rust,ignore
45//! #[async_trait]
46//! pub trait Agent: Send + Sync {
47//!     fn name(&self) -> &str;
48//!     fn description(&self) -> Option<&str>;
49//!     async fn run(&self, ctx: Arc<dyn InvocationContext>) -> Result<EventStream>;
50//! }
51//! ```
52//!
53//! ### Tool
54//!
55//! The [`Tool`] trait defines custom capabilities:
56//!
57//! ```rust,ignore
58//! #[async_trait]
59//! pub trait Tool: Send + Sync {
60//!     fn name(&self) -> &str;
61//!     fn description(&self) -> &str;
62//!     async fn execute(&self, ctx: Arc<dyn ToolContext>, args: Value) -> Result<Value>;
63//! }
64//! ```
65//!
66//! ## State Management
67//!
68//! State uses typed prefixes for organization:
69//!
70//! - `user:` - User preferences (persists across sessions)
71//! - `app:` - Application state (application-wide)
72//! - `temp:` - Temporary data (cleared each turn)
73
74pub mod agent;
75pub mod agent_loader;
76pub mod callbacks;
77pub mod context;
78pub mod error;
79pub mod event;
80pub mod identity;
81pub mod instruction_template;
82pub mod model;
83pub mod request_context;
84pub mod shared_state;
85pub mod tool;
86pub mod types;
87
88pub use agent::{Agent, EventStream, ResolvedContext};
89pub use agent_loader::{AgentLoader, MultiAgentLoader, SingleAgentLoader};
90pub use callbacks::{
91    AfterAgentCallback, AfterModelCallback, AfterToolCallback, AfterToolCallbackFull,
92    BaseEventsSummarizer, BeforeAgentCallback, BeforeModelCallback, BeforeModelResult,
93    BeforeToolCallback, EventsCompactionConfig, GlobalInstructionProvider, InstructionProvider,
94    OnToolErrorCallback,
95};
96pub use context::{
97    Artifacts, CallbackContext, IncludeContents, InvocationContext, MAX_STATE_KEY_LEN, Memory,
98    MemoryEntry, ReadonlyContext, ReadonlyState, RunConfig, Session, State, StreamingMode,
99    ToolCallbackContext, ToolConfirmationDecision, ToolConfirmationPolicy, ToolConfirmationRequest,
100    ToolOutcome, validate_state_key,
101};
102pub use error::{AdkError, ErrorCategory, ErrorComponent, ErrorDetails, Result, RetryHint};
103pub use event::{
104    Event, EventActions, EventCompaction, KEY_PREFIX_APP, KEY_PREFIX_TEMP, KEY_PREFIX_USER,
105};
106pub use identity::{
107    AdkIdentity, AppName, ExecutionIdentity, IdentityError, InvocationId, SessionId, UserId,
108};
109pub use instruction_template::inject_session_state;
110pub use model::{
111    CacheCapable, CitationMetadata, CitationSource, ContextCacheConfig, FinishReason,
112    GenerateContentConfig, Llm, LlmRequest, LlmResponse, LlmResponseStream, UsageMetadata,
113};
114pub use request_context::RequestContext;
115pub use shared_state::{SharedState, SharedStateError};
116pub use tool::{
117    RetryBudget, Tool, ToolContext, ToolExecutionStrategy, ToolPredicate, ToolRegistry, Toolset,
118    ValidationMode,
119};
120pub use types::{
121    Content, FileDataPart, FunctionResponseData, InlineDataPart, MAX_INLINE_DATA_SIZE, Part,
122};
123
124// Re-export async_trait so the #[tool] macro's generated code can reference it
125// via adk_tool::async_trait (adk_tool re-exports from adk_core).
126pub use async_trait::async_trait;
127
128/// Enforces the explicit cryptographic provider process-wide.
129/// This bypasses any inert 'ring' code lingering in deep dependencies.
130///
131/// Because we lack a monolithic main() function, we use lazy evaluation
132/// to guarantee that aws-lc-rs is installed globally the millisecond
133/// an adk-rust consumer attempts to use the network.
134pub fn ensure_crypto_provider() {
135    #[cfg(feature = "rustls")]
136    {
137        static CRYPTO_INIT: std::sync::Once = std::sync::Once::new();
138        CRYPTO_INIT.call_once(|| {
139            // We ignore the Result. If the parent application has already
140            // deliberately installed a provider, we respect their sovereign choice.
141            let _ = rustls::crypto::aws_lc_rs::default_provider().install_default();
142        });
143    }
144}
adk_core/lib.rs

adk_core/
lib.rs
