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.8.1"

Or use the meta-crate:

[dependencies]
adk-rust = "0.8.1"

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;
    fn is_read_only(&self) -> bool;           // default: false
    fn is_concurrency_safe(&self) -> bool;    // default: false
    async fn execute(&self, ctx: Arc<dyn ToolContext>, args: Value) -> Result<Value>;
}

is_read_only() and is_concurrency_safe() are used by the ToolExecutionStrategy::Auto dispatch mode to run read-only tools concurrently. Both default to false so existing implementations are unaffected.

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> },
}

Multimodal Function Responses

Tools can return images, audio, or file references alongside JSON:

// Tool returns JSON with inline_data — framework extracts automatically
Ok(json!({
    "response": { "title": "Q4 Chart" },
    "inline_data": [{ "mime_type": "image/png", "data": png_bytes }]
}))

// Direct construction
let frd = FunctionResponseData::with_inline_data(
    "chart_tool",
    json!({"title": "Q4 Chart"}),
    vec![InlineDataPart { mime_type: "image/png".into(), data: png_bytes }],
);

// File references (URIs to external files)
let frd = FunctionResponseData::with_file_data(
    "doc_tool",
    json!({"status": "ok"}),
    vec![FileDataPart { mime_type: "application/pdf".into(), file_uri: "gs://bucket/report.pdf".into() }],
);

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
}

High-Stakes Tooling & Context Engineering

For production agents, adk-core provides types to ensure that an agent's instructions (the cognitive frame) always match its tool capabilities (the physical frame).

ResolvedContext

An "atomic unit" containing the final system instruction and the collection of verified, binary Arc<dyn Tool> instances. This prevents "Phantom Tool" hallucinations.

ToolRegistry

A foundational trait for mapping string-based tool names (from config or skills) to concrete executable tool instances.

ValidationMode

Defines how the framework handles cases where a requested tool is missing:

• Strict: Rejects the match/operation if any tool is missing.
• Permissive: Binds available tools, omits missing ones, and logs a warning.

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)
}

ToolExecutionStrategy

Controls how multiple tool calls from a single LLM response are dispatched:

pub enum ToolExecutionStrategy {
    Sequential,  // One at a time, in order (default)
    Parallel,    // All concurrently via join_all
    Auto,        // Read-only tools concurrently, then mutable sequentially
}

Set per-agent via LlmAgentBuilder::tool_execution_strategy().

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.