Claude SDK for Rust

A complete, production-ready Rust SDK for Claude with full API coverage. Built for Colony Shell but usable standalone.

⚡ What Makes This Special

100% Feature Complete - Every Claude API feature implemented
Both Platforms - Anthropic API + AWS Bedrock with unified interface
Production Ready - 90 tests, retry logic, error handling, token counting
Developer Experience - Interactive REPL, auto-changelog, pre-commit hooks
Type Safe - Leverage Rust's type system for correctness
Zero Cost - Idiomatic async Rust with no runtime overhead

🚀 Features

Core API

✅ Streaming & Non-streaming - SSE streams + complete responses ✅ Error Handling - Comprehensive error taxonomy with retry logic ✅ Exponential Backoff - Automatic retry on rate limits (429) and server errors (5xx) ✅ Token Counting - Accurate context window management with tiktoken-rs

Intelligence & Tools

✅ Tool Use - Programmatic calling, parallel execution, input examples (beta) ✅ Tool Choice - Force specific tools (auto/any/tool/none) ✅ Conversations - Multi-turn state management with ConversationBuilder ✅ Extended Thinking - Step-by-step reasoning (thinking blocks with signatures) ✅ Effort Control - Token efficiency (high/medium/low for Opus 4.5)

Content Types

✅ Text - Standard messages with optional citations ✅ Images - Vision support (base64, URL, or file_id) ✅ Documents - PDFs and text files with citations ✅ Search Results - RAG with automatic source attribution ✅ Thinking Blocks - Extended reasoning (including redacted)

Cost Optimization

✅ Prompt Caching - 90% cost reduction on cached content (system prompts, tools, docs) ✅ Batch Processing - 50% discount for async bulk requests (up to 100K requests) ✅ Files API - Upload once, reference many times

Platform Support

✅ Anthropic API - Full support including all beta features ✅ AWS Bedrock - Complete implementation with streaming ✅ Regional Endpoints - standard/global/us/eu/ap prefixes

Developer Tools

✅ Interactive REPL - Full terminal UI with streaming, token display, backend switching ✅ Auto-Changelog - Uses Claude to generate changelog from git commits ✅ Pre-commit Hooks - Automated quality checks (test, clippy, fmt, docs) ✅ CI/CD - GitHub Actions for testing, releases, upstream monitoring ✅ System Prompts - Battle-tested prompts including Claude Code

Advanced Features

✅ Structured Outputs - Forced JSON extraction with schema validation ✅ Context Validation - Proactive window checking (200K/1M tokens) ✅ Model Registry - 9 models with full metadata, constraints, pricing ✅ Model Capabilities - Track extended context, effort support, thinking support

📦 Installation

Add to your Cargo.toml:

[dependencies]
claude-sdk = "1.0"
tokio = { version = "1", features = ["full"] }

# Optional features
claude-sdk = { version = "1.0", features = ["bedrock", "repl"] }

Features:

anthropic (default) - Anthropic API support
bedrock - AWS Bedrock support
repl - Interactive REPL binary
full - All features enabled

🎯 Quick Start

Basic Chat

use claude_sdk::{ClaudeClient, Message, MessagesRequest, models};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ClaudeClient::anthropic(std::env::var("ANTHROPIC_API_KEY")?);

    let request = MessagesRequest::new(
        models::CLAUDE_SONNET_4_5.anthropic_id,
        1024,
        vec![Message::user("Explain quantum entanglement")],
    );

    let response = client.send_message(request).await?;

    for content in &response.content {
        if let claude_sdk::ContentBlock::Text { text, .. } = content {
            println!("{}", text);
        }
    }

    Ok(())
}

Streaming Responses

use claude_sdk::{ClaudeClient, Message, MessagesRequest, StreamEvent};
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ClaudeClient::anthropic(
        std::env::var("ANTHROPIC_API_KEY")?
    );

    let request = MessagesRequest::new(
        claude_sdk::models::CLAUDE_SONNET_4_5.anthropic_id,
        1024,
        vec![Message::user("Tell me a story")],
    );

    let mut stream = client.send_streaming(request).await?;

    while let Some(event) = stream.next().await {
        match event? {
            StreamEvent::ContentBlockDelta { delta, .. } => {
                if let Some(text) = delta.text() {
                    print!("{}", text);
                }
            }
            StreamEvent::MessageStop => break,
            _ => {}
        }
    }

    Ok(())
}

