AI Agent SDK (Claude Code SDK in Rust)

English | 中文

Idiomatic Rust SDK — 1:1 translation of Claude Code. Runs the full agent loop in-process with 50 built-in tools. Deploy anywhere: cloud, serverless, Docker, CI/CD.

AI Coding CLI: ai-code

Quick Start

cargo add ai-agent
export AI_AUTH_TOKEN=your-api-key
export AI_MODEL=MiniMaxAI/MiniMax-M2.5

use ai_agent::Agent;

// Simple one-shot query
let answer = Agent::prompt("claude-sonnet-4-6", "List 10 files").await?;

// Full agent with builder pattern
let agent = Agent::new("claude-sonnet-4-6")
    .max_turns(10);
let result = agent.query("List 10 files").await?;

See Usage Examples for more.

Core Features

Built-in Tools

The SDK ships with 50 built-in tools organized into 15 categories. All tools are available out of the box with full parameter validation and type-safe schemas.

File Operations (4)

File Discovery (2)

Shell Execution (3)

Web (3)

Code Intelligence (1)

Multi-agent Orchestration (4)

Task Management (6)

Planning Mode (2)

User Interaction (2)

Scheduling (3)

Git Worktrees (2)

Skills & Configuration (4)

MCP (Model Context Protocol) (4)

Remote / Cloud (1)

Communication & Data (3)

Internal / Not Implemented (6)

These tools are defined in the schema but not actively registered. They are placeholders for future features.

Usage Examples

The agent automatically uses 50 built-in tools across 15 categories to accomplish tasks.

Multi-turn Conversation

let agent = Agent::new("claude-sonnet-4-6")
    .max_turns(10);
agent.query("Create /tmp/hello.txt with 'Hello'").await?;
agent.query("Read that file back").await?;
println!("Messages: {}", agent.get_messages().len());

Custom Tools

use ai_agent::{Agent, ToolDefinition, ToolInputSchema};

let agent = Agent::new("claude-sonnet-4-6")
    .max_turns(5)
    .tools(vec![
        ToolDefinition {
            name: "calculator".into(),
            description: "Evaluate a math expression. Returns the result".into(),
            input_schema: ToolInputSchema {
                schema_type: "object".into(),
                properties: serde_json::json!({
                    "expression": {
                        "description": "The expression to evaluate",
                        "type": "string"
                    }
                }),
                required: Some(vec!["expression".into()]),
            },
            ..Default::default()
        },
    ]);

MCP Servers

let config = McpServerConfig::Stdio(McpStdioConfig {
    command: "npx".into(),
    args: Some(vec!["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]),
    ..Default::default()
});

Hooks

registry.register("PreToolUse", HookDefinition {
    command: Some("echo pre-tool".into()),
    timeout: Some(5000),
    matcher: Some("Read.*".into()),
});

Event Callback API (CLI/TUI Integration)

Register an on_event callback to receive incremental events during query execution — ideal for real-time chat UIs and TUIs.

use ai_agent::{Agent, AgentEvent, ContentDelta};

let agent = Agent::new("claude-sonnet-4-6")
    .max_turns(10)
    .on_event(|event| match &event {
        AgentEvent::ContentBlockDelta {
            delta: ContentDelta::Text { text },
            ..
        } => print!("{}", text),
        AgentEvent::Thinking { turn } => {
            eprintln!("[Turn {} thinking...]", turn);
        }
        AgentEvent::Done { result } => {
            println!("\nDone! Turns: {}", result.num_turns);
        }
        _ => {}
    });

let result = agent.query("write hello world").await?;

Pub/Sub Event Subscription

For decoupled architectures, use subscribe() to listen to events independently:

let (mut sub, _guard) = agent.subscribe();
// Run query in background, consume events via sub.next().await

Interrupting Agent Execution

Call agent.interrupt() from another task to cancel a running query(). The operation returns AgentError::UserAborted.

use ai_agent::Agent;
use std::sync::Arc;
use std::time::Duration;
use tokio::sync::Mutex;

let agent = Arc::new(Mutex::new(Agent::new("claude-sonnet-4-6").max_turns(10)));
let interrupt_agent = Arc::clone(&agent);

// Spawn a task that interrupts after 5 seconds
let interrupt_task = tokio::spawn(async move {
    tokio::time::sleep(Duration::from_secs(5)).await;
    interrupt_agent.lock().await.interrupt();
});

// Run the query with exclusive access
let result = {
    let mut ag = agent.lock().await;
    ag.query("Process a large codebase").await
};

let _ = tokio::time::timeout(Duration::from_secs(10), interrupt_task).await;

See examples/27_interrupt.rs for a full runnable example.

Configuration

Agent Options

Environment Variables

API Compatibility

SDK uses OpenAI format, compatible with:

• MiniMax
• Anthropic (via compatible endpoint)
• OpenAI (compatible mode)
• Any provider with /v1/chat/completions endpoint

Architecture

┌─────────────────────────────────────┐
│         Your Application             │
│   use ai_agent::Agent            │
└──────────────┬──────────────────────┘
               │
    ┌──────────▼──────────┐
    │       Agent         │  Session, tools, MCP
    │    query()          │
    └──────────┬──────────┘
               │
    ┌──────────▼──────────┐
    │    QueryEngine      │  Agent loop: API → tools → repeat
    └──────────┬──────────┘
               │
    ┌──────────┼──────────┐
    │          │          │
┌───▼───┐  ┌───▼────┐  ┌──▼────┐
│  LLM  │  │ 50     │  │  MCP  │
│  API  │  │Tools   │  │Server │
└───────┘  └───────┘  └───────┘

Examples

cargo run --example 01_simple_query
cargo run --example 18_plugin
cargo run --example 19_hooks

License

MIT