claude-agent 0.2.20

Rust SDK for building AI agents with Anthropic's Claude - Direct API, no CLI dependency
Documentation

claude-agent-rs

Production-Ready Rust SDK for Claude API

Crates.io Docs.rs Rust License DeepWiki

English | 한국어

Why claude-agent-rs?

Feature claude-agent-rs Other SDKs
Pure Rust, No Runtime Dependencies Native Node.js/Python required
Claude Code CLI Auth Reuse OAuth token sharing Manual API key setup
Automatic Prompt Caching System + Message caching Manual implementation
TOCTOU-Safe File Operations openat() + O_NOFOLLOW Standard file I/O
Multi-Cloud Support Bedrock, Vertex, Foundry Limited or none
OS-Level Sandboxing Landlock, Seatbelt None
1100+ Tests Production-proven Varies

Quick Start

Installation

[dependencies]
claude-agent = "0.2"
tokio = { version = "1", features = ["full"] }

Simple Query

use claude_agent::query;

#[tokio::main]
async fn main() -> claude_agent::Result<()> {
    let response = query("Explain the benefits of Rust").await?;
    println!("{response}");
    Ok(())
}

Streaming Response

use claude_agent::stream;
use futures::StreamExt;
use std::pin::pin;

#[tokio::main]
async fn main() -> claude_agent::Result<()> {
    let stream = stream("What is quantum computing?").await?;
    let mut stream = pin!(stream);

    while let Some(chunk) = stream.next().await {
        print!("{}", chunk?);
    }
    Ok(())
}

Full Agent with Tools

use claude_agent::{Agent, AgentEvent, ToolAccess};
use futures::StreamExt;
use std::pin::pin;

#[tokio::main]
async fn main() -> claude_agent::Result<()> {
    let agent = Agent::builder()
        .from_claude_code("./my-project").await?  // Auth + working_dir
        .tools(ToolAccess::all())                 // 12 built-in tools
        .with_web_search()                        // + Server tools
        .build()
        .await?;

    let stream = agent.execute_stream("Find and fix the bug in main.rs").await?;
    let mut stream = pin!(stream);

    while let Some(event) = stream.next().await {
        match event? {
            AgentEvent::Text(text) => print!("{text}"),
            AgentEvent::ToolComplete { name, .. } => eprintln!("\n[{name}]"),
            AgentEvent::Complete(result) => {
                eprintln!("\nTokens: {}", result.total_tokens());
            }
            _ => {}
        }
    }
    Ok(())
}

Authentication

Claude Code CLI (Recommended)

Agent::builder()
    .from_claude_code(".").await?  // Uses ~/.claude/credentials.json
    .build()
    .await?

API Key

use claude_agent::Auth;

Agent::builder()
    .auth(Auth::api_key("sk-ant-...")).await?
    .build()
    .await?

Cloud Providers

use claude_agent::Auth;

// AWS Bedrock
Agent::builder()
    .auth(Auth::bedrock("us-east-1")).await?
    .build().await?

// Google Vertex AI
Agent::builder()
    .auth(Auth::vertex("project-id", "us-central1")).await?
    .build().await?

// Azure AI Foundry
Agent::builder()
    .auth(Auth::foundry("resource-name")).await?
    .build().await?

Mixed: Any Auth + Claude Code Resources

// Use Bedrock auth with .claude/ project resources
Agent::builder()
    .auth(Auth::bedrock("us-east-1")).await?
    .working_dir("./my-project")
    .with_project_resources()  // Load .claude/ without OAuth
    .build().await?

See: Authentication Guide | Cloud Providers

Tools

12 Built-in Tools

Category Tools
File Read, Write, Edit, Glob, Grep
Shell Bash, KillShell
Agent Task, TaskOutput, TodoWrite, Skill
Planning Plan

2 Server Tools (Anthropic API only)

Tool Description
WebFetch Fetch and process URL content
WebSearch Web search with citations 
Agent::builder()
    .with_web_fetch()
    .with_web_search()

Tool Access Control

ToolAccess::all()                           // All 12 tools
ToolAccess::only(["Read", "Grep", "Glob"])  // Specific tools
ToolAccess::except(["Bash", "Write"])       // Exclude tools

See: Tools Guide

Key Features

