当前位置：首页 > news >正文

AI 命令行工具开发：用 Rust 构建智能 Agent，从 API 调用到工具链编排

news 2026/6/30 15:10:02

AI 命令行工具开发：用 Rust 构建智能 Agent，从 API 调用到工具链编排

一、CLI 工具的智能化困境：为什么传统命令行不够用了

命令行工具一直是开发者的核心生产力工具。从 grep 到 ripgrep，从 curl 到 httpie，CLI 工具的进化从未停止。但传统 CLI 工具有一个根本性局限：它们只能执行预定义的逻辑，无法理解用户的意图。

实际场景中，开发者经常遇到这样的痛点：你想在日志文件中找到"过去一小时内所有超时的请求"，传统做法是组合grep、awk、date命令，管道一层套一层。如果日志格式变了，整个管道就要重写。

AI 驱动的命令行工具可以改变这个局面。用户用自然语言描述需求，工具内部将自然语言转化为具体的操作序列，执行并返回结果。这不是取代传统 CLI，而是在传统 CLI 之上增加一个智能调度层。

Rust 在这个领域的优势很明确：编译为单二进制、启动速度快、内存占用低、跨平台分发简单。这些特性让 AI CLI 工具可以像传统命令一样轻量地使用。

二、AI Agent 的架构：从单次调用到工具链编排

2.1 AI CLI 工具的三层架构

一个成熟的 AI 命令行工具，通常由三层构成：

flowchart TD A[用户输入：自然语言指令] --> B[意图解析层] B --> C{需要调用工具?} C -->|否| D[直接调用 LLM 生成回答] C -->|是| E[工具选择与编排层] E --> F[工具1: 文件搜索] E --> G[工具2: 代码分析] E --> H[工具3: Shell 执行] E --> I[工具N: ...] F --> J[结果聚合与格式化] G --> J H --> J I --> J J --> K[输出到终端] D --> K

意图解析层：将自然语言转化为结构化的操作意图
工具选择与编排层：根据意图选择合适的工具，确定执行顺序
执行与输出层：执行工具调用，聚合结果，格式化输出

2.2 ReAct 模式：推理与行动的循环

当前主流的 AI Agent 模式是 ReAct（Reasoning + Acting）。其核心思想是：LLM 先推理下一步该做什么，然后执行一个工具调用，观察结果，再推理下一步，直到任务完成。

这个循环的关键在于：每次工具调用后，LLM 都能根据返回结果调整后续策略。这比一次性生成所有操作要可靠得多，因为中间结果可以修正推理方向。

2.3 Rust 在 AI Agent 中的角色

Rust 不适合训练模型，但在 Agent 工具链中有三个不可替代的优势：

系统级集成：直接调用操作系统 API，无需通过 Python 的 subprocess
并发安全：多个工具并行调用时，无需担心数据竞争
部署简单：编译为单二进制，无需安装 Python 运行时和依赖

三、生产级代码：用 Rust 构建一个 AI Agent CLI

3.1 项目结构与依赖

# Cargo.toml 核心依赖 [dependencies] tokio = { version = "1", features = ["full"] } reqwest = { version = "0.12", features = ["json"] } serde = { version = "1", features = ["derive"] } serde_json = "1" clap = { version = "4", features = ["derive"] } anyhow = "1"

3.2 LLM 客户端：带重试和超时的 API 调用

use anyhow::{Context, Result}; use reqwest::Client; use serde::{Deserialize, Serialize}; use std::time::Duration; /// LLM API 的聊天消息 #[derive(Serialize, Deserialize, Clone, Debug)] struct ChatMessage { role: String, content: String, } /// LLM API 请求体 #[derive(Serialize)] struct ChatRequest { model: String, messages: Vec<ChatMessage>, temperature: f32, } /// LLM API 响应体（简化版） #[derive(Deserialize)] struct ChatResponse { choices: Vec<Choice>, } #[derive(Deserialize)] struct Choice { message: ChatMessage, } /// LLM 客户端：封装 API 调用、重试和超时逻辑 struct LlmClient { http: Client, api_base: String, api_key: String, model: String, } impl LlmClient { fn new(api_base: &str, api_key: &str, model: &str) -> Self { let http = Client::builder() .timeout(Duration::from_secs(60)) .build() .expect("HTTP 客户端创建失败"); LlmClient { http, api_base: api_base.to_string(), api_key: api_key.to_string(), model: model.to_string(), } } /// 发送聊天请求：带指数退避重试 async fn chat(&self, messages: Vec<ChatMessage>) -> Result<String> { let request = ChatRequest { model: self.model.clone(), messages, temperature: 0.1, }; let mut last_error = None; // 最多重试 3 次，指数退避 for attempt in 0..3 { let result = self .http .post(format!("{}/chat/completions", self.api_base)) .header("Authorization", format!("Bearer {}", self.api_key)) .json(&request) .send() .await; match result { Ok(resp) if resp.status().is_success() => { let body: ChatResponse = resp .json() .await .context("解析 LLM 响应失败")?; return Ok(body.choices[0].message.content.clone()); } Ok(resp) => { let status = resp.status(); // 429 限流时等待更久 let wait = if status.as_u16() == 429 { Duration::from_secs(2u64.pow(attempt + 2)) } else { Duration::from_secs(2u64.pow(attempt)) }; last_error = Some(anyhow::anyhow!("API 返回错误状态: {}", status)); tokio::time::sleep(wait).await; } Err(e) => { last_error = Some(anyhow::anyhow!("请求失败: {}", e)); tokio::time::sleep(Duration::from_secs(2u64.pow(attempt))).await; } } } Err(last_error.context("LLM 调用重试耗尽")?) } }

