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

Or use the meta-crate:

[dependencies]
adk-rust = "0.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;
    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> },
    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

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
}

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

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

Callbacks

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

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

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.