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 25+ built-in tools. Deploy anywhere: cloud, serverless, Docker, CI/CD.

AI Coding CLI: ai-code

Quick Start

cargo add ai-agent-sdk
export AI_AUTH_TOKEN=your-api-key
export AI_MODEL=MiniMaxAI/MiniMax-M2.5
# Optional: AI_BASE_URL=https://api.minimax.chat/v1

use ai_agent_sdk::Agent;
let mut agent = Agent::new("MiniMaxAI/MiniMax-M2.5", 10);
agent.prompt("List 10 files").await?;

See Usage Examples for more.

Core Features

Feature	Description
Agent	Create agents with custom models, tools, and prompts
Subagent	Spawn subagents for parallel or specialized tasks
Session	Persist, resume, fork conversations on disk
Context Compact	Automatic conversation summarization when approaching context limits
Skills	Load external skills or use 15+ bundled skills
Hooks	20+ lifecycle events (PreToolUse, PostToolUse, SessionStart, etc.)
Tools	25+ built-in tools (Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, Agent, Tasks, Teams, Worktree, Cron, etc.)
Memory	File-based persistent context via MEMORY.md
Permissions	Tool access control with allow/deny rules
Plugins	Load plugins with commands, skills, MCP servers
MCP	Connect to Model Context Protocol servers
Cost Tracking	Real-time token usage and cost estimation

Usage Examples

The agent automatically uses 25+ built-in tools (Bash, Read, Write, Edit, Glob, Grep, WebFetch, etc.) to accomplish tasks.

Multi-turn Conversation

let mut agent = Agent::new("MiniMaxAI/MiniMax-M2.5", 5);
agent.prompt("Create /tmp/hello.txt with 'Hello'").await?;
agent.prompt("Read that file back").await?;
println!("Messages: {}", agent.get_messages().len());

Custom Tools

let calculator = ai_agent_sdk::Tool {
    name: "Calculator".into(),
    description: "Evaluate math expressions".into(),
    input_schema: ToolInputSchema::Json(serde_json::json!({
        "type": "object",
        "properties": {"expression": {"type": "string"}},
        "required": ["expression"]
    })),
    executor: Box::new(|input, _ctx| async move {
        Ok(ToolResult { /* ... */ })
    }),
};

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()),
});

Configuration

Agent Options

Option	Default	Description
`model`	MiniMaxAI/MiniMax-M2.5	LLM model ID
`max_turns`	10	Max agentic turns
`max_tokens`	16384	Max response tokens
`max_budget_usd`	—	Spending cap
`system_prompt`	—	Custom system prompt
`cwd`	process.cwd()	Working directory
`allowed_tools`	all	Tool allow-list
`disallowed_tools`	—	Tool deny-list

Environment Variables

Variable	Default	Description
`AI_AUTH_TOKEN`	—	API key (required)
`AI_MODEL`	MiniMaxAI/MiniMax-M2.5	Model name
`AI_BASE_URL`	—	Custom API endpoint
`AI_CONTEXT_WINDOW`	200000	Context window size
`AI_DISABLE_AUTO_MEMORY`	false	Disable auto memory
`AI_MEMORY_PATH_OVERRIDE`	~/.ai	Memory directory
`AI_AUTO_COMPACT_WINDOW`	model-based	Compact trigger window
`AI_AUTOCOMPACT_PCT_OVERRIDE`	—	Threshold % (0-100)
`AI_DISABLE_COMPACT`	false	Disable compaction
`AI_CODE_DISABLE_BACKGROUND_TASKS`	false	Disable background tasks

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_sdk::Agent            │
└──────────────┬──────────────────────┘
               │
    ┌──────────▼──────────┐
    │       Agent         │  Session, tools, MCP
    │    prompt()         │
    └──────────┬──────────┘
               │
    ┌──────────▼──────────┐
    │    QueryEngine      │  Agent loop: API → tools → repeat
    └──────────┬──────────┘
               │
    ┌──────────┼──────────┐
    │          │          │
┌───▼───┐  ┌───▼───┐  ┌──▼────┐
│  LLM  │  │ 25+   │  │  MCP  │
│  API  │  │Tools  │  │Server │
└───────┘  └───────┘  └───────┘

Examples

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

License

MIT

ai-agent 0.13.4