AWS Bedrock

Same API works with AWS Bedrock:

use claude_sdk::{ClaudeClient, MessagesRequest, Message, models};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Uses AWS_PROFILE or default credential chain
    let client = ClaudeClient::bedrock("us-east-1").await?;

    let request = MessagesRequest::new(
        models::CLAUDE_SONNET_4_5.anthropic_id,  // Auto-converts to Bedrock format
        1024,
        vec![Message::user("Hello from Bedrock!")],
    );

    let response = client.send_message(request).await?;
    // Works identically to Anthropic API!

    Ok(())
}

Tool Use

use claude_sdk::{ConversationBuilder, Tool, models};
use serde_json::json;

let mut conversation = ConversationBuilder::new()
    .with_cached_system("You are a helpful assistant")  // Cached for 5min!
    .with_cached_tool(Tool {
        name: "get_weather".into(),
        description: "Get current weather".into(),
        input_schema: json!({"type": "object", "properties": {
            "location": {"type": "string"}
        }}),
        disable_user_input: Some(true),  // Programmatic
        input_examples: None,
        cache_control: None,
    });

conversation.add_user_message("What's the weather in Tokyo?");

// Claude will request tool use automatically
let request = conversation.build(models::CLAUDE_SONNET_4_5.anthropic_id, 1024);

Extended Thinking

let request = MessagesRequest::new(
    models::CLAUDE_SONNET_4_5.anthropic_id,
    16000,
    vec![Message::user("Solve this complex math problem...")],
)
.with_thinking(10_000);  // 10K token budget for reasoning

// Response includes thinking blocks showing step-by-step reasoning

Batch Processing (50% Discount!)

use claude_sdk::batch::{BatchClient, BatchRequest};

let batch_client = BatchClient::new(api_key);

let requests = vec![
    BatchRequest {
        custom_id: "req-1".into(),
        params: MessagesRequest::new(/*...*/),
    },
    // ... up to 100,000 requests
];

let batch = batch_client.create(requests).await?;
let completed = batch_client.wait_for_completion(&batch.id).await?;

// 50% cost reduction on all tokens!

Retry Logic for Production

use claude_sdk::{ClaudeClient, MessagesRequest, Message};
use claude_sdk::retry::RetryConfig;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ClaudeClient::anthropic(
        std::env::var("ANTHROPIC_API_KEY")?
    );

    let request = MessagesRequest::new(
        claude_sdk::models::CLAUDE_SONNET_4_5.anthropic_id,
        1024,
        vec![Message::user("Hello!")],
    );

    // Configure retry behavior
    let retry_config = RetryConfig::new()
        .with_max_attempts(5)
        .with_initial_backoff(std::time::Duration::from_secs(1))
        .with_max_backoff(std::time::Duration::from_secs(60));

    // Automatically retries on rate limits and server errors
    let response = client.send_message_with_retry(request, retry_config).await?;

    Ok(())
}

Examples

Run the examples with your API key:

export ANTHROPIC_API_KEY="your-api-key"
cargo run --example simple_chat
cargo run --example streaming_chat
cargo run --example tool_use
cargo run --example prompt_caching

Available examples:

simple_chat - Basic message sending with complete responses
streaming_chat - Real-time streaming responses with token display
tool_use - Tool definitions, multi-turn conversations, programmatic tool calling
prompt_caching - Cost reduction with prompt caching (90% savings on cached tokens)

🤖 Supported Models

All Claude 4.5, 4.x, and 3.x models supported with full metadata:

Model	Context	Output	Extended Context	Thinking	Effort
Claude Sonnet 4.5	200K	64K	✅ 1M	✅	❌
Claude Haiku 4.5	200K	64K	❌	✅	❌
Claude Opus 4.5	200K	64K	❌	✅	✅
Claude Opus 4.1	200K	32K	❌	✅	❌
Claude Sonnet 4	200K	64K	✅ 1M	✅	❌
Others	200K	varies	varies	varies	❌

Model Registry Includes:

Context windows & output limits
Extended context support (1M)
Thinking capability
Effort parameter support
Pricing per million tokens
Bedrock & Vertex AI IDs
Regional endpoint prefixes

