Rust Deep Agents SDK

A Rust implementation of the Deep Agents architecture — production-ready AI agents with planning, sub-agents, and persistent memory.

Quick Start • Features • Examples • Why This SDK? • Contributing • Documentation

What are Deep Agents?

Deep Agents is an architecture pioneered by LangChain for building agents that can tackle complex, multi-step tasks. Inspired by applications like Claude Code, Deep Research, and Manus, deep agents go beyond simple ReAct loops with:

This SDK brings the Deep Agents architecture to Rust, with type safety, native performance, and memory safety.

Why Rust for Deep Agents?

Building AI agents shouldn't mean sacrificing performance or type safety. While Python frameworks dominate the AI space, Rust Deep Agents SDK brings the reliability and speed of Rust to agent development.

Comparison with Alternatives

Ideal Use Cases

• Enterprise applications requiring reliability and compliance
• High-throughput systems processing thousands of agent requests
• Security-critical environments where memory safety matters
• Cloud-native deployments on AWS Lambda, ECS, or Kubernetes
• Rust teams who want AI capabilities without Python dependencies

Features

Multi-Provider LLM Support

The SDK is model-agnostic — pass any model string supported by the provider:

• OpenAI: Any model (e.g., gpt-5.2, gpt-4o, o1-pro, gpt-4o-mini)
• Anthropic: Any model (e.g., claude-opus-4.5, claude-sonnet-4.5, claude-haiku-4.5)
• Google Gemini: Any model (e.g., gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash)

Ergonomic Tool System

• #[tool] macro for zero-boilerplate tool definitions
• Automatic JSON Schema generation
• Support for sync and async tools

Flexible Persistence

• In-memory storage for development
• Redis for production deployments
• PostgreSQL for enterprise environments
• DynamoDB for AWS-native architectures

Token Tracking and Cost Control

• Real-time usage monitoring
• Cost estimation per request
• Budget alerts and limits

Human-in-the-Loop (HITL)

• Configurable approval workflows
• Tool-level interrupt policies
• Audit trail for compliance

Enterprise Security

• Automatic PII sanitization
• Sensitive field redaction
• Compliance-ready event logging

Token Optimization with TOON Format

• TOON (Token-Oriented Object Notation) support for 30-60% token reduction
• Compact, human-readable data serialization
• Feature-gated opt-in via toon feature flag

Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
agents-sdk = "0.0.29"
tokio = { version = "1.0", features = ["full"] }
anyhow = "1.0"

Your First Agent

use agents_sdk::{ConfigurableAgentBuilder, OpenAiConfig, OpenAiChatModel};
use agents_sdk::state::AgentStateSnapshot;
use agents_macros::tool;
use std::sync::Arc;

// Define a tool with a simple macro
#[tool("Adds two numbers together")]
fn add(a: i32, b: i32) -> i32 {
    a + b
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Configure the LLM
    let config = OpenAiConfig::new(
        std::env::var("OPENAI_API_KEY")?,
        "gpt-4o-mini"
    );
    let model = Arc::new(OpenAiChatModel::new(config)?);

    // Build your agent
    let agent = ConfigurableAgentBuilder::new("You are a helpful math assistant.")
        .with_model(model)
        .with_tool(AddTool::as_tool())
        .build()?;

    // Use it
    let response = agent.handle_message(
        "What is 5 + 3?",
        Arc::new(AgentStateSnapshot::default())
    ).await?;
    
    println!("{}", response.content.as_text().unwrap_or("No response"));
    Ok(())
}

Examples

Explore comprehensive examples demonstrating SDK capabilities:

Running Examples

git clone https://github.com/yafatek/rust-deep-agents-sdk.git
cd rust-deep-agents-sdk

export OPENAI_API_KEY="your-key-here"

cargo run -p tool-test
cargo run -p token-tracking-demo
cargo run -p hitl-financial-advisor

Architecture