3.3 工具定义与执行框架

use serde_json::Value; /// 工具定义：描述一个可供 Agent 调用的工具 #[derive(Serialize, Clone)] struct ToolDefinition { name: String, description: String, parameters: Value, } /// 工具执行结果 struct ToolResult { output: String, success: bool, } /// 工具注册表：管理所有可用工具 struct ToolRegistry { tools: Vec<ToolDefinition>, } impl ToolRegistry { fn new() -> Self { let mut registry = ToolRegistry { tools: Vec::new() }; // 注册文件搜索工具 registry.register(ToolDefinition { name: "search_files".to_string(), description: "在指定目录中搜索包含关键词的文件".to_string(), parameters: serde_json::json!({ "type": "object", "properties": { "directory": { "type": "string", "description": "搜索目录" }, "keyword": { "type": "string", "description": "搜索关键词" } }, "required": ["directory", "keyword"] }), }); // 注册 Shell 命令执行工具 registry.register(ToolDefinition { name: "run_command".to_string(), description: "执行 Shell 命令并返回输出".to_string(), parameters: serde_json::json!({ "type": "object", "properties": { "command": { "type": "string", "description": "要执行的命令" } }, "required": ["command"] }), }); registry } fn register(&mut self, tool: ToolDefinition) { self.tools.push(tool); } /// 执行工具调用：根据工具名分发到具体实现 async fn execute(&self, tool_name: &str, args: &Value) -> Result<ToolResult> { match tool_name { "search_files" => { let dir = args["directory"].as_str().unwrap_or("."); let keyword = args["keyword"].as_str().unwrap_or(""); // 实际实现中应使用 ripgrep 库或 walkdir let output = format!("在 {} 中搜索 '{}' 的结果（示例）", dir, keyword); Ok(ToolResult { output, success: true }) } "run_command" => { let cmd = args["command"].as_str().unwrap_or(""); // 实际实现中应使用 tokio::process::Command // 并设置超时和白名单机制，防止危险命令执行 let output = format!("命令 '{}' 执行结果（示例）", cmd); Ok(ToolResult { output, success: true }) } _ => Err(anyhow::anyhow!("未知工具: {}", tool_name)), } } }

3.4 Agent 主循环：ReAct 模式实现

/// Agent 主循环：推理 → 行动 → 观察 → 再推理 async fn agent_loop( llm: &LlmClient, registry: &ToolRegistry, user_input: &str, max_iterations: usize, ) -> Result<String> { let mut messages = vec![ChatMessage { role: "system".to_string(), content: "你是一个命令行助手。根据用户需求选择合适的工具执行任务。\ 当任务完成时，用 FINISH: 开头给出最终回答。".to_string(), }]; messages.push(ChatMessage { role: "user".to_string(), content: user_input.to_string(), }); for i in 0..max_iterations { let response = llm.chat(messages.clone()).await?; // 检查是否完成 if response.starts_with("FINISH:") { return Ok(response.trim_start_matches("FINISH:").trim().to_string()); } // 尝试解析工具调用（简化版，实际应使用 function calling） if let Some(tool_call) = try_parse_tool_call(&response) { let result = registry .execute(&tool_call.name, &tool_call.args) .await?; // 将工具结果加入上下文，供下一轮推理使用 messages.push(ChatMessage { role: "assistant".to_string(), content: response.clone(), }); messages.push(ChatMessage { role: "user".to_string(), content: format!( "工具 {} 执行结果: {}", tool_call.name, result.output ), }); } else { // LLM 没有调用工具，直接返回回答 return Ok(response); } } Ok("Agent 达到最大迭代次数，任务未完成".to_string()) } /// 简化的工具调用解析（实际应使用 LLM 的 function calling API） struct ToolCall { name: String, args: Value, } fn try_parse_tool_call(text: &str) -> Option<ToolCall> { // 生产环境中应使用 LLM 原生的 function calling 能力 // 这里仅做演示：假设 LLM 输出格式为 TOOL:name:json_args let prefix = "TOOL:"; if !text.starts_with(prefix) { return None; } let rest = text.trim_start_matches(prefix); let parts: Vec<&str> = rest.splitn(2, ':').collect(); if parts.len() != 2 { return None; } let args: Value = serde_json::from_str(parts[1]).ok()?; Some(ToolCall { name: parts[0].to_string(), args, }) }