Agent-Reach 这个项目起因是我在一次深夜调试里差点把电脑砸了。当时我在做一个多 Agent 协作实验图省事直接上了某全家桶框架结果白天装依赖晚上查报错半夜还得跟版本兼容性搏斗。最后我实在忍不了推倒重来用最小代码量自己写了一个 Agent 运行时把需要的功能一个个以 Skill 的方式塞进去。跑通的那天晚上我在提交记录里写了一句Let the agent reach further.Agent-Reach 这个名字就这么定下来了。先给还没上车的朋友说清楚Agent-Reach 是一个轻量级 AI Agent 运行时核心解决的是一个很朴素的问题——怎么让大模型可靠地触达外部工具、文件、网络和记忆。它不像 LangChain 那样一上来就是几十个模块也不像 Dify 那样得先拖半天可视化流程它更像一组你完全能看懂的代码骨架工具注册、主循环、记忆、沙箱、评测每一块都可以单独替换。如果你正在研究 Agent 架构、想系统学习 agent 开发或者在梳理 agent 开发学习路线而绕不开代码层那这个项目至少能帮你把抽象概念落成看得见、改得动的代码。这个项目适合三类人用 LangChain、CrewAI、Dify 但不太清楚框架背后在干什么的人。框架封装太多反而掩盖了 Agent 运行的底层逻辑你需要一个足够小的参考实现。刚入门做 agent 开发被Agent 是什么harness 和 agent 区别这类问题卡住的新手。名词解释看一百遍不如跟着写一个循环。要把 Agent 接入自己业务系统、对可控性和安全边界特别在意的开发者。沙箱、权限、Token 消耗这些Agent-Reach 都是自己掌控的不会被框架黑盒掉。如果你是这个方向的新人下面我从项目定位开始讲把我踩过的坑、为什么这样设计以及完整可跑的代码全都摊开来说。老手可以直接跳到第 3 章看架构拆解或者第 4 章抄代码。1. Agent-Reach 是什么一次重新思考的产物1.1 先解释名字里的 Reach 到底指什么Agent 圈子里有个词叫harness指的是你用来驾驭Agent 的那层外围代码——循环调用模型、解析工具调用、维护上下文、处理错误和重试。后面我会专门辨析 harness 和 agent 的区别这里你先记住一句话Agent 是大脑harness 是手脚的控制器。Agent-Reach 里的 Reach含义是触达。我在设计它的时候给自己定了一个目标让 Agent 能触达任何需要用到的资源和能力——不管是读取数据库、调用命令行、抓取网页、还是翻历史记忆。很多 Agent 做不好不是因为模型智商不够而是因为触达能力太弱工具只挂了两三个、记忆一塌糊涂、上下文被无效信息占满。Agent-Reach 的所有设计都在回答一个问题怎么让触达更广、更稳、更可控。1.2 三个核心支柱工具触达、记忆触达、安全边界我在重构时把功能需求收敛成三根支柱每个方向都对应一组明确需求支柱解决的核心问题Agent-Reach 的对应模块工具触达Agent 能调用代码、命令、API、网页抓取等外部能力Tool Registry Skills 协议记忆触达Agent 能跨会话记住信息且不爆 Token工作记忆 对话摘要 长期记忆安全边界Agent 只做允许做的事不产生灾难性副作用沙箱执行 权限声明 危险操作拦截这三根支柱决定了 Agent 的天花板。模型只负责决定做什么而能不能做、做到什么粒度、做得安不安全完全是 harness 的事。LangChain、CrewAI 这类框架之所以用起来总觉得隔了一层就是因为他们把这三件事都给你包好了你想改却找不到下手的地方。1.3 Agent-Reach 不是又一个 Agent 框架而是底层运行时现在 Agent 框架太多了LangChain 偏开发工具链CrewAI 偏多角色协作Dify 偏可视化应用搭建。Agent-Reach 的定位跟它们都不一样——它不是一个开箱即用的平台而是一个你拿过去就能看懂、改得动的最小运行时。这带来的好处很实际调试透明。每一条消息、每一次工具调用、每一段记忆摘要都是标准数据结构你在日志里直接看不用查框架源码。依赖极简。核心不强制绑定某个模型 SDK只要实现一个call_model(messages, tools)函数就能跑。可嵌入。你的业务系统里想加一个 AI 能力直接 import 这个运行时写几个 Skill 就是一套完整闭环不需要部署一个重平台。我在实际项目里最爽的时刻是别人还在调框架配置的时候我已经把自定义 Skill 写好跑通了。轻量就是生产力。2. 框架对比与选型思路为什么我不直接选著名框架2.1 主流 Agent 框架各自擅长什么我先给一张对比表方便你快速建立概念。注意这不是说谁好谁坏而是看匹配度。框架核心优势我最不能忍的点适合场景LangChain生态大集成多文档丰富过度封装抽象层太多调试地狱快速做 PoC、需要大量现成集成CrewAI多 Agent 角色扮演思路清晰接近业务语言编排逻辑偏黑盒复杂依赖下 debug 困难团队协作型流程模拟Dify可视化编排非开发者友好对模型管理完整平台绑定深入定制要碰平台代码产品和运营搭 AI 工作流自研运行时全掌控代码即文档能摸到每个细节一切要自己写学习成本前置对可控性、安全、二次开发深度有强需求我这里特别想说一下为什么不用 LangChain。LangChain 的问题不在于它不好而在于它把 Agent 运行时的关键决策都藏起来了。你写一个AgentExecutor它内部帮你处理了工具调用循环但出了问题你看不到中间过程你想改一个记忆策略得先去读它的 memory 模块源代码。对新手来说这会造成一种好像会用但根本没懂的假象。等你真要用它做深度定制时反而要花大量时间绕开框架的默认行为。2.2 自研运行时没有想象中复杂很多人一听自研 Agent 运行时就头大觉得是造轮子。我实际做下来发现一个够用的最小核心核心代码不到 200 行。真正复杂的是上面的 Skill 和各种外围适配器——而这部分本来就应该按你的业务需求来写框架帮不了多少。我推荐给自己动手留一扇门的理由有三个现在的 LLM API 已经足够标准化。OpenAI、Anthropic、国内各家模型平台基本都是一个chat/completions接口返回 messages支持 tool calling。你自己封装一个函数十分钟搞定没必要因为这点胶水引一个重框架。Agent 的核心逻辑是稳定且简单的。主循环就是组装消息 → 调用模型 → 如果有工具调用就执行 → 把结果塞回消息 → 再调模型这个循环几十年内不会变。写一遍它你对 Agent 的理解会彻底落地。可控性就是安全感。业务系统里接入 Agent老板最担心的不是它不会拍马屁而是它会不会乱删数据、乱调接口。自研之后工具注册和沙箱都由你掌控每一行代码都看得见安全审计也不需要求人。2.3 Agent-Reach 选择的实现语言和生态我自己最初用 Python 写的原因是 AI 生态里 Python 工具链最全爬虫、数据处理、脚本调用都顺手。但如果你要用 Rust 重写核心来提高性能和并发安全Agent-Reach 的架构也完全支持——因为核心设计把模型调用和工具执行都抽象成了接口语言只是实现方式。顺带说一句圈子里基于 Rust 语言 AI Agent越来越多。Rust 的优势主要在内存安全、高并发、二进制分发方便。Agent-Reach 的思想放到 Rust 里同样成立Tool Trait Runner Loop 沙箱隔离这跟我在 Python 里做的 Tool Registry run_agent 独立进程执行是一一对应的。语言是工具架构思维才是内核。3. 核心架构拆解Agent-Reach 的设计细节3.1 工具注册与 Skills 协议第一个要写对的设计工具注册是整个 Agent-Reach 的基石。每个工具需要四样东西名字、描述、参数声明、执行函数。描述必须写给模型看因为模型靠描述来决定要不要调用、传什么参数——这个是你 Agent 能力的说明书。下面是我简化的注册实现这段代码你几乎可以直接抄# registry.py from typing import Callable, Optional TOOLS: dict[str, dict] {} def tool(name: str, description: str, parameters: dict): 注册一个工具到全局表供 Agent 调用。 def decorator(func: Callable): TOOLS[name] { name: name, description: description, parameters: parameters, handler: func, } return func return decorator def get_tool_schema() - list[dict]: 生成传给模型的 function calling 结构。 return [ { type: function, function: { name: t[name], description: t[description], parameters: t[parameters], }, } for t in TOOLS.values() ] def execute_tool(name: str, arguments: dict): 按名字执行工具异常兜底统一返回字符串。 if name not in TOOLS: return json.dumps({error: ftool {name} not found}) try: result TOOLS[name][handler](**arguments) return result if isinstance(result, str) else json.dumps(result, ensure_asciiFalse) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse)这里有几个关键设计点都是踩过坑后总结的执行函数强制返回字符串。模型看到的是字符串你无论是返回 dict、list 还是 None统一序列化避免模型拿到奇怪的类型。异常一定要捕获并返回给模型。真实的 Agent 调用中工具报错是常态网络超时、参数不对如果 harness 直接抛异常整个 Agent 就停了。把它作为正常结果返回让模型自己决定怎么调整这才是人机该有的协作方式。参数声明要严格写 JSON Schema。很多模型非常依赖参数声明的规范和示例字段说明写得好工具调用准确率直接上一个台阶。3.2 主循环理解 Agent 执行的所以然Agent 的主循环也就是常说的Agent harness是整个系统的心脏。网上关于harness 和 agent 区别的讨论很多我用人话解释一下Agent 是那个有脑子但没手脚的模型harness 是你给它装上手脚、控制手脚的逻辑。Agent 出主意harness 动手并反馈结果。Agent-Reach 的主循环非常直观# runner.py def run_turn( instruction: str, messages: Optional[list] None, max_steps: int 5, ): 执行一个 Agent 回合循环调用模型 工具直到模型不再请求工具。 messages messages or [{role: user, content: instruction}] for step in range(max_steps): resp call_model(messages, toolsget_tool_schema()) msg normalize_response(resp) # 转成标准消息结构 messages.append(msg) if not msg.get(tool_calls): return msg[content], messages for call in msg[tool_calls]: tool_result execute_tool(call[name], call[arguments]) messages.append({ role: tool, tool_call_id: call[id], content: tool_result, }) return {error: fexceeded {max_steps} tool steps}, messagesmax_steps这个参数非常重要。没有它Agent 一旦陷入工具调用 → 报错 → 再调用的死循环能把你整月 Token 烧光。我默认设 5复杂任务调到 10 就顶天了。我的实际心得是主循环里不要塞太多智能逻辑比如自己尝试修正工具参数、自动重试模型请求。这些看似聪明的逻辑在复杂场景里反而是调试的噩梦。循环只做最笨的事调用、执行、回填、再调用。所有智能都留给模型自己处理你在外面做观察和控制即可出了问题也能一眼看出是模型决策问题还是工具执行问题。3.3 记忆模块三种记忆方式各有各的用处Agent 记忆是热词也是绝大多数 Agent 做不好的一大原因。有些人一上来就整 vector database结果实际需求根本用不上。Agent-Reach 里我把记忆分成三层按需组合成本完全可控记忆类型存储方式解决什么问题成本量级工作记忆当前 messages 列表保持本轮对话的连续性随对话增长需压缩会话摘要定期用模型做总结避免历史会话无限膨胀每次摘要一次模型调用长期记忆结构化存储JSON/DB/向量库跨会话记住偏好、事实、任务状态可定期写入低频率在实际实现里会话摘要非常关键也是最容易忽略的。比如用户连续聊了 20 轮全量塞给模型会让 Token 消耗爆炸而且模型注意力会分散。我的做法是# memory.py def compress_if_needed(messages, budget_chars4000): 如果消息总量超预算就把前半部分摘要。 total sum(len(m[content]) for m in messages) if total budget_chars: return messages history messages[:-2] # 保留最后两轮 summary summarize_messages(history) return [{role: system, content: fprior_summary: {summary}}] messages[-2:]注意摘要要作为system 消息放进去而不是 user这样模型会更倾向于把摘要当成事实背景来参考而非当作当前对话内容。长期记忆我第一版是写成 JSON 文件的简单可靠。只有当你积累了几千条记忆、需要语义检索时才引入向量库。从简单方案起步按需升级这是我做记忆模块的准则。3.4 沙箱与安全边界让 Agent 能干活但不闯祸Agent 安全是很多人担心的问题这个担心非常合理。你让 Agent 能调用就调用能删就删这等于把上了膛的枪交到一个可能产生幻觉的模型手上。Agent-Reach 的安全设计有三层第一层工具白名单。默认不提供execute_any_code、delete_file这类大杀器工具。所有工具都是显式注册的Agent 只能调用注册表里的能力。第二层权限声明。每个工具声明自己的danger_levelsafe / warn / forbidden。执行前harness 检查权限配置forbidden直接拒绝并返回 fixed 的提示语。第三层沙箱执行。高风险工具在隔离环境跑。最简单的方式是放进 Docker 容器里执行甚至独立进程 restricted 配置都行。我不建议裸奔跑直接操作生产环境文件的工具。给你一个权限声明示例tool( namebash_exec_in_sandbox, description在沙箱容器中执行 bash 命令用于代码测试或数据处理, parameters{ type: object, properties: {command: {type: string, description: 要执行的 bash 命令如 ls -la}}, required: [command], }, danger_levelwarn, # 需要人工确认 ) def bash_exec_in_sandbox(command: str): # 这里走 Docker sandbox 的逻辑 return sandbox_run(command, imagepython:3.11)我实际运营下来发现Agent 触发危险操作拦截的次数远比想象中多。比如让它分析一批日志它可能会随手调用一个删除临时文件的命令——这不是模型坏是它的行为覆盖率太广。安全边界不是限制 Agent 的自由而是保护你的系统和数据这句话一定要刻在脑门上。4. 实操过程基于 Agent-Reach 搭建真实场景4.1 场景一把网页保存成 Markdown 的 Skill这是我在 Agent-Reach 生态里最常用的一个 Skill也是网上讨论度很高的用例——Agent 将网页保存成 Markdown 的 skill。我先说下业务背景做信息收集时经常需要把一堆网页快速整理成统一的 Markdown 笔记供后续检索和模型读取。手动复制粘贴十几页效率太低而且格式乱七八糟。用 Agent 来做输入一个 URL它就能抓取、清理、转成标准 Markdown 存到指定目录。下面是完整代码基于 Python 和简洁的库实现# skills/save_page_as_markdown.py import json import urllib.parse from datetime import datetime from pathlib import Path import requests from bs4 import BeautifulSoup from markdownify import markdownify as md tool( namesave_page_as_markdown, description下载指定网页并转换为干净 Markdown保存到 notes 目录。适合保存文章、文档和研究资料。, parameters{ type: object, properties: { url: {type: string, description: 目标网页完整 URL例如 https://example.com/article}, output_dir: {type: string, description: 保存目录默认 notes}, }, required: [url], }, ) def save_page_as_markdown(url: str, output_dir: str notes): # 1. 下载页面 resp requests.get(url, timeout20, headers{User-Agent: Mozilla/5.0}) resp.raise_for_status() # 2. 用 BeautifulSoup 去掉 script/style 等噪音 soup BeautifulSoup(resp.text, html.parser) for tag in soup([script, style, nav, footer, header, aside]): tag.decompose() # 3. 转 Markdown 并压缩空白 content_md md(str(soup.body) if soup.body else soup, heading_styleATX) content_md \n.join(line.rstrip() for line in content_md.splitlines() if line.strip()) # 4. 按域名时间存文件 host urllib.parse.urlparse(url).netloc.replace(www., ) ts datetime.now().strftime(%Y%m%d_%H%M%S) safe_title f{host}_{ts} out_path Path(output_dir) / f{safe_title}.md out_path.parent.mkdir(parentsTrue, exist_okTrue) content f# {url}\n\n 抓取时间: {ts}\n\n{content_md} out_path.write_text(content, encodingutf-8) return json.dumps({status: saved, path: str(out_path), length: len(content_md)}, ensure_asciiFalse)这段代码踩过的坑很值得说UA 头一定要伪装。很多网站对裸 requests 直接返回 403加了浏览器 UA 之后大部分都能过。当然请只抓取你允许抓取的网站合规操作。去噪要按标签批量做。nav、footer、aside这些导航和边栏经常把大量无关文本混进 Markdown不删掉模型会读得很痛苦。压缩空白行。很多网页源码里乱七八糟的换行不处理的话 Markdown 会变得没法看。写完这个工具你可以在主循环里直接让它工作。比如这样提问帮我把 https://example.com/a-blog-post 这个网页保存成 Markdown 文件。Agent 会自己判断调用上面这个工具然后返回保存路径和文件长度。这就完成了从理解指令到触达外部资源并产出文件的完整闭环。4.2 场景二把命令行能力封装成工具让 Agent 变成终端助手Agent 不只是问答机器人。我把它接入终端之后日常很多机械操作都解放了。这里分享一个安全版命令行执行器加上权限校验再挂进 Agent# skills/run_command_safe.py import subprocess ALLOWED_PREFIX (ls, pwd, cat, grep, find, head, tail, wc, echo) tool( namerun_command_safe, description在本地执行白名单内的命令行命令用于查看文件、日志、目录等信息。, parameters{ type: object, properties: {command: {type: string, description: 需执行的命令字符串}}, required: [command], }, ) def run_command_safe(command: str): parts command.split() if not parts or parts[0] not in ALLOWED_PREFIX: return json.dumps({error: fcommand prefix not in whitelist: {parts[0] if parts else empty}, allowed: list(ALLOWED_PREFIX)}, ensure_asciiFalse) result subprocess.run(command, shellTrue, capture_outputTrue, timeout10, textTrue) return json.dumps({stdout: result.stdout[:3000], stderr: result.stderr[:1000]}, ensure_asciiFalse)这个工具的精髓在于白名单 输出截断。白名单保证 Agent 只能执行查看类命令不能执行rm、sudo之类的危险指令输出截断防止一条cat一个大文件就把上下文打爆。这两个机制是终端 Agent 稳定运行的前提。我实际用它做过一个事从一堆日志里找出报错最多的接口、统计关键错误码的出现次数然后让 Agent 自己整理成报告。换成以前这个工作我要写三五个脚本现在一句话的事。4.3 场景三多 Agent 协作模式——执行者 审查者多 Agent也是高频热词。但多 Agent 不是让你开十几个 Agent 排排坐而是明确不同 Agent 的职责边界类似团队里不同角色。Agent-Reach 里我用执行者 审查者模式做过一个代码审查实验简单又实用执行者 Agent读取代码文件输出修改建议或直接生成补丁。审查者 Agent负责复查执行者的输出检查安全问题、逻辑遗漏和风格一致性。两个 Agent 之间传递的是结构化消息而不是互相自由对话。我强烈建议用结构化数据做多 Agent 通信好处是可审查、可记录、可回滚不会像两个碎嘴同事开会一样扯皮。# multi_agent.py def reviewer_loop(candidate_code: str): reviewer_messages [ {role: system, content: 你是资深代码审查者请找出候选代码中的安全问题和逻辑问题输出 JSON 列表。}, {role: user, content: candidate_code}, ] result, _ run_turn( instructionreview the code, messagesreviewer_messages, max_steps2, ) return result这个模式的好处是你可以完全控制评审流程。执行者写代码 → 审查者返回 JSON → 主程序决定是否接受或打回。整个过程不依赖某个框架的角色编排黑盒每一环都跑在你眼皮底下。如果你要面试 Agent 相关岗位这绝对是加分项——很多人只会说概念能演示两个 Agent 之间通过结构化数据协作的就说明是真做过的。4.4 场景四评测集构建验证 Agent 是真的能用做了 Agent 之后最怕的是什么是你觉得它好用别人一试就崩。这个问题的解药是评测集Eval Set。Agent 评测和传统单元测试不一样它测的是模型决策 工具执行的整体链路。Agent-Reach 的评测集设计非常直白每一道题目包含四块字段含义示例instruction用户指令把 https://example.com 存为 Markdownexpected_tools期望调用的工具列表[save_page_as_markdown]expected_output期望的输出特征返回字符串包含 saveddomain场景域web_scrape评测跑起来就是批量执行# evals/run_evals.py from runner import run_turn CASES [ { instruction: 把 https://example.com 保存成 markdown 文件, expected_tools: [save_page_as_markdown], expected_output: saved, }, ] for case in CASES: result, _ run_turn(case[instruction], max_steps5) ok case[expected_output] in result print(f{PASS if ok else FAIL} | {case[instruction][:30]})这里最值得关注的指标是工具调用准确率该调的工具是不是调了、工具参数正确率参数传得对不对、最终任务完成率用户要的东西是不是真拿到了。多跑几十个 case你对 Agent 能力的判断就会从我觉得还行变成它有 92% 的完成率已经可以上线给业务用了。5. 常见问题与排查技巧实录5.1 Agent execution terminated due to error 到底怎么查这个报错是我做 Agent 开发以来见到最多的一条。很多人一看就懵以为是模型出错了。实际上这句话只是 harness 层的兜底真正的错误早就在更底层被吞掉了。排查思路一共三步你照着走就行关闭一切错误吞没。确保execute_tool里捕获异常后把完整异常信息序列化传回模型而不是只返回{error: failed}。把真实的repr(e)和 traceback 截断后放进去模型才知道怎么修正。打开详细日志。在 harness 每个阶段打一条结构化日志模型输入 Token 数、工具名称、参数、执行耗时、返回摘要。出现问题时往回翻日志定位是哪一个工具挂了。最小化复现。把指令拆到最简单一步一步加行为。我见过很多terminated due to error不是代码 bug而是某个工具超时或者返回了超大 JSON 把上下文撑爆了。我见过最离谱的一次某工具返回了一个 200KB 的 JSON模型在处理这个 JSON 时超时了客户端只知道有 error。加了日志和截断方案后问题当天就解决了。5.2 Token 消耗快得惊人先看这几个漏点Token 就是钱烧起来肉疼。我实测下来Agent Token 消耗高的漏点通常有三个工具结果无脑全量塞回。一个cat返回 10000 行全塞进 messages模型每轮都要重新读一遍。解决方式截断 摘要。工具结果超过 3000 字符就做摘要超过 8000 字符只返回文件路径和行数统计。历史消息从不压缩。对话拉长之后旧消息占用大量 Token。这就要用我前面说的compress_if_needed定期摘要。模型选择不当。简单任务用大模型复杂任务也用它当然贵。Agent-Reach 的设计让你可以在 harness 里做模型路由——根据任务类型切换模型。简单任务比如信息提取用轻量模型复杂推理比如代码审查用主力模型成本能省 50% 以上。5.3 模型不好好按 JSON 返回怎么办做 Agent 开发必然遇到模型不老实的情况让它返回 JSON它给你包个 Markdown 代码块让它传工具参数它给你传一个带有注释的 JSON。我的应对办法在系统提示词里给死格式并给出一个可解析的示例。模型对示例的遵循度高得多。写一个宽容解析器。先去代码块符号发现裸 JSON 就直接json.loads失败再尝试ast.literal_eval。兜底逻辑放在 harness 里不影响模型。不要把解析失败当成模型蠢。很多时候是参数 schema 写得含糊。把工具参数 description 写细一点比如说明output_dir 必须是已存在的目录路径不要带结尾斜杠准确率立刻提升。5.4 Agent 面试里高频问题的一次性梳理如果你在准备 Agent 相关岗位的面试下面这几个问题几乎必问。我把参考答案也一并整理出来面试时能用自己的话讲清楚会增加不少说服力问题核心答题思路Agent 是什么是 LLM 驱动的自主决策执行体理解指令 → 拆解任务 → 调用工具 → 根据反馈调整。核心是决策-行动-观察循环。harness 和 agent 区别Agent 是模型决策层harness 是控制层负责循环调用、工具分派、上下文管理、安全策略。比喻Agent 是指挥官harness 是传令兵和监军。Token 是什么Token 是模型文本的最小计算单元约等于 0.7~1 个英文单词或一部分汉字。工具结果、历史消息都消耗 Token需要做压缩和摘要。如何保证 Agent 安全工具白名单、权限分级、沙箱执行、结果审查、危险操作拦截。四个字最小权限。记忆怎么做分级工作记忆上下文、会话摘要压缩历史、长期记忆跨会话存储。按场景选择不要一上来就上向量库。如何评测 Agent构建带期望工具和期望输出的评测集批量跑测统计工具调用准确率、参数正确率、任务完成率。你会发现这些问题只要你亲手跑过一遍 Agent-Reach 的代码全都能从实际经验里答上来而不是背概念。6. 最后再聊点关于 Agent 开发路线的心得我从接触 Agent 开发到现在最大的感触是工具和框架会过时但思想不会。LangChain 会出 v3、v4Dify 会改版但模型决策 工具执行 记忆管理 安全边界这套架构骨架会长期存在。所以我的学习建议不是让你追着框架更新跑而是先写一遍最小 Agent 循环。不用任何框架200 行代码体验一下模型调用、工具注册、结果回填整个流程。再研究一个成熟框架的源码。这个时候你看 LangChain 或 CrewAI 的源码会发现很多机制你已经在最小实现里摸过了理解速度飞快。挑一个业务场景做实操。把网页转 Markdown日志分析代码审查这类具体任务做成 Skill放到真实数据上跑。只有服务过真实的场景你才知道什么是评测、什么是稳定、什么是 Token 成本。最后再回头看架构。此时你再读那些关于 Agent 架构的文章、看多 Agent 编排方案就都水到渠成了。根据我个人经验学习 Agent 开发切忌一上来就框架全家桶、配置一大堆插件。先手动跑通最小集再逐渐加能力这个过程带来的掌控感是任何框架都给不了你的。当你把 Agent-Reach 这种小项目写明白再看那些动不动就上万星的框架你会觉得世界清晰了很多。
Agent-Reach 这个项目起因是我在一次深夜调试里差点把电脑砸了。当时我在做一个多 Agent 协作实验图省事直接上了某全家桶框架结果白天装依赖晚上查报错半夜还得跟版本兼容性搏斗。最后我实在忍不了推倒重来用最小代码量自己写了一个 Agent 运行时把需要的功能一个个以 Skill 的方式塞进去。跑通的那天晚上我在提交记录里写了一句Let the agent reach further.Agent-Reach 这个名字就这么定下来了。先给还没上车的朋友说清楚Agent-Reach 是一个轻量级 AI Agent 运行时核心解决的是一个很朴素的问题——怎么让大模型可靠地触达外部工具、文件、网络和记忆。它不像 LangChain 那样一上来就是几十个模块也不像 Dify 那样得先拖半天可视化流程它更像一组你完全能看懂的代码骨架工具注册、主循环、记忆、沙箱、评测每一块都可以单独替换。如果你正在研究 Agent 架构、想系统学习 agent 开发或者在梳理 agent 开发学习路线而绕不开代码层那这个项目至少能帮你把抽象概念落成看得见、改得动的代码。这个项目适合三类人用 LangChain、CrewAI、Dify 但不太清楚框架背后在干什么的人。框架封装太多反而掩盖了 Agent 运行的底层逻辑你需要一个足够小的参考实现。刚入门做 agent 开发被Agent 是什么harness 和 agent 区别这类问题卡住的新手。名词解释看一百遍不如跟着写一个循环。要把 Agent 接入自己业务系统、对可控性和安全边界特别在意的开发者。沙箱、权限、Token 消耗这些Agent-Reach 都是自己掌控的不会被框架黑盒掉。如果你是这个方向的新人下面我从项目定位开始讲把我踩过的坑、为什么这样设计以及完整可跑的代码全都摊开来说。老手可以直接跳到第 3 章看架构拆解或者第 4 章抄代码。1. Agent-Reach 是什么一次重新思考的产物1.1 先解释名字里的 Reach 到底指什么Agent 圈子里有个词叫harness指的是你用来驾驭Agent 的那层外围代码——循环调用模型、解析工具调用、维护上下文、处理错误和重试。后面我会专门辨析 harness 和 agent 的区别这里你先记住一句话Agent 是大脑harness 是手脚的控制器。Agent-Reach 里的 Reach含义是触达。我在设计它的时候给自己定了一个目标让 Agent 能触达任何需要用到的资源和能力——不管是读取数据库、调用命令行、抓取网页、还是翻历史记忆。很多 Agent 做不好不是因为模型智商不够而是因为触达能力太弱工具只挂了两三个、记忆一塌糊涂、上下文被无效信息占满。Agent-Reach 的所有设计都在回答一个问题怎么让触达更广、更稳、更可控。1.2 三个核心支柱工具触达、记忆触达、安全边界我在重构时把功能需求收敛成三根支柱每个方向都对应一组明确需求支柱解决的核心问题Agent-Reach 的对应模块工具触达Agent 能调用代码、命令、API、网页抓取等外部能力Tool Registry Skills 协议记忆触达Agent 能跨会话记住信息且不爆 Token工作记忆 对话摘要 长期记忆安全边界Agent 只做允许做的事不产生灾难性副作用沙箱执行 权限声明 危险操作拦截这三根支柱决定了 Agent 的天花板。模型只负责决定做什么而能不能做、做到什么粒度、做得安不安全完全是 harness 的事。LangChain、CrewAI 这类框架之所以用起来总觉得隔了一层就是因为他们把这三件事都给你包好了你想改却找不到下手的地方。1.3 Agent-Reach 不是又一个 Agent 框架而是底层运行时现在 Agent 框架太多了LangChain 偏开发工具链CrewAI 偏多角色协作Dify 偏可视化应用搭建。Agent-Reach 的定位跟它们都不一样——它不是一个开箱即用的平台而是一个你拿过去就能看懂、改得动的最小运行时。这带来的好处很实际调试透明。每一条消息、每一次工具调用、每一段记忆摘要都是标准数据结构你在日志里直接看不用查框架源码。依赖极简。核心不强制绑定某个模型 SDK只要实现一个call_model(messages, tools)函数就能跑。可嵌入。你的业务系统里想加一个 AI 能力直接 import 这个运行时写几个 Skill 就是一套完整闭环不需要部署一个重平台。我在实际项目里最爽的时刻是别人还在调框架配置的时候我已经把自定义 Skill 写好跑通了。轻量就是生产力。2. 框架对比与选型思路为什么我不直接选著名框架2.1 主流 Agent 框架各自擅长什么我先给一张对比表方便你快速建立概念。注意这不是说谁好谁坏而是看匹配度。框架核心优势我最不能忍的点适合场景LangChain生态大集成多文档丰富过度封装抽象层太多调试地狱快速做 PoC、需要大量现成集成CrewAI多 Agent 角色扮演思路清晰接近业务语言编排逻辑偏黑盒复杂依赖下 debug 困难团队协作型流程模拟Dify可视化编排非开发者友好对模型管理完整平台绑定深入定制要碰平台代码产品和运营搭 AI 工作流自研运行时全掌控代码即文档能摸到每个细节一切要自己写学习成本前置对可控性、安全、二次开发深度有强需求我这里特别想说一下为什么不用 LangChain。LangChain 的问题不在于它不好而在于它把 Agent 运行时的关键决策都藏起来了。你写一个AgentExecutor它内部帮你处理了工具调用循环但出了问题你看不到中间过程你想改一个记忆策略得先去读它的 memory 模块源代码。对新手来说这会造成一种好像会用但根本没懂的假象。等你真要用它做深度定制时反而要花大量时间绕开框架的默认行为。2.2 自研运行时没有想象中复杂很多人一听自研 Agent 运行时就头大觉得是造轮子。我实际做下来发现一个够用的最小核心核心代码不到 200 行。真正复杂的是上面的 Skill 和各种外围适配器——而这部分本来就应该按你的业务需求来写框架帮不了多少。我推荐给自己动手留一扇门的理由有三个现在的 LLM API 已经足够标准化。OpenAI、Anthropic、国内各家模型平台基本都是一个chat/completions接口返回 messages支持 tool calling。你自己封装一个函数十分钟搞定没必要因为这点胶水引一个重框架。Agent 的核心逻辑是稳定且简单的。主循环就是组装消息 → 调用模型 → 如果有工具调用就执行 → 把结果塞回消息 → 再调模型这个循环几十年内不会变。写一遍它你对 Agent 的理解会彻底落地。可控性就是安全感。业务系统里接入 Agent老板最担心的不是它不会拍马屁而是它会不会乱删数据、乱调接口。自研之后工具注册和沙箱都由你掌控每一行代码都看得见安全审计也不需要求人。2.3 Agent-Reach 选择的实现语言和生态我自己最初用 Python 写的原因是 AI 生态里 Python 工具链最全爬虫、数据处理、脚本调用都顺手。但如果你要用 Rust 重写核心来提高性能和并发安全Agent-Reach 的架构也完全支持——因为核心设计把模型调用和工具执行都抽象成了接口语言只是实现方式。顺带说一句圈子里基于 Rust 语言 AI Agent越来越多。Rust 的优势主要在内存安全、高并发、二进制分发方便。Agent-Reach 的思想放到 Rust 里同样成立Tool Trait Runner Loop 沙箱隔离这跟我在 Python 里做的 Tool Registry run_agent 独立进程执行是一一对应的。语言是工具架构思维才是内核。3. 核心架构拆解Agent-Reach 的设计细节3.1 工具注册与 Skills 协议第一个要写对的设计工具注册是整个 Agent-Reach 的基石。每个工具需要四样东西名字、描述、参数声明、执行函数。描述必须写给模型看因为模型靠描述来决定要不要调用、传什么参数——这个是你 Agent 能力的说明书。下面是我简化的注册实现这段代码你几乎可以直接抄# registry.py from typing import Callable, Optional TOOLS: dict[str, dict] {} def tool(name: str, description: str, parameters: dict): 注册一个工具到全局表供 Agent 调用。 def decorator(func: Callable): TOOLS[name] { name: name, description: description, parameters: parameters, handler: func, } return func return decorator def get_tool_schema() - list[dict]: 生成传给模型的 function calling 结构。 return [ { type: function, function: { name: t[name], description: t[description], parameters: t[parameters], }, } for t in TOOLS.values() ] def execute_tool(name: str, arguments: dict): 按名字执行工具异常兜底统一返回字符串。 if name not in TOOLS: return json.dumps({error: ftool {name} not found}) try: result TOOLS[name][handler](**arguments) return result if isinstance(result, str) else json.dumps(result, ensure_asciiFalse) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse)这里有几个关键设计点都是踩过坑后总结的执行函数强制返回字符串。模型看到的是字符串你无论是返回 dict、list 还是 None统一序列化避免模型拿到奇怪的类型。异常一定要捕获并返回给模型。真实的 Agent 调用中工具报错是常态网络超时、参数不对如果 harness 直接抛异常整个 Agent 就停了。把它作为正常结果返回让模型自己决定怎么调整这才是人机该有的协作方式。参数声明要严格写 JSON Schema。很多模型非常依赖参数声明的规范和示例字段说明写得好工具调用准确率直接上一个台阶。3.2 主循环理解 Agent 执行的所以然Agent 的主循环也就是常说的Agent harness是整个系统的心脏。网上关于harness 和 agent 区别的讨论很多我用人话解释一下Agent 是那个有脑子但没手脚的模型harness 是你给它装上手脚、控制手脚的逻辑。Agent 出主意harness 动手并反馈结果。Agent-Reach 的主循环非常直观# runner.py def run_turn( instruction: str, messages: Optional[list] None, max_steps: int 5, ): 执行一个 Agent 回合循环调用模型 工具直到模型不再请求工具。 messages messages or [{role: user, content: instruction}] for step in range(max_steps): resp call_model(messages, toolsget_tool_schema()) msg normalize_response(resp) # 转成标准消息结构 messages.append(msg) if not msg.get(tool_calls): return msg[content], messages for call in msg[tool_calls]: tool_result execute_tool(call[name], call[arguments]) messages.append({ role: tool, tool_call_id: call[id], content: tool_result, }) return {error: fexceeded {max_steps} tool steps}, messagesmax_steps这个参数非常重要。没有它Agent 一旦陷入工具调用 → 报错 → 再调用的死循环能把你整月 Token 烧光。我默认设 5复杂任务调到 10 就顶天了。我的实际心得是主循环里不要塞太多智能逻辑比如自己尝试修正工具参数、自动重试模型请求。这些看似聪明的逻辑在复杂场景里反而是调试的噩梦。循环只做最笨的事调用、执行、回填、再调用。所有智能都留给模型自己处理你在外面做观察和控制即可出了问题也能一眼看出是模型决策问题还是工具执行问题。3.3 记忆模块三种记忆方式各有各的用处Agent 记忆是热词也是绝大多数 Agent 做不好的一大原因。有些人一上来就整 vector database结果实际需求根本用不上。Agent-Reach 里我把记忆分成三层按需组合成本完全可控记忆类型存储方式解决什么问题成本量级工作记忆当前 messages 列表保持本轮对话的连续性随对话增长需压缩会话摘要定期用模型做总结避免历史会话无限膨胀每次摘要一次模型调用长期记忆结构化存储JSON/DB/向量库跨会话记住偏好、事实、任务状态可定期写入低频率在实际实现里会话摘要非常关键也是最容易忽略的。比如用户连续聊了 20 轮全量塞给模型会让 Token 消耗爆炸而且模型注意力会分散。我的做法是# memory.py def compress_if_needed(messages, budget_chars4000): 如果消息总量超预算就把前半部分摘要。 total sum(len(m[content]) for m in messages) if total budget_chars: return messages history messages[:-2] # 保留最后两轮 summary summarize_messages(history) return [{role: system, content: fprior_summary: {summary}}] messages[-2:]注意摘要要作为system 消息放进去而不是 user这样模型会更倾向于把摘要当成事实背景来参考而非当作当前对话内容。长期记忆我第一版是写成 JSON 文件的简单可靠。只有当你积累了几千条记忆、需要语义检索时才引入向量库。从简单方案起步按需升级这是我做记忆模块的准则。3.4 沙箱与安全边界让 Agent 能干活但不闯祸Agent 安全是很多人担心的问题这个担心非常合理。你让 Agent 能调用就调用能删就删这等于把上了膛的枪交到一个可能产生幻觉的模型手上。Agent-Reach 的安全设计有三层第一层工具白名单。默认不提供execute_any_code、delete_file这类大杀器工具。所有工具都是显式注册的Agent 只能调用注册表里的能力。第二层权限声明。每个工具声明自己的danger_levelsafe / warn / forbidden。执行前harness 检查权限配置forbidden直接拒绝并返回 fixed 的提示语。第三层沙箱执行。高风险工具在隔离环境跑。最简单的方式是放进 Docker 容器里执行甚至独立进程 restricted 配置都行。我不建议裸奔跑直接操作生产环境文件的工具。给你一个权限声明示例tool( namebash_exec_in_sandbox, description在沙箱容器中执行 bash 命令用于代码测试或数据处理, parameters{ type: object, properties: {command: {type: string, description: 要执行的 bash 命令如 ls -la}}, required: [command], }, danger_levelwarn, # 需要人工确认 ) def bash_exec_in_sandbox(command: str): # 这里走 Docker sandbox 的逻辑 return sandbox_run(command, imagepython:3.11)我实际运营下来发现Agent 触发危险操作拦截的次数远比想象中多。比如让它分析一批日志它可能会随手调用一个删除临时文件的命令——这不是模型坏是它的行为覆盖率太广。安全边界不是限制 Agent 的自由而是保护你的系统和数据这句话一定要刻在脑门上。4. 实操过程基于 Agent-Reach 搭建真实场景4.1 场景一把网页保存成 Markdown 的 Skill这是我在 Agent-Reach 生态里最常用的一个 Skill也是网上讨论度很高的用例——Agent 将网页保存成 Markdown 的 skill。我先说下业务背景做信息收集时经常需要把一堆网页快速整理成统一的 Markdown 笔记供后续检索和模型读取。手动复制粘贴十几页效率太低而且格式乱七八糟。用 Agent 来做输入一个 URL它就能抓取、清理、转成标准 Markdown 存到指定目录。下面是完整代码基于 Python 和简洁的库实现# skills/save_page_as_markdown.py import json import urllib.parse from datetime import datetime from pathlib import Path import requests from bs4 import BeautifulSoup from markdownify import markdownify as md tool( namesave_page_as_markdown, description下载指定网页并转换为干净 Markdown保存到 notes 目录。适合保存文章、文档和研究资料。, parameters{ type: object, properties: { url: {type: string, description: 目标网页完整 URL例如 https://example.com/article}, output_dir: {type: string, description: 保存目录默认 notes}, }, required: [url], }, ) def save_page_as_markdown(url: str, output_dir: str notes): # 1. 下载页面 resp requests.get(url, timeout20, headers{User-Agent: Mozilla/5.0}) resp.raise_for_status() # 2. 用 BeautifulSoup 去掉 script/style 等噪音 soup BeautifulSoup(resp.text, html.parser) for tag in soup([script, style, nav, footer, header, aside]): tag.decompose() # 3. 转 Markdown 并压缩空白 content_md md(str(soup.body) if soup.body else soup, heading_styleATX) content_md \n.join(line.rstrip() for line in content_md.splitlines() if line.strip()) # 4. 按域名时间存文件 host urllib.parse.urlparse(url).netloc.replace(www., ) ts datetime.now().strftime(%Y%m%d_%H%M%S) safe_title f{host}_{ts} out_path Path(output_dir) / f{safe_title}.md out_path.parent.mkdir(parentsTrue, exist_okTrue) content f# {url}\n\n 抓取时间: {ts}\n\n{content_md} out_path.write_text(content, encodingutf-8) return json.dumps({status: saved, path: str(out_path), length: len(content_md)}, ensure_asciiFalse)这段代码踩过的坑很值得说UA 头一定要伪装。很多网站对裸 requests 直接返回 403加了浏览器 UA 之后大部分都能过。当然请只抓取你允许抓取的网站合规操作。去噪要按标签批量做。nav、footer、aside这些导航和边栏经常把大量无关文本混进 Markdown不删掉模型会读得很痛苦。压缩空白行。很多网页源码里乱七八糟的换行不处理的话 Markdown 会变得没法看。写完这个工具你可以在主循环里直接让它工作。比如这样提问帮我把 https://example.com/a-blog-post 这个网页保存成 Markdown 文件。Agent 会自己判断调用上面这个工具然后返回保存路径和文件长度。这就完成了从理解指令到触达外部资源并产出文件的完整闭环。4.2 场景二把命令行能力封装成工具让 Agent 变成终端助手Agent 不只是问答机器人。我把它接入终端之后日常很多机械操作都解放了。这里分享一个安全版命令行执行器加上权限校验再挂进 Agent# skills/run_command_safe.py import subprocess ALLOWED_PREFIX (ls, pwd, cat, grep, find, head, tail, wc, echo) tool( namerun_command_safe, description在本地执行白名单内的命令行命令用于查看文件、日志、目录等信息。, parameters{ type: object, properties: {command: {type: string, description: 需执行的命令字符串}}, required: [command], }, ) def run_command_safe(command: str): parts command.split() if not parts or parts[0] not in ALLOWED_PREFIX: return json.dumps({error: fcommand prefix not in whitelist: {parts[0] if parts else empty}, allowed: list(ALLOWED_PREFIX)}, ensure_asciiFalse) result subprocess.run(command, shellTrue, capture_outputTrue, timeout10, textTrue) return json.dumps({stdout: result.stdout[:3000], stderr: result.stderr[:1000]}, ensure_asciiFalse)这个工具的精髓在于白名单 输出截断。白名单保证 Agent 只能执行查看类命令不能执行rm、sudo之类的危险指令输出截断防止一条cat一个大文件就把上下文打爆。这两个机制是终端 Agent 稳定运行的前提。我实际用它做过一个事从一堆日志里找出报错最多的接口、统计关键错误码的出现次数然后让 Agent 自己整理成报告。换成以前这个工作我要写三五个脚本现在一句话的事。4.3 场景三多 Agent 协作模式——执行者 审查者多 Agent也是高频热词。但多 Agent 不是让你开十几个 Agent 排排坐而是明确不同 Agent 的职责边界类似团队里不同角色。Agent-Reach 里我用执行者 审查者模式做过一个代码审查实验简单又实用执行者 Agent读取代码文件输出修改建议或直接生成补丁。审查者 Agent负责复查执行者的输出检查安全问题、逻辑遗漏和风格一致性。两个 Agent 之间传递的是结构化消息而不是互相自由对话。我强烈建议用结构化数据做多 Agent 通信好处是可审查、可记录、可回滚不会像两个碎嘴同事开会一样扯皮。# multi_agent.py def reviewer_loop(candidate_code: str): reviewer_messages [ {role: system, content: 你是资深代码审查者请找出候选代码中的安全问题和逻辑问题输出 JSON 列表。}, {role: user, content: candidate_code}, ] result, _ run_turn( instructionreview the code, messagesreviewer_messages, max_steps2, ) return result这个模式的好处是你可以完全控制评审流程。执行者写代码 → 审查者返回 JSON → 主程序决定是否接受或打回。整个过程不依赖某个框架的角色编排黑盒每一环都跑在你眼皮底下。如果你要面试 Agent 相关岗位这绝对是加分项——很多人只会说概念能演示两个 Agent 之间通过结构化数据协作的就说明是真做过的。4.4 场景四评测集构建验证 Agent 是真的能用做了 Agent 之后最怕的是什么是你觉得它好用别人一试就崩。这个问题的解药是评测集Eval Set。Agent 评测和传统单元测试不一样它测的是模型决策 工具执行的整体链路。Agent-Reach 的评测集设计非常直白每一道题目包含四块字段含义示例instruction用户指令把 https://example.com 存为 Markdownexpected_tools期望调用的工具列表[save_page_as_markdown]expected_output期望的输出特征返回字符串包含 saveddomain场景域web_scrape评测跑起来就是批量执行# evals/run_evals.py from runner import run_turn CASES [ { instruction: 把 https://example.com 保存成 markdown 文件, expected_tools: [save_page_as_markdown], expected_output: saved, }, ] for case in CASES: result, _ run_turn(case[instruction], max_steps5) ok case[expected_output] in result print(f{PASS if ok else FAIL} | {case[instruction][:30]})这里最值得关注的指标是工具调用准确率该调的工具是不是调了、工具参数正确率参数传得对不对、最终任务完成率用户要的东西是不是真拿到了。多跑几十个 case你对 Agent 能力的判断就会从我觉得还行变成它有 92% 的完成率已经可以上线给业务用了。5. 常见问题与排查技巧实录5.1 Agent execution terminated due to error 到底怎么查这个报错是我做 Agent 开发以来见到最多的一条。很多人一看就懵以为是模型出错了。实际上这句话只是 harness 层的兜底真正的错误早就在更底层被吞掉了。排查思路一共三步你照着走就行关闭一切错误吞没。确保execute_tool里捕获异常后把完整异常信息序列化传回模型而不是只返回{error: failed}。把真实的repr(e)和 traceback 截断后放进去模型才知道怎么修正。打开详细日志。在 harness 每个阶段打一条结构化日志模型输入 Token 数、工具名称、参数、执行耗时、返回摘要。出现问题时往回翻日志定位是哪一个工具挂了。最小化复现。把指令拆到最简单一步一步加行为。我见过很多terminated due to error不是代码 bug而是某个工具超时或者返回了超大 JSON 把上下文撑爆了。我见过最离谱的一次某工具返回了一个 200KB 的 JSON模型在处理这个 JSON 时超时了客户端只知道有 error。加了日志和截断方案后问题当天就解决了。5.2 Token 消耗快得惊人先看这几个漏点Token 就是钱烧起来肉疼。我实测下来Agent Token 消耗高的漏点通常有三个工具结果无脑全量塞回。一个cat返回 10000 行全塞进 messages模型每轮都要重新读一遍。解决方式截断 摘要。工具结果超过 3000 字符就做摘要超过 8000 字符只返回文件路径和行数统计。历史消息从不压缩。对话拉长之后旧消息占用大量 Token。这就要用我前面说的compress_if_needed定期摘要。模型选择不当。简单任务用大模型复杂任务也用它当然贵。Agent-Reach 的设计让你可以在 harness 里做模型路由——根据任务类型切换模型。简单任务比如信息提取用轻量模型复杂推理比如代码审查用主力模型成本能省 50% 以上。5.3 模型不好好按 JSON 返回怎么办做 Agent 开发必然遇到模型不老实的情况让它返回 JSON它给你包个 Markdown 代码块让它传工具参数它给你传一个带有注释的 JSON。我的应对办法在系统提示词里给死格式并给出一个可解析的示例。模型对示例的遵循度高得多。写一个宽容解析器。先去代码块符号发现裸 JSON 就直接json.loads失败再尝试ast.literal_eval。兜底逻辑放在 harness 里不影响模型。不要把解析失败当成模型蠢。很多时候是参数 schema 写得含糊。把工具参数 description 写细一点比如说明output_dir 必须是已存在的目录路径不要带结尾斜杠准确率立刻提升。5.4 Agent 面试里高频问题的一次性梳理如果你在准备 Agent 相关岗位的面试下面这几个问题几乎必问。我把参考答案也一并整理出来面试时能用自己的话讲清楚会增加不少说服力问题核心答题思路Agent 是什么是 LLM 驱动的自主决策执行体理解指令 → 拆解任务 → 调用工具 → 根据反馈调整。核心是决策-行动-观察循环。harness 和 agent 区别Agent 是模型决策层harness 是控制层负责循环调用、工具分派、上下文管理、安全策略。比喻Agent 是指挥官harness 是传令兵和监军。Token 是什么Token 是模型文本的最小计算单元约等于 0.7~1 个英文单词或一部分汉字。工具结果、历史消息都消耗 Token需要做压缩和摘要。如何保证 Agent 安全工具白名单、权限分级、沙箱执行、结果审查、危险操作拦截。四个字最小权限。记忆怎么做分级工作记忆上下文、会话摘要压缩历史、长期记忆跨会话存储。按场景选择不要一上来就上向量库。如何评测 Agent构建带期望工具和期望输出的评测集批量跑测统计工具调用准确率、参数正确率、任务完成率。你会发现这些问题只要你亲手跑过一遍 Agent-Reach 的代码全都能从实际经验里答上来而不是背概念。6. 最后再聊点关于 Agent 开发路线的心得我从接触 Agent 开发到现在最大的感触是工具和框架会过时但思想不会。LangChain 会出 v3、v4Dify 会改版但模型决策 工具执行 记忆管理 安全边界这套架构骨架会长期存在。所以我的学习建议不是让你追着框架更新跑而是先写一遍最小 Agent 循环。不用任何框架200 行代码体验一下模型调用、工具注册、结果回填整个流程。再研究一个成熟框架的源码。这个时候你看 LangChain 或 CrewAI 的源码会发现很多机制你已经在最小实现里摸过了理解速度飞快。挑一个业务场景做实操。把网页转 Markdown日志分析代码审查这类具体任务做成 Skill放到真实数据上跑。只有服务过真实的场景你才知道什么是评测、什么是稳定、什么是 Token 成本。最后再回头看架构。此时你再读那些关于 Agent 架构的文章、看多 Agent 编排方案就都水到渠成了。根据我个人经验学习 Agent 开发切忌一上来就框架全家桶、配置一大堆插件。先手动跑通最小集再逐渐加能力这个过程带来的掌控感是任何框架都给不了你的。当你把 Agent-Reach 这种小项目写明白再看那些动不动就上万星的框架你会觉得世界清晰了很多。
