Rust + AI 全栈 · 让大模型跑在你的本地 · 第7节

Agent 系统平台开发

Agent Platform · 有手有脑有记忆的 AI 员工

Agent 就是有手有脑有记忆的 AI 员工——LLM 是大脑，工具是手，记忆是工作笔记本，规划是待办清单。2026 年最火的赛道：OpenAI Codex、Claude Code、字节 trae work、腾讯 workbuddy，全在做这件事。这一章讲怎么用 Rust 从零搭一个本地 Agent 运行时。

Agent 架构五要素

要素	人话
LLM 大脑	推理、决策、生成。支持 OpenAI / Anthropic / 本地 candle。
工具 hands	文件读写、命令执行、网页抓取、数据库查询、API 调用。
记忆 memory	短期 = 对话历史；长期 = 向量库存摘要和关键事实。
规划 planning	ReAct 循环：想一步、做一步、看结果、再想下一步。
感知 perception	读屏幕、读文件、读系统状态——决定下一步干什么。

ReAct 循环：Agent 的心跳

ReAct = Reason + Act。模型先想（Thought），再行动（Action 调工具），观察结果（Observation），循环直到任务完成。这是最简单也最有效的 Agent 范式。

loop {
    // 1. 把对话历史 + 工具定义 + 任务 发给 LLM
    let resp = llm.chat(&messages, &tools).await?;

    // 2. LLM 返回工具调用？
    match resp.tool_calls {
        Some(calls) => {
            for call in calls {
                // 3. 执行工具，把结果塞回 messages
                let result = tool_registry.execute(&call).await?;
                messages.push(ToolResult { content: result });
            }
        }
        None => {
            // 4. 没有工具调用 = LLM 认为任务完成，返回最终回答
            return Ok(resp.content);
        }
    }
}

Rust 写 Agent 的独特优势

论为什么 Agent 要 Rust

一、数据不出域。本地 Agent 要读你的文件、跑命令、访问数据库。Python 跑在别人服务器上你不放心；Rust 编译成本地二进制，数据不出本机，合规。

二、低延迟。Agent 要在毫秒级响应工具调用。Python 的 GIL 和 GC 抖一下，体验就卡。Rust 无 GC，延迟稳定。

三、可嵌入。Rust 库可以被任何语言 FFI 调用，Agent 运行时能嵌入 IDE、嵌入浏览器、嵌入手机。

Agent 平台十层架构（生产级参考）

L10 产品层：任务看板 / 会话工作区 / 数字员工管理
L9  治理层：RBAC 权限 / 工具审批 / 审计链 / 沙箱隔离
L8  可观测：Token 用量 / 成本监控 / Trace 追踪
L7  记忆层：短期对话 / 长期向量记忆 / 摘要压缩
L6  知识层：RAG 知识库 / 文档分块 / 混合检索
L5  工具层：内置工具 / MCP 工具注册表 / 沙箱执行
L4  编排层：Plan-Execute-Verify / DAG 工作流
L3  运行时：Agent 状态机 / 会话管理 / 中断恢复
L2  模型层：本地 LLM（candle）/ 云端模型 / 多模型路由
L1  基础设施：SQLite / 异步运行时 / 配置 / 日志

记忆系统：短期 + 长期

记忆层级	存什么	怎么管
短期记忆	当前对话历史	messages 数组，超 token 上限就摘要压缩
工作记忆	当前任务上下文	任务级变量，任务结束丢弃
长期记忆	用户偏好、事实、过往决策	Embedding 存 qdrant，相关时检索注入

多 Agent 协作：主管-工人模式

单个 Agent 干不了复杂活。主 Agent 拆任务，派给子 Agent：一个负责写代码、一个负责查文档、一个负责测试。子 Agent 干完把结果交回来，主 Agent 汇总。这就是"主管-工人"模式，Claude Code 的 Sub-agents 就是这个思路。Rust 里用 tokio::spawn + mpsc 通道就能实现——每个子 Agent 是一个异步任务，结果通过通道发回主 Agent。