✅ Complete API Coverage

Messages API: 100%

Non-streaming & streaming
System prompts (cached & non-cached)
Multi-turn conversations
Stop reasons (end_turn, max_tokens, stop_sequence, tool_use, pause_turn)

Content Types: 100%

Text (with citations)
Images (base64, URL, file_id)
Documents (PDFs, text with citations)
Search Results (RAG with auto-citations)
Tool Use & Tool Results
Thinking & Redacted Thinking

Tool Use: 100%

Tool definitions with JSON schemas
Programmatic calling (disable_user_input)
Tool choice (auto/any/tool/none)
Parallel tool use (configurable)
Input examples (beta)
Tool result error handling

Platform: 100%

Anthropic API (complete)
AWS Bedrock (streaming + non-streaming)
Regional endpoints (standard/global/us/eu/ap)
Automatic model ID conversion

Optimization: 100%

Prompt caching (90% savings)
Batch processing (50% discount)
Token counting (tiktoken-rs)
Context validation (200K/1M)
Retry logic with backoff
Effort control (Opus 4.5)

Advanced: 100%

Extended thinking (reasoning blocks)
Files API (upload/download/manage)
Structured outputs (forced JSON)
Vision (image analysis)
Citations (automatic source attribution)

Developer Tools: 100%

Interactive REPL
Token counting display
Conversation save/load
Auto-changelog generator
Pre-commit hooks
CI/CD pipelines
System prompts (Claude Code)

🎉 Development Status: v1.0.0 - COMPLETE

All Features Implemented: 22/22 (100%)

✅ Core SDK (17/17) ✅ Advanced Features (5/5) ✅ 90 tests passing ✅ Zero technical debt ✅ Production ready

What This Means:

Every documented Claude API feature is implemented
Both Anthropic and AWS Bedrock fully supported
All content types (text, image, document, search, thinking)
All optimization features (caching, batching, retry)
Complete developer tooling (REPL, hooks, CI/CD)
Ready for immediate production use

💡 Why Use This SDK?

vs. Official SDKs (TypeScript/Python):

✅ Type Safety - Rust's type system catches errors at compile time
✅ Model Registry - Full metadata with constraints and validation
✅ Unified Bedrock - Same API for both platforms
✅ System Prompts - Pre-built prompts (Claude Code, RAG, coding, etc.)
✅ Better Regional Support - First-class Bedrock endpoint handling
✅ Performance - Zero-cost abstractions, no GC pauses
✅ Memory Safety - No segfaults, no undefined behavior

vs. Building Your Own:

✅ Complete - Every API feature implemented
✅ Tested - 90 tests covering all features
✅ Maintained - Auto-monitoring for upstream changes
✅ Documented - Full API docs + examples
✅ Production Ready - Error handling, retry logic, validation

Perfect For:

🦀 Rust applications needing Claude integration
🤖 Building AI agents (like Colony Shell)
🏢 Enterprise apps needing AWS Bedrock
📊 Batch processing workloads (50% savings)
💰 Cost-sensitive applications (caching, batching)

📁 Project Structure

claude-agent-sdk-rust/
├── src/
│   ├── lib.rs              # Public API & re-exports
│   ├── client.rs           # HTTP client (Anthropic + Bedrock)
│   ├── conversation.rs     # ConversationBuilder
│   ├── types.rs            # Request/response types (400+ lines)
│   ├── error.rs            # Error taxonomy
│   ├── models.rs           # Model registry (9 models)
│   ├── streaming.rs        # SSE event types
│   ├── tokens.rs           # Token counting (tiktoken-rs)
│   ├── retry.rs            # Exponential backoff
│   ├── files.rs            # Files API client
│   ├── batch.rs            # Batch processing
│   ├── prompts.rs          # System prompts (Claude Code, etc.)
│   ├── structured.rs       # Structured output helpers
│   └── bin/
│       ├── claude-repl.rs  # Interactive REPL (440+ lines)
│       └── update-changelog.rs  # Changelog generator
├── examples/
│   ├── simple_chat.rs      # Basic non-streaming
│   ├── streaming_chat.rs   # Real-time streaming
│   ├── tool_use.rs         # Multi-turn with tools
│   └── prompt_caching.rs   # Cost optimization
├── .github/workflows/
│   ├── ci.yml              # PR checks
│   ├── release.yml         # Auto-publish
│   └── upstream-check.yml  # Model monitoring
├── hooks/
│   └── pre-commit          # Quality checks
├── scripts/
│   └── install-hooks.sh    # Hook installer
├── .claude/system/
│   ├── features.json       # Feature tracking (22 features)
│   ├── future-features.json # Advanced features
│   └── history.txt         # Development log
├── CHANGELOG.md            # Keep a Changelog format
├── CONTRIBUTING.md         # Development guide
├── RELEASE.md              # Release process
├── ROADMAP.md              # Feature roadmap
└── README.md               # This file

