claude-agent-rs

Production-Ready Rust SDK for Claude API

English | 한국어

Why claude-agent-rs?

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 + server tools
        .tools(ToolAccess::all())                 // 12 built-in 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")
    .project_resources()  // Load .claude/ without OAuth
    .build().await?

See: Authentication Guide | Cloud Providers

Tools

12 Built-in Tools

3 Server Tools (Anthropic API only)

Server tools are auto-enabled when using OAuth/CLI authentication.

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;

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

4 Built-in Subagents

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

See: Session Guide

Hooks System

10 lifecycle events for execution control:

See: Hooks Guide

MCP Integration

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

let 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(),
    cwd: None,
}).await?;

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

See: MCP Guide

Security

See: Security Guide | Sandbox Guide

Documentation

Feature Flags

[dependencies]
claude-agent = { version = "0.2", features = ["mcp", "postgres"] }

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
cargo run --example sandbox_verification   # Sandbox testing

Environment Variables

Testing

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

License

MIT