Rust SDK for 开源AI工作流

Requirements

• Rust 1.85+
• Tokio 1.50+ (async runtime)
• serde, serde_json (serialization)
• reqwest (HTTP client)
• futures (async streams)

Installation

[dependencies]
open-agent-sdk = "0.6.4"
tokio = { version = "1", features = ["full"] }
futures = "0.3"
serde_json = "1.0"

For development:

git clone https://github.com/slb350/open-agent-sdk-rust.git
cd open-agent-sdk-rust
cargo build

Quick Start

Quick Example

use open_agent::{
    AgentOptions, Client, Hooks,
    PreToolUseEvent, PostToolUseEvent,
    HookDecision,
};

// Security gate - block dangerous operations
let hooks = Hooks::new()
    .add_pre_tool_use(|event| async move {
        if event.tool_name == "delete_file" {
            return Some(HookDecision::block("Delete operations require approval"));
        }
        Some(HookDecision::continue_())
    })
    .add_post_tool_use(|event| async move {
        // Audit logger - track all tool executions
        println!("Tool executed: {} -> {:?}", event.tool_name, event.tool_result);
        None
    });

// Register hooks in AgentOptions
let options = AgentOptions::builder()
    .system_prompt("You are a helpful assistant")
    .model("qwen2.5-32b-instruct")
    .base_url("http://localhost:1234/v1")
    .hooks(hooks)
    .build()?;

let mut client = Client::new(options)?;

Interrupt Quick Example

use open_agent::{Client, AgentOptions};
use tokio::time::{timeout, Duration};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let options = AgentOptions::builder()
        .system_prompt("You are a helpful assistant.")
        .model("qwen2.5-32b-instruct")
        .base_url("http://localhost:1234/v1")
        .build()?;

    let mut client = Client::new(options)?;
    client.send("Write a detailed 1000-word essay...").await?;

    // Timeout after 5 seconds
    match timeout(Duration::from_secs(5), async {
        while let Some(block) = client.receive().await? {
            // Process blocks
            let _ = block;
        }
        Ok::<_, Box<dyn std::error::Error>>(())
    }).await {
        Ok(_) => println!("Completed"),
        Err(_) => {
            client.interrupt();  // Clean cancellation
            println!("Operation timed out!");
        }
    }

    // Client is still usable after interrupt
    client.send("Short question?").await?;
    // Continue using client...

    Ok(())
}

Practical Examples

Example agents demonstrating real-world usage:

Why These Examples?

These agents demonstrate:

• Practical Value: Solve real problems developers face daily
• Tool Integration: Show how to integrate with system commands (git, file I/O)
• Structured Output: Parse and format LLM responses for actionable results
• Privacy-First: Keep your code and logs local while getting AI assistance

Examples

Core SDK Usage

• simple_query.rs – Minimal streaming query (simplest quickstart)
• calculator_tools.rs – Manual tool execution pattern
• auto_execution_demo.rs – Automatic tool execution pattern
• vision_example.rs – Multimodal image support (URLs, local files, base64)
• vision_api_demo.rs – Vision API walkthrough with token cost notes
• hooks_example.rs – Lifecycle hooks patterns (security gates, audit logging)
• context_management.rs – Manual history management patterns
• interrupt_demo.rs – Interrupt capability patterns (timeout, conditional, concurrent)
• advanced_patterns.rs – Retry logic and concurrent request handling
• test_tool_serialization.rs – Verifies tool call serialization (see examples/test_tool_serialization.rs)

AgentOptions

AgentOptions::builder()
    .system_prompt(str)                  // System prompt
    .model(str)                          // Model name (required)
    .base_url(str)                       // OpenAI-compatible endpoint (required)
    .tool(Tool)                          // Add a single tool for function calling
    .tools(Vec<Tool>)                    // Add multiple tools at once
    .hooks(Hooks)                        // Lifecycle hooks for monitoring/control
    .auto_execute_tools(bool)            // Enable automatic tool execution
    .max_tool_iterations(u32)            // Max tool calls per query in auto mode
    .max_tokens(u32)                     // Tokens to generate (default: 4096)
    .max_turns(u32)                      // Max conversation turns (default: 1)
    .temperature(f32)                    // Sampling temperature (default: 0.7)
    .timeout(u64)                        // Request timeout in seconds (default: 60)
    .api_key(str)                        // API key (default: "not-needed")
    .build()?

Open Agent SDK (Rust)

Build AI agents in Rust using your own hardware

What you can build:

• Copy editors that analyze manuscripts and track writing patterns
• Git commit generators that write meaningful commit messages
• Market analyzers that research competitors and summarize findings
• Code reviewers, data analysts, research assistants, and more

Why local?

• No API costs - use your hardware, not OpenAI's
• Privacy - your data never leaves your machine
• Control - pick your model (Qwen, Llama, Mistral, etc.)

How fast? From zero to working agent in under 5 minutes. Rust-native performance (zero-cost abstractions, no GC), fearless concurrency, with 360+ tests.

---

Supported (OpenAI-Compatible Endpoints)

• LM Studio - http://localhost:1234/v1
• Ollama - http://localhost:11434/v1
• llama.cpp server - OpenAI-compatible mode
• vLLM - OpenAI-compatible API
• Text Generation WebUI - OpenAI extension
• Any OpenAI-compatible local endpoint
• Local gateways proxying cloud models - e.g., Ollama or custom gateways that route to cloud providers

Note on LM Studio: LM Studio is particularly well-tested with this SDK and provides reliable OpenAI-compatible API support. If you're looking for a user-friendly local model server with excellent compatibility, LM Studio is highly recommended.

Not Supported (Use Official SDKs)

• Claude/OpenAI direct - Use their official SDKs, unless you proxy through a local OpenAI-compatible gateway
• Cloud provider SDKs - Bedrock, Vertex, Azure, etc. (proxied via local gateway is fine)

API Reference

feat(auth): Add OAuth2 integration with refresh tokens

#