rust-deep-agents-sdk/
├── crates/
│   ├── agents-core/        # Core traits, messages, state models
│   ├── agents-runtime/     # Execution engine, builders, middleware
│   ├── agents-toolkit/     # Built-in tools and utilities
│   ├── agents-macros/      # #[tool] procedural macro
│   ├── agents-sdk/         # Unified SDK with feature flags
│   ├── agents-aws/         # AWS integrations (DynamoDB, Secrets)
│   └── agents-persistence/ # Redis, PostgreSQL backends
├── examples/               # Working examples and demos
├── docs/                   # Documentation and guides
└── deploy/                 # Terraform modules for AWS

Provider Support

The SDK is model-agnostic — you can use any model string supported by the provider's API.

Note: Model availability depends on your API access. The SDK passes your model string directly to the provider — any model they support will work.

Middleware Stack

The SDK includes a composable middleware system:

• Token Tracking — Usage and cost monitoring
• HITL — Human approval workflows
• Planning — Todo list management
• Summarization — Context window management
• PII Sanitization — Automatic data protection
• SubAgent — Task delegation to specialized agents

Advanced Usage

use agents_sdk::{
    ConfigurableAgentBuilder, 
    OpenAiConfig, OpenAiChatModel,
    AnthropicConfig, AnthropicMessagesModel,
    GeminiConfig, GeminiChatModel
};
use std::sync::Arc;

// OpenAI
let openai = Arc::new(OpenAiChatModel::new(
    OpenAiConfig::new(api_key, "gpt-4o-mini")?
)?);

// Anthropic Claude
let claude = Arc::new(AnthropicMessagesModel::new(
    AnthropicConfig::new(api_key, "claude-sonnet-4.5", 4096)?
)?);

// Google Gemini
let gemini = Arc::new(GeminiChatModel::new(
    GeminiConfig::new(api_key, "gemini-2.5-pro")?
)?);

// Use any provider with the same builder API
let agent = ConfigurableAgentBuilder::new("You are a helpful assistant")
    .with_model(claude)
    .build()?;

use agents_sdk::{ConfigurableAgentBuilder, TokenTrackingConfig, TokenCosts};

let token_config = TokenTrackingConfig {
    enabled: true,
    emit_events: true,
    log_usage: true,
    custom_costs: Some(TokenCosts::openai_gpt4o_mini()),
};

let agent = ConfigurableAgentBuilder::new("You are a helpful assistant")
    .with_model(model)
    .with_token_tracking_config(token_config)
    .build()?;

use agents_sdk::{ConfigurableAgentBuilder, HitlPolicy};
use std::collections::HashMap;

let mut policies = HashMap::new();
policies.insert(
    "delete_file".to_string(),
    HitlPolicy {
        allow_auto: false,
        note: Some("File deletion requires security review".to_string()),
    }
);

// Use with_tool_interrupt() for each tool requiring approval
let agent = ConfigurableAgentBuilder::new("You are a helpful assistant")
    .with_model(model)
    .with_tool_interrupt("delete_file", policies.get("delete_file").unwrap().clone())
    .with_checkpointer(checkpointer)
    .build()?;

// Handle interrupts
                if let Some(interrupt) = agent.current_interrupt().await? {
    println!("Approval needed for: {}", interrupt.tool_name);
    agent.resume_with_approval(HitlAction::Accept).await?;
}

use agents_sdk::{ConfigurableAgentBuilder, InMemoryCheckpointer};
use agents_persistence::RedisCheckpointer;
use std::sync::Arc;

// Development: In-memory
let checkpointer = Arc::new(InMemoryCheckpointer::new());

// Production: Redis
let checkpointer = Arc::new(
    RedisCheckpointer::new("redis://127.0.0.1:6379").await?
);

let agent = ConfigurableAgentBuilder::new("You are a helpful assistant")
    .with_model(model)
    .with_checkpointer(checkpointer)
    .build()?;

// Save and restore conversation state
let thread_id = "user-123";
agent.save_state(&thread_id).await?;
agent.load_state(&thread_id).await?;