Development Setup

Install Git Hooks

We use pre-commit hooks to ensure code quality. Install them with:

./scripts/install-hooks.sh

The pre-commit hook automatically runs:

cargo test - All tests must pass
cargo clippy -- -D warnings - No clippy warnings allowed
cargo fmt --check - Code must be formatted
cargo doc - Documentation must build

To bypass the hook (not recommended): git commit --no-verify

Running Checks Manually

# Run all checks
cargo test --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --all -- --check
cargo doc --no-deps --all-features

# Auto-fix formatting
cargo fmt --all

Developer Tools

Interactive REPL:

Test the SDK interactively with a full-featured terminal interface:

export ANTHROPIC_API_KEY="your-api-key"
cargo run --features repl --bin claude-repl

Features:

Real-time streaming responses
Multi-turn conversations
Token counting in prompt
Slash commands (/help, /save, /load, /tokens, /model, /backend)
Backend switching (Anthropic ↔ Bedrock)
Conversation save/load

Automated Changelog Generation:

Use Claude to generate changelog entries from git commits:

export ANTHROPIC_API_KEY="your-api-key"
cargo run --bin update-changelog

This analyzes commits since the last release and generates Keep a Changelog format entries.

🤝 Contributing

This project is feature-complete at v1.0.0, but we welcome:

🐛 Bug reports and fixes
📝 Documentation improvements
✨ Additional examples
🔧 Performance optimizations

See CONTRIBUTING.md for development guidelines.

Development

# Setup
git clone https://github.com/mcfearsome/claude-agent-sdk-rust
cd claude-agent-sdk-rust
./scripts/install-hooks.sh

# Run tests
cargo test --all-features

# Quality checks
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --all -- --check
cargo doc --no-deps

📚 Documentation

API Documentation - Full API reference
Examples - Working code examples
ROADMAP.md - Feature tracking & future plans
CHANGELOG.md - Version history
CONTRIBUTING.md - Development guide
RELEASE.md - Release process

Official Claude Resources:

🎯 Design Principles

API Compliance - Match official Claude API exactly
Type Safety - Leverage Rust's type system for correctness
Zero Cost - Idiomatic async Rust with no runtime overhead
Platform Agnostic - Same API for Anthropic & Bedrock
Production Ready - Comprehensive error handling, retry logic, validation
Developer Friendly - Clear APIs, good docs, helpful tools

🏆 Status

Version: 1.0.0 Status: Production Ready ✅ Features: 22/22 (100%) Tests: 90 passing Platforms: Anthropic + AWS Bedrock

Built for: Colony Shell F015 - Claude ADK Integration

📄 License

MIT License - See LICENSE for details

🙏 Acknowledgments

Built with the official Claude API and inspired by:

Special thanks to Anthropic for creating Claude and maintaining excellent API documentation.

claude-sdk 2.0.0

Claude SDK for Rust

⚡ What Makes This Special

🚀 Features

Core API

Intelligence & Tools

Content Types

Cost Optimization

Platform Support

Developer Tools

Advanced Features

📦 Installation

🎯 Quick Start

Basic Chat

Streaming Responses

AWS Bedrock

Tool Use

Extended Thinking

Batch Processing (50% Discount!)

Retry Logic for Production

Examples

🤖 Supported Models

✅ Complete API Coverage

🎉 Development Status: v1.0.0 - COMPLETE

💡 Why Use This SDK?

📁 Project Structure

Development Setup

Install Git Hooks

Running Checks Manually

Developer Tools

🤝 Contributing

Development

📚 Documentation

🎯 Design Principles

🏆 Status

📄 License

🙏 Acknowledgments