claude-agent-rs

Production-Ready Rust SDK for Claude API

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
1000+ 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()              // Reuse Claude Code CLI OAuth
        .tools(ToolAccess::all())        // 12 built-in tools
        .with_web_search()               // + Server tools
        .working_dir("./my-project")
        .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()  // 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?

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 automatically
Message history caching: Last user turn cached for multi-turn efficiency

use claude_agent::CacheConfig;

Agent::builder()
    .cache(CacheConfig::default())  // Both enabled by default
    // .cache(CacheConfig::system_only())  // System prompt only
    // .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
PostgreSQL	`postgres`	Production (7 tables)
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
Budget	Token/cost limits
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
`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                    # 1000+ tests
cargo test -- --ignored       # + live API tests
cargo clippy --all-features   # Lint

License

MIT

claude-agent 0.2.9