Prompt Caching

Automatic caching based on Anthropic best practices:

  • System prompt caching: Static context cached with 1-hour TTL
  • Message history caching: Last user turn cached with 5-minute TTL
use claude_agent::{CacheConfig, CacheStrategy};

Agent::builder()
    .cache(CacheConfig::default())        // Full caching (recommended)
    // .cache(CacheConfig::system_only()) // System prompt only (1h TTL)
    // .cache(CacheConfig::messages_only()) // Messages only (5m TTL)
    // .cache(CacheConfig::disabled())    // No caching

3 Built-in Subagents

Type Model Purpose
explore Haiku Fast codebase search
plan Primary Implementation planning
general Primary Complex multi-step tasks

See: Subagents Guide

Skills System

Define reusable skills via markdown:

.claude/skills/deploy.md:

---
description: Production deployment
allowed-tools: [Bash, Read]
---
Deploy to $ARGUMENTS environment.

See: Skills Guide

Memory System

Auto-loads CLAUDE.md for project context:

# Project Guide
@import ./docs/architecture.md

## Rules
- Use Rust 2024 Edition

See: Memory System Guide

Session Persistence

Backend Feature Use Case
Memory (default) Development
JSONL jsonl CLI-compatible
PostgreSQL postgres Production
Redis redis-backend High-throughput

See: Session Guide

Hooks System

10 lifecycle events for execution control:

Blockable Non-Blockable
PreToolUse PostToolUse, PostToolUseFailure
UserPromptSubmit Stop, SubagentStart, SubagentStop
PreCompact, SessionStart, SessionEnd

See: Hooks Guide

MCP Integration

use claude_agent::{McpManager, McpServerConfig};
use std::collections::HashMap;

let mut mcp = McpManager::new();
mcp.add_server("filesystem", McpServerConfig::Stdio {
    command: "npx".into(),
    args: vec!["-y".into(), "@anthropic-ai/mcp-server-filesystem".into()],
    env: HashMap::new(),
}).await?;

Agent::builder().mcp_manager(mcp).build().await?

See: MCP Guide

Security

Feature Description
OS Sandbox Landlock (Linux 5.13+), Seatbelt (macOS)
TOCTOU-Safe openat() + O_NOFOLLOW atomic operations
Bash AST tree-sitter based dangerous command detection
Resource Limits setrlimit() process isolation
Network Filter Domain whitelist/blacklist

See: Security Guide | Sandbox Guide

Documentation

Document Description
Architecture System structure and data flow
Authentication OAuth, API Key, cloud integration
Tools 12 built-in + 2 server tools
Skills Slash commands and skill definitions
Subagents Subagent spawning and management
Memory CLAUDE.md and @import
Hooks 10 lifecycle events
MCP External MCP servers
Session Persistence and prompt caching
Permissions Permission modes and policies
Security TOCTOU-safe operations
Sandbox Landlock and Seatbelt
Models Model registry and pricing tiers
Tokens Context window tracking
Budget Cost limits (USD)
Observability OpenTelemetry integration
Output Styles Response formatting
Cloud Providers Bedrock, Vertex, Foundry

Feature Flags

[dependencies]
claude-agent = { version = "0.2", features = ["mcp", "postgres"] }
Feature Description
cli-integration Claude Code CLI support (default)
mcp MCP protocol support
multimedia PDF reading support
aws AWS Bedrock
gcp Google Vertex AI
azure Azure AI Foundry
jsonl JSONL persistence (CLI-compatible)
postgres PostgreSQL persistence
redis-backend Redis persistence
otel OpenTelemetry
full All features

Examples

cargo run --example advanced_test      # Skills, subagents, hooks
cargo run --example all_tools_test     # All 12 tools
cargo run --example server_tools       # WebFetch, WebSearch

Environment Variables

Variable Description
ANTHROPIC_API_KEY API key
ANTHROPIC_MODEL Default model
CLAUDE_CODE_USE_BEDROCK Enable Bedrock
CLAUDE_CODE_USE_VERTEX Enable Vertex AI
CLAUDE_CODE_USE_FOUNDRY Enable Foundry

Testing

cargo test                    # 1100+ tests
cargo test -- --ignored       # + live API tests
cargo clippy --all-features   # Lint

License

MIT