adk-core

Core traits and types for ADK-Rust agents, tools, sessions, and events.

Overview

adk-core provides the foundational abstractions for ADK-Rust. It defines the core traits and types that all other ADK crates build upon:

• Agent trait - The fundamental abstraction for all agents
• Tool / Toolset traits - For extending agents with custom capabilities
• Llm trait - For LLM provider integrations
• Context hierarchy - ReadonlyContext → CallbackContext → ToolContext/InvocationContext
• Content / Part - Message content structures
• Event system - For streaming agent responses
• Session / State - For managing conversation context
• Error types - Unified error handling

This crate is model-agnostic and contains no LLM-specific code.

Installation

[dependencies]
adk-core = "0.3"

Or use the meta-crate:

[dependencies]
adk-rust = "0.3"

Core Traits

Agent

#[async_trait]
pub trait Agent: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn sub_agents(&self) -> &[Arc<dyn Agent>];
    async fn run(&self, ctx: Arc<dyn InvocationContext>) -> Result<EventStream>;
}

Tool

#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> Option<Value>;
    fn is_long_running(&self) -> bool;
    async fn execute(&self, ctx: Arc<dyn ToolContext>, args: Value) -> Result<Value>;
}

Toolset

#[async_trait]
pub trait Toolset: Send + Sync {
    fn name(&self) -> &str;
    async fn tools(&self, ctx: Arc<dyn ReadonlyContext>) -> Result<Vec<Arc<dyn Tool>>>;
}

Llm

#[async_trait]
pub trait Llm: Send + Sync {
    fn name(&self) -> &str;
    async fn generate_content(&self, request: LlmRequest, stream: bool) -> Result<LlmResponseStream>;
}

Key Types

Content & Part

// Message content with role and parts
let content = Content::new("user")
    .with_text("Hello!")
    .with_inline_data("image/png", image_bytes)
    .with_file_uri("image/jpeg", "https://example.com/image.jpg");

// Part variants
enum Part {
    Text { text: String },
    InlineData { mime_type: String, data: Vec<u8> },  // Max 10MB (MAX_INLINE_DATA_SIZE)
    FileData { mime_type: String, file_uri: String },
    FunctionCall { name: String, args: Value, id: Option<String> },
    FunctionResponse { function_response: FunctionResponseData, id: Option<String> },
}

Event

// Events stream from agent execution
let event = Event::new("invocation_123");
event.content()  // Access response content
event.actions    // State changes, transfers, escalation

// Provider-specific metadata (replaces GCP-specific fields)
event.provider_metadata  // HashMap<String, String>

EventActions

pub struct EventActions {
    pub state_delta: HashMap<String, Value>,  // State updates
    pub artifact_delta: HashMap<String, i64>, // Artifact changes
    pub skip_summarization: bool,
    pub transfer_to_agent: Option<String>,    // Agent transfer
    pub escalate: bool,                       // Escalate to parent
    pub tool_confirmation: Option<ToolConfirmationRequest>,  // Pending tool confirmation
    pub tool_confirmation_decision: Option<ToolConfirmationDecision>,
    pub compaction: Option<EventCompaction>,  // Context compaction summary
}

EventCompaction

When context compaction is enabled, older events are summarized into a single compacted event:

pub struct EventCompaction {
    pub start_timestamp: DateTime<Utc>,   // Earliest compacted event
    pub end_timestamp: DateTime<Utc>,     // Latest compacted event
    pub compacted_content: Content,       // The summary replacing original events
}

See Context Compaction for usage details.

Context Hierarchy

ReadonlyContext (read-only access)
    ├── invocation_id, agent_name, user_id, app_name, session_id
    └── user_content()

CallbackContext (extends ReadonlyContext)
    └── artifacts()

ToolContext (extends CallbackContext)
    ├── function_call_id()
    ├── actions() / set_actions()
    └── search_memory()

InvocationContext (extends CallbackContext)
    ├── agent(), memory(), session()
    ├── run_config()
    └── end_invocation() / ended()

Security

Inline Data Size Limit

Content::with_inline_data() and Part::inline_data() enforce a 10 MB limit (MAX_INLINE_DATA_SIZE) to prevent oversized payloads.

State Key Validation

validate_state_key() rejects keys that are empty, exceed 256 bytes (MAX_STATE_KEY_LEN), contain path separators (/, \, ..), or null bytes.

use adk_core::context::validate_state_key;

assert!(validate_state_key("user_name").is_ok());
assert!(validate_state_key("../etc/passwd").is_err());

Provider Metadata

The Event struct uses a generic provider_metadata: HashMap<String, String> field for provider-specific data (e.g., GCP Vertex, Azure OpenAI), keeping the core type provider-agnostic.

State Management

State uses typed prefixes for organization:

// Access state via session
let value = session.state().get("user:preference");
session.state().set("temp:counter".to_string(), json!(42));

State keys are validated with validate_state_key() — max length is MAX_STATE_KEY_LEN (256 bytes), and keys must be valid UTF-8 with no control characters.

Callbacks

// Callback type aliases
pub type BeforeAgentCallback = Box<dyn Fn(...) -> ... + Send + Sync>;
pub type AfterAgentCallback = Box<dyn Fn(...) -> ... + Send + Sync>;
pub type BeforeModelCallback = Box<dyn Fn(...) -> ... + Send + Sync>;
pub type AfterModelCallback = Box<dyn Fn(...) -> ... + Send + Sync>;
pub type BeforeToolCallback = Box<dyn Fn(...) -> ... + Send + Sync>;
pub type AfterToolCallback = Box<dyn Fn(...) -> ... + Send + Sync>;

// Instruction providers
pub type InstructionProvider = Box<dyn Fn(...) -> ... + Send + Sync>;
pub type GlobalInstructionProvider = Box<dyn Fn(...) -> ... + Send + Sync>;

Context Compaction

Types for sliding-window context compaction (summarizing older events to reduce LLM context size):

/// Trait for summarizing events during compaction.
#[async_trait]
pub trait BaseEventsSummarizer: Send + Sync {
    async fn summarize_events(&self, events: &[Event]) -> Result<Option<Event>>;
}

/// Configuration for automatic context compaction.
pub struct EventsCompactionConfig {
    pub compaction_interval: u32,  // Invocations between compactions
    pub overlap_size: u32,         // Events to carry over for continuity
    pub summarizer: Arc<dyn BaseEventsSummarizer>,
}

Streaming Modes

pub enum StreamingMode {
    None,  // Complete responses only
    SSE,   // Server-Sent Events (default)
    Bidi,  // Bidirectional (realtime)
}

Related Crates

• adk-rust - Meta-crate with all components
• adk-agent - Agent implementations
• adk-model - LLM integrations
• adk-tool - Tool implementations

License

Apache-2.0

Part of ADK-Rust

This crate is part of the ADK-Rust framework for building AI agents in Rust.