use agents_sdk::{ConfigurableAgentBuilder, EventBroadcaster};
use agents_core::events::AgentEvent;
use async_trait::async_trait;

struct WebhookBroadcaster {
    endpoint: String,
}

#[async_trait]
impl EventBroadcaster for WebhookBroadcaster {
    fn id(&self) -> &str { "webhook" }
    
    fn supports_streaming(&self) -> bool { true }
    
    async fn broadcast(&self, event: &AgentEvent) -> anyhow::Result<()> {
        match event {
            AgentEvent::AgentStarted(e) => { /* POST to webhook */ }
            AgentEvent::StreamingToken(e) => { /* SSE push */ }
            AgentEvent::ToolCompleted(e) => { /* Log to analytics */ }
            AgentEvent::TokenUsage(e) => { /* Track costs */ }
            _ => {}
        }
        Ok(())
    }
}

let agent = ConfigurableAgentBuilder::new("You are a helpful assistant")
    .with_model(model)
    .with_event_broadcaster(Arc::new(WebhookBroadcaster { 
        endpoint: "https://api.example.com/events".into() 
    }))
    .build()?;

use agents_sdk::{ConfigurableAgentBuilder, SubAgentConfig};

let researcher = SubAgentConfig::new(
    "researcher",
    "Searches and analyzes information",
    "You are a research specialist.",
);

let writer = SubAgentConfig::new(
    "writer",
    "Creates well-written content",
    "You are a content writer.",
);

// Use with_subagent_config() to add sub-agents
let agent = ConfigurableAgentBuilder::new("You are a project coordinator.")
    .with_model(model)
    .with_subagent_config([researcher, writer])
    .with_auto_general_purpose(true)
    .build()?;

use agents_sdk::{ConfigurableAgentBuilder, PromptFormat};

let agent = ConfigurableAgentBuilder::new("You are a helpful assistant")
    .with_model(model)
    .with_prompt_format(PromptFormat::Toon)  // Enable TOON format
    .build()?;

use agents_core::toon::ToonEncoder;
use serde_json::json;

let encoder = ToonEncoder::new();
let data = json!({
    "users": [
        {"id": 1, "name": "Alice", "role": "admin"},
        {"id": 2, "name": "Bob", "role": "user"}
    ]
});

// TOON output is ~40% smaller than JSON
let toon_string = encoder.encode(&data)?;
// users[2]{id,name,role}:
//   1,Alice,admin
//   2,Bob,user

Feature Flags

[dependencies]
# Default: includes toolkit
agents-sdk = "0.0.29"

# Minimal: core only
agents-sdk = { version = "0.0.29", default-features = false }

# With persistence
agents-sdk = { version = "0.0.29", features = ["redis"] }
agents-sdk = { version = "0.0.29", features = ["postgres"] }

# With AWS
agents-sdk = { version = "0.0.29", features = ["aws", "dynamodb"] }

# With TOON format (token optimization)
agents-sdk = { version = "0.0.29", features = ["toon"] }

# Everything
agents-sdk = { version = "0.0.29", features = ["full"] }

Development

git clone https://github.com/yafatek/rust-deep-agents-sdk.git
cd rust-deep-agents-sdk

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all
cargo build --release

Environment Variables

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="..."
export TAVILY_API_KEY="..."  # Optional: for web search

Contributing

We welcome contributions of all kinds:

• Bug reports and fixes
• Feature requests and implementations
• Documentation improvements
• Test coverage

Please read our Contributing Guide to get started.

New contributors can look for issues labeled good first issue.

Roadmap

Providers

• AWS Bedrock provider (Claude, Titan, Llama)
• Ollama for local/self-hosted models
• Azure OpenAI Service

Features

• Custom sub-agent execution graphs
• Advanced state features (encryption, migrations)
• Enhanced tool composition and validation
• WebAssembly support
• OpenTelemetry integration

See the full roadmap for details.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Support

• API Documentation
• GitHub Discussions
• Issue Tracker

_{Built with Rust for production AI systems}