// 主管-工人：主 Agent 派 3 个子 Agent 并行干活，收齐结果
use tokio::sync::mpsc;

#[derive(Debug, Clone)]
enum Task { WriteCode, SearchDocs, RunTests }

async fn worker(id: u32, task: Task, tx: mpsc::Sender<String>) {
    // 每个工人调 LLM 干自己那份活（这里用假结果示意）
    let result = format!("工人{} 完成 {:?}", id, task);
    tx.send(result).await.unwrap();
}

#[tokio::main]
async fn main() {
    let (tx, mut rx) = mpsc::channel::<String>(10);

    // 派三个子 Agent 并行跑
    let tasks = vec![Task::WriteCode, Task::SearchDocs, Task::RunTests];
    for (i, t) in tasks.into_iter().enumerate() {
        let tx = tx.clone();
        tokio::spawn(async move { worker(i as u32, t, tx).await; });
    }
    drop(tx);   // 关键： drop 掉主 tx，否则 rx 永远等不到结束

    // 主管收齐三份结果，汇总
    let mut report = vec![];
    while let Some(r) = rx.recv().await { report.push(r); }
    println!("汇总：\n{}", report.join("\n"));
}

$ cargo run 汇总：工人0 完成 WriteCode 工人1 完成 SearchDocs 工人2 完成 RunTests

多 Agent 的坑

① 死锁/活锁：子 Agent 互相等对方结果，谁都不动。② 结果乱序：通道不保证先来后到，要带 task_id 才能对齐。③ token 成本爆炸：N 个子 Agent 各调一次 LLM，并发 N 倍，记得限流和缓存。④ 别一上来就多 Agent——单 Agent + 好工具能干的事，拆多 Agent 反而更难调。

安全治理：权限与沙箱

论Agent 不能为所欲为

Agent 能跑命令、读写文件——这是能力也是风险。生产级 Agent 平台必须有三层护栏：

一、RBAC 权限。不同 Agent 角色能调哪些工具，白名单写死。

二、人工审批（HITL）。危险操作（删文件、发邮件、付款）弹出来等人点确认。

三、沙箱隔离。命令执行跑在容器/沙箱里，崩了不影响宿主。所有工具调用记审计日志，可追溯。

AgentScope：可借鉴的设计

阿里巴巴开源的 AgentScope（agentscope.io）是多 Agent 编排框架，支持分布式、可视化调试。Rust 里你可以借鉴它的设计模式：消息驱动、角色分工、黑板共享。虽然官方是 Python，但架构思想通用。

本地 Agent 运行时设计

做一个"数据不出域"的本地 Agent（对标 WorkBuddy 本地化产品），核心就是：本地 LLM 推理 + 本地文件访问 + 本地向量库。不需要调云端 API，断网也能用。Rust 在这个场景是天选之子——candle 跑本地模型，std::fs 读本地文件，qdrant 本地模式存向量，Tauri 打包桌面端。

本地 Agent 运行时组成：
  ├─ LLM 层：candle 加载 Qwen2.5-3B-Instruct-GGUF（Q4_K_M）
  ├─ 工具层：
  │   ├─ read_file(path)        读本地文件
  │   ├─ write_file(path, content)
  │   ├─ run_command(cmd)        沙箱里跑命令
  │   └─ search_local(query)    搜本地文件
  ├─ 记忆层：
  │   ├─ 短期：对话历史 in-memory
  │   └─ 长期：qdrant 本地嵌入式
  ├─ 编排层：ReAct 循环
  └─ UI 层：Tauri 2.0 + React

记

本章小结

① Agent 五要素：LLM 大脑、工具手、记忆、规划、感知。

② ReAct 循环：Thought → Action → Observation → 重复直到完成。

③ Rust 写 Agent：数据不出域、低延迟、可嵌入，对标 WorkBuddy / Codex 本地化产品。

← 返回总览 Rust + AI 全栈总览下一节：Rust + AI 项目实战 →