Agent-Reach 实战：从零搭建 CLI AI Agent 调度框架

1. 从命令行到智能体Agent-Reach 到底想解决什么问题第一次看到 Agent-Reach 这个名字我脑子里蹦出来的画面是“让 Agent 伸手够到真实世界”。后来翻了一圈社区讨论发现这个理解方向基本对路。它本质上是一个基于 CLI 形态运行的 AI Agent 调度层核心目标是把大模型从“只会聊天”变成“能动手干活”的角色。你给它一条指令它自己去拆解任务、调用工具、读写文件、执行命令最后把结果反馈回来。听起来像是把 Codex CLI、Claude Code 那一类工具的能力抽象出来做成一个更通用、更容易接入自己业务场景的框架。为什么是 CLI这个问题我琢磨了很久。GUI 当然更友好但 CLI 有三个天然优势第一它天然适合管道化操作你可以把 Agent-Reach 嵌进任何脚本、CI/CD 流程或者定时任务里第二它的输入输出是纯文本调试和日志记录极其方便出问题的时候你直接看终端回显就能定位第三它对资源的占用极低一台 1C1G 的轻量服务器就能跑起来不需要额外开浏览器或者图形环境。这三点加起来决定了 CLI 形态的 Agent 在自动化和工程化场景里几乎是唯一合理的选择。那 Agent-Reach 和市面上已有的 Codex CLI、zcode CLI 有什么区别我的理解是Codex CLI 更偏向“代码生成执行”的垂直场景而 Agent-Reach 的野心更大一些它想做一个通用的 Agent 运行时。你可以把它理解成一个“Agent 的操作系统”底层负责和 LLM 通信中间层负责工具注册和调度上层负责任务编排和状态管理。这种分层设计的好处是你换模型、换工具、换业务逻辑都不需要动核心框架。社区里有人拿它接 FastAPI LangChain LangGraph 那一套也有人直接用它跑 Django 项目的自动化开发说明它的适配层做得比较薄侵入性低。适合谁来用我觉得有三类人值得重点关注。第一类是后端工程师尤其是那些已经在用 Spring AI Agent 或者自己搭过 Agent 框架的人Agent-Reach 可以帮你省掉大量重复造轮子的时间第二类是运维和 DevOps你可以用它做 GitLab CLI 安装、日志分析、自动巡检这类重复性工作第三类是独立开发者和技术博主想快速验证一个 AI Agent 项目想法Agent-Reach 的启动成本比从零写一个低得多。当然如果你完全没接触过命令行那可能需要先补一下基础否则连安装那一步都会卡住。2. 核心架构拆解一个 CLI Agent 是怎么跑起来的2.1 四层架构与数据流向Agent-Reach 的架构我画过好几遍草图最后收敛成一个四层模型。最底层是LLM 通信层负责和模型 API 打交道处理 token 计算、流式输出、重试和降级。这一层的关键设计是“模型无关”也就是说你可以在配置文件里切换不同的模型提供商而不需要改任何业务代码。第二层是工具注册层所有可被 Agent 调用的能力——读文件、写文件、执行 shell、发 HTTP 请求——都以工具的形式注册进来每个工具包含名称、描述、参数 schema 和执行函数。第三层是任务编排层这是最核心的部分它决定 Agent 下一步该做什么是继续调用工具还是给出最终答案。第四层是会话与状态层负责维护多轮对话的上下文、任务执行历史和中间结果。数据流向是这样的用户输入一条指令编排层把它和系统提示词、历史上下文拼成一个完整的 prompt发给 LLM 通信层LLM 返回一个响应编排层解析这个响应判断它是“工具调用”还是“最终答案”如果是工具调用就路由到工具注册层执行把结果追加到上下文里再次发给 LLM循环往复直到得到最终答案。这个循环就是所谓的ReAct 循环Reasoning Acting也是目前 AI Agent 主流架构的基础范式。注意ReAct 循环必须有最大迭代次数限制否则遇到模型“钻牛角尖”的情况会无限循环烧 token。我一般设 15 到 20 轮超过就强制中断并返回当前结果。2.2 工具注册机制的设计取舍工具注册这块Agent-Reach 用的是装饰器模式。你写一个 Python 函数上面加一行tool框架自动读取函数的类型注解和 docstring生成对应的 JSON Schema。这个设计的好处是极简开发者不需要手写 schema减少出错概率。但代价是灵活性受限比如你想动态控制某个工具在不同场景下是否可见就需要额外写一层包装。我实测下来这种设计对 80% 的场景够用。剩下 20% 的复杂场景比如需要根据用户权限动态裁剪工具列表可以通过在编排层加一个 filter 钩子来实现。具体做法是继承默认的 ToolRegistry 类重写get_available_tools方法在里面根据 session 里的用户角色返回不同的工具子集。这个扩展点官方文档没怎么写但源码里留了口子算是一个隐藏福利。工具描述的质量直接决定 Agent 的调用准确率。我踩过的一个坑是把工具描述写得太短比如“读取文件”四个字结果模型经常把“读取文件”和“列出目录”搞混。后来我把描述改成“读取指定路径的文本文件内容返回字符串。如果路径是目录会报错需要先用 list_directory 工具”调用准确率立刻上去了。所以写工具描述的时候一定要把边界条件和前置依赖写清楚这是血的教训。2.3 上下文管理与 token 预算Agent 跑多轮任务的时候上下文会迅速膨胀。一个稍微复杂点的任务十几轮下来轻松突破几万 token。Agent-Reach 默认用的是滑动窗口加摘要的策略保留最近 N 轮完整对话更早的内容用 LLM 压缩成一段摘要。这个策略在大多数场景下够用但有两个坑需要注意。第一个坑是摘要会丢失细节。比如 Agent 前面读了一个配置文件记住了某个端口号后面摘要的时候这个端口号可能被压缩掉导致后续步骤用错参数。我的解决办法是把关键信息显式写进一个“工作记忆”区域这个区域不参与摘要压缩始终保留在上下文里。具体实现就是在系统提示词里留一个## Working Memory段落每轮任务开始前由编排层更新。第二个坑是 token 计算不准。不同模型的分词器不一样用 tiktoken 算出来的数字和实际 API 计费可能有 10% 到 20% 的偏差。我的建议是留足余量比如模型上下文窗口是 128k你实际用到 80k 就该触发压缩了别等到 120k 才动手否则很容易撞上限流或者截断。3. 从零搭建Agent-Reach 的安装与最小可运行实例3.1 环境准备与依赖安装Agent-Reach 基于 Python 3.10 运行官方推荐用 uv 做包管理比 pip 快很多。如果你还在用 pip建议花十分钟切到 uv后面装依赖的时候能省不少时间。Rust 语言写的 AI Agent 最近也很火但 Agent-Reach 目前还是 Python 生态别搞混了。安装步骤我整理成了一张表照着做基本不会出问题步骤命令说明1curl -LsSf https://astral.sh/uv/install.sh | sh安装 uv 包管理器2uv python install 3.11安装 Python 3.113uv venv .venv创建虚拟环境4source .venv/bin/activate激活虚拟环境5uv pip install agent-reach安装 Agent-Reach6agent-reach --version验证安装提示如果你在国内网络环境uv 的下载速度可能不理想可以配置镜像源。在~/.config/uv/uv.toml里加上[[index]] url https://pypi.tuna.tsinghua.edu.cn/simple即可。安装完之后你需要配置模型 API Key。Agent-Reach 支持环境变量和配置文件两种方式我推荐用配置文件方便管理多个模型。配置文件默认在~/.agent-reach/config.toml内容大概长这样[llm] provider openai model gpt-4o api_key sk-xxxxxxxx base_url https://api.openai.com/v1 max_tokens 4096 temperature 0.1 [agent] max_iterations 20 verbose true working_dir ./workspacetemperature 设 0.1 是有讲究的。Agent 任务需要的是稳定和可复现不是创意发散。我试过 0.7 和 0.1 的对比高 temperature 下 Agent 经常“自作主张”改需求低 temperature 下行为明显更可控。除非你做的是创意类任务否则别调高。3.2 第一个 Agent 任务自动整理目录装好之后跑一个最小实例找找感觉。假设你有一个下载目录里面堆满了各种文件想让 Agent 帮你按类型归类。创建一个demo.pyfrom agent_reach import Agent, tool import os import shutil tool def list_files(directory: str) - str: 列出指定目录下的所有文件和文件夹名称返回换行分隔的字符串。 return \n.join(os.listdir(directory)) tool def move_file(src: str, dst_dir: str) - str: 把源文件移动到目标目录。如果目标目录不存在会自动创建。 os.makedirs(dst_dir, exist_okTrue) shutil.move(src, os.path.join(dst_dir, os.path.basename(src))) return fMoved {src} to {dst_dir} agent Agent(tools[list_files, move_file]) result agent.run(把 ./downloads 目录下的文件按扩展名分类图片放到 images文档放到 docs其他放到 others) print(result)跑起来之后你会看到终端里 Agent 一步步思考、调用工具、观察结果。这个过程非常直观也是 CLI 形态最大的魅力——你能看到 Agent 的“思考过程”而不是一个黑盒。注意move_file这种有副作用的工具一定要加确认机制。生产环境里我建议加一个dry_run参数先让 Agent 输出计划人工确认后再执行。Agent-Reach 支持在工具函数里抛RequireConfirmation异常框架会暂停并等待用户输入 y/n。3.3 接入自定义工具链Agent-Reach 真正强大的地方在于工具链的扩展。你可以把任何 Python 函数变成工具包括调用内部 API、操作数据库、发送消息等等。社区里有人拿它接小红书自动发消息原理就是写一个send_message工具内部调用对应的接口。这里不展开具体平台细节但思路是通用的任何重复性的、有明确输入输出的操作都可以封装成工具交给 Agent 调度。我自己的做法是维护一个tools/目录每个业务模块一个文件用__init__.py统一导出。这样 Agent 初始化的时候一行代码就能加载全部工具from tools import ALL_TOOLS agent Agent(toolsALL_TOOLS)工具多了之后prompt 会变长模型选择工具的准确率会下降。这时候可以上工具分组策略根据任务类型动态加载工具子集。比如处理文件的任务只加载文件类工具处理网络的任务只加载 HTTP 类工具。这个策略能把工具数量从几十个压到五六个准确率提升非常明显。4. 并发、部署与生产化改造4.1 AI Agent 怎么扛并发“AI Agent 怎么扛并发”是最近被问得最多的问题。我的答案可能有点反直觉大多数场景下你不需要扛高并发你需要的是任务队列。Agent 任务的特点是耗时长几秒到几分钟、token 成本高、状态复杂用同步 HTTP 请求去扛并发是自找麻烦。正确的做法是前面挂一个消息队列Agent 作为消费者异步处理。具体架构是这样的Web 层接收请求把任务丢进 Redis 队列立即返回一个 task_idAgent Worker 从队列里取任务执行把结果写回 Redis客户端用 task_id 轮询或者走 WebSocket 拿结果。这套架构下单台 4C8G 的机器跑 10 到 20 个并发 Worker 没问题再往上加机器就行扩展性是线性的。Agent-Reach 本身是同步执行的要改造成 Worker 模式需要在外面包一层。我写过一个简单的 Worker 模板import redis import json from agent_reach import Agent r redis.Redis() agent Agent(toolsALL_TOOLS) while True: _, task_data r.blpop(agent_tasks) task json.loads(task_data) try: result agent.run(task[prompt]) r.set(fresult:{task[id]}, result) except Exception as e: r.set(fresult:{task[id]}, fERROR: {e})这个模板很粗糙生产环境还需要加超时控制、重试、日志、监控。但核心思路就是这样Agent 不直接面对用户请求而是面对队列。4.2 部署方案对比部署 Agent-Reach 有几种常见方案我列了个对比表方案适用场景优点缺点裸机 systemd单机小规模简单直接性能最好扩展性差无高可用Docker Compose中小规模环境隔离部署方便资源开销略大K8s HPA大规模自动扩缩容高可用运维复杂度高Serverless低频任务按需付费零运维冷启动慢有超时限制我个人推荐从 Docker Compose 起步。写一个 Dockerfile把 Agent-Reach 和你的工具代码打进去用 Compose 管理 Worker 数量。等业务量上来了再迁 K8s迁移成本不高。Dockerfile 有个坑要注意Agent 执行 shell 命令的时候容器里的环境和宿主机不一样。如果你需要 Agent 操作宿主机文件要么挂载 volume要么用 Docker socket。前者更安全后者更方便但风险高。我一般用 volume 挂载一个工作目录Agent 只能在这个目录里活动避免误操作。4.3 监控与成本控制Agent 跑起来之后最怕两件事一是任务卡死没人知道二是 token 烧超预算。监控这块我建议至少埋三个指标任务成功率、平均执行轮数、单任务 token 消耗。前两个反映 Agent 的健康度第三个直接关系到钱包。Agent-Reach 支持回调钩子可以在每轮循环结束时触发。我用这个钩子把指标打到 Prometheusfrom prometheus_client import Counter, Histogram task_counter Counter(agent_tasks_total, Total tasks, [status]) token_histogram Histogram(agent_tokens_per_task, Tokens per task) def on_iteration_end(info): token_histogram.observe(info[tokens_used]) def on_task_end(info): task_counter.labels(statusinfo[status]).inc()成本控制方面除了设 max_iterations还可以设单任务 token 上限。Agent-Reach 的配置里有个max_tokens_per_task参数超过就强制中断。我一般设 100k正常任务很少超过这个数超了基本说明 Agent 跑偏了中断反而是好事。提示如果你用的是按量计费的模型建议在测试环境用便宜的小模型跑通流程生产环境再换大模型。我见过有人测试阶段就用 GPT-4 跑一天烧掉几百块其实大部分测试用小模型完全够用。5. 常见问题与排查技巧实录5.1 Agent 不调用工具怎么办这是新手遇到最多的一个问题。你明明注册了工具Agent 却在那里“空谈”就是不调用。原因通常有三个一是工具描述写得太模糊模型不知道什么时候该用二是系统提示词里没有强调“优先使用工具”三是模型本身能力不足小模型经常出现这种情况。排查顺序我建议这样先看工具描述把每个工具的描述改成“什么情况下用输入是什么输出是什么”的格式然后在系统提示词里加一句“当需要获取信息或执行操作时优先调用可用工具不要凭记忆回答”如果还不行换个更强的模型试试。我实测下来GPT-4o 和 Claude 3.5 Sonnet 在工具调用上的表现明显好于小模型这个钱不能省。5.2 工具调用参数错误模型传错参数是第二常见的问题。比如你定义了一个read_file(path: str)模型可能传{file_path: xxx}或者{path: xxx, encoding: utf-8}。这种问题的根源是 JSON Schema 生成得不够严格。Agent-Reach 默认用类型注解生成 schema但如果你用了Optional或者默认值schema 会变得宽松模型就容易乱传。解决办法是在工具函数里加参数校验发现多余参数或者缺少参数时返回一个明确的错误信息让模型自己纠正。比如tool def read_file(path: str) - str: 读取文件内容。参数 path 必须是字符串不能有其他参数。 if not isinstance(path, str): return ERROR: path must be a string ...这个错误信息会回到模型那里模型看到之后通常会重新调用。我试过加了这个校验之后参数错误率能降一半以上。5.3 任务循环不终止Agent 陷入死循环是第三大坑。表现是它反复调用同一个工具或者在不同工具之间来回横跳就是不给最终答案。原因可能是任务本身有歧义也可能是工具返回的结果让模型困惑。应急处理就是设 max_iterations这个前面说过了。但治本的方法是优化任务描述和工具返回值。任务描述要尽量明确避免“帮我整理一下”这种模糊指令改成“把 A 目录下的 .jpg 文件移动到 B 目录”。工具返回值要简洁明确不要返回一大堆无关信息否则模型容易被干扰。我整理了一个常见问题速查表贴在下面方便对照现象可能原因排查方法解决方案不调用工具描述模糊/提示词缺失检查工具 docstring改描述加提示词参数错误Schema 不严格看模型传的 JSON加参数校验死循环任务歧义/返回值干扰看迭代日志明确任务精简返回结果不完整max_iterations 太小看是否被中断调大迭代次数token 超限上下文膨胀看 token 统计开启摘要压缩5.4 模型切换后的兼容性问题不同模型的工具调用格式不一样。OpenAI 用function_callAnthropic 用tool_use有些开源模型干脆用纯文本描述。Agent-Reach 在通信层做了适配但偶尔还是会有兼容性问题。我遇到过一次从 GPT-4o 切到某个国产模型之后工具调用全部失效原因是那个模型不支持 JSON Schema 格式的参数定义。解决办法是在配置里指定tool_format参数Agent-Reach 支持openai、anthropic、text三种格式。如果模型比较特殊可以用text格式让模型用自然语言描述工具调用框架再用正则解析。这种方式准确率低一些但兼容性最好。6. 进阶玩法把 Agent-Reach 嵌进现有工作流6.1 与 CI/CD 集成Agent-Reach 最适合的场景之一是 CI/CD 自动化。比如每次 MR 提交的时候让 Agent 自动做代码审查、跑测试、生成变更说明。具体做法是在 GitLab CI 的.gitlab-ci.yml里加一个 jobagent-review: stage: review script: - agent-reach run 审查本次 MR 的代码变更检查是否有明显的 bug 或安全问题输出审查报告 only: - merge_requests这个 job 跑完可以把报告贴到 MR 评论里。我实测下来Agent 能抓到一些低级错误比如未处理的异常、硬编码的密钥、明显的逻辑漏洞。但它不能替代人工审查只能作为第一道过滤。6.2 定时任务与自动巡检用 cron 配合 Agent-Reach 可以做自动巡检。比如每天早上 9 点检查服务器磁盘、内存、日志异常生成巡检报告发到群里。这个场景下 Agent 的价值在于它能“理解”日志内容而不是简单地 grep 关键字。比如日志里出现“connection timeout”Agent 能判断这是网络问题还是下游服务挂了并给出排查建议。配置方式很简单写一个 shell 脚本里面调用agent-reach run然后加到 crontab 里。注意 cron 环境下的 PATH 和虚拟环境可能不一样脚本里要用绝对路径。6.3 多 Agent 协作单个 Agent 能力有限复杂任务可以拆成多个 Agent 协作。比如一个“规划 Agent”负责拆解任务多个“执行 Agent”负责具体操作一个“审查 Agent”负责检查结果。Agent-Reach 本身不直接支持多 Agent但你可以用消息队列把它们串起来。这种架构的复杂度上升很快我建议先从单 Agent 做起确实遇到瓶颈再考虑多 Agent。很多场景下单 Agent 加更多工具就能解决没必要上多 Agent。7. 一些踩坑之后的个人体会Agent-Reach 这个项目我用下来最大的感受是Agent 的能力上限取决于工具的质量而不是模型的能力。同样的模型工具写得好Agent 就像个熟练工工具写得烂Agent 就像个刚入职的实习生。所以如果你打算认真用这个框架花在工具设计和描述上的时间应该比花在调模型上的时间多。另一个体会是不要追求全自动。很多人一上来就想让 Agent 端到端完成整个流程结果一出错就全盘崩溃。我的做法是在关键节点加人工确认比如执行删除操作前、发送消息前、修改生产配置前都让 Agent 停下来等确认。这样虽然牺牲了一点效率但安全性提升巨大。Agent-Reach 的RequireConfirmation机制就是干这个的用起来很方便。最后分享一个小技巧给 Agent 加一个“反思”步骤。任务执行完之后让 Agent 自己回顾一遍执行过程输出“哪里做得好、哪里可以改进”。这个反思结果可以存下来作为后续任务的参考。我试过之后发现加了反思的 Agent 在重复任务上的表现会逐步提升有点像“经验积累”的效果。实现方式就是在任务结束后追加一轮 LLM 调用prompt 大概是“回顾你刚才的执行过程总结经验和教训”。成本很低但效果意外地好。