claude-agent-rs

Claude Code CLI Compatible Rust SDK

English | 한국어

Why claude-agent-rs?

Quick Start

Installation

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

One-shot 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(())
}

Agent Workflow

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()              // Use Claude Code CLI auth
        .tools(ToolAccess::all())        // 12 tools + 2 server tools
        .working_dir("./my-project")
        .max_iterations(10)
        .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::ToolStart { name, .. } => eprintln!("\n[{name}]"),
            AgentEvent::ToolEnd { .. } => eprintln!(" done"),
            AgentEvent::Complete(result) => {
                eprintln!("\nTotal: {} tokens", result.total_tokens());
            }
            _ => {}
        }
    }
    Ok(())
}

Authentication

Claude Code CLI (Recommended)

let agent = Agent::builder()
    .from_claude_code()  // Automatically use OAuth token
    .build()
    .await?;

API Key

let agent = Agent::builder()
    .api_key("sk-ant-...")
    .build()
    .await?;

Cloud Providers

// AWS Bedrock
let agent = Agent::builder().bedrock("us-east-1").build().await?;

// Google Vertex AI
let agent = Agent::builder().vertex("my-project", "us-central1").build().await?;

// Azure AI Foundry
let agent = Agent::builder().foundry("my-resource", "claude-sonnet").build().await?;

See: Authentication Guide | Cloud Providers

Tools

12 Built-in Tools

2 Server Tools (Anthropic API)

Tool Access Control

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

See: Tools Guide

Key Features

Prompt Caching

Automatic system prompt caching for up to 90% token cost savings.

// Auto-enabled with from_claude_code
// Or manual configuration
let agent = Agent::builder()
    .cache_static_context(true)
    .build()
    .await?;

Skills System

.claude/commands/deploy.md:

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

Programmatic registration:

let skill = SkillDefinition::new("deploy", "Production deployment", "Deployment process...")
    .with_trigger("deploy")
    .with_allowed_tools(["Bash", "Read"]);

let agent = Agent::builder()
    .skill(skill)
    .build()
    .await?;

See: Skills Guide

Subagents

Specialized agents running in isolated contexts:

{
    "subagent_type": "explore",
    "prompt": "Analyze auth module structure",
    "run_in_background": true
}

See: Subagents Guide

Memory System

Auto-loads CLAUDE.md files for project context:

# Project Guide

@import ./docs/architecture.md

## Coding Rules
- Use Rust 2024 Edition

See: Memory System Guide

Security

See: Security Guide | Sandbox Guide

Documentation

Examples

# Core SDK test
cargo run --example sdk_core_test

# Advanced features test
cargo run --example advanced_test

# All tools test
cargo run --example all_tools_test

# Server tools (WebFetch, WebSearch)
cargo run --example server_tools

# Files API
cargo run --example files_api

Environment Variables

Testing

cargo test                    # Unit tests
cargo test -- --ignored       # Include CLI auth tests
cargo clippy --all-features   # Lint check

License

MIT or Apache-2.0 (at your option)