REA Agent实战：从npx初始化到应用分析闭环

1. 先把REA这件事想明白再动手敲命令1.1 一次“应用分析”为什么需要Agent而不是一段Prompt很多人第一次听到“应用分析”脑子里浮现的是丢一段长提示词给大模型让它输出一份功能清单、用户反馈和竞品对比。这种玩法在Demo阶段确实爽但你只要真拿它去分析一个应用很快就会撞墙应用信息分散在多个来源里有的在公开页面上有的在用户评论里有的在更新日志里一次上下文根本塞不下更要命的是你没法保证模型说的是真话它会把“我记得这个应用有XX功能”和“我查到这个应用有XX功能”混在一起输出看起来头头是道实际上有一半是编的。REA这套范式的价值就在这里。REA是Reasoning-Execution-Action的缩写核心思路是把“模型推理”和“工具执行”拆成两个显式的、可审计的步骤一轮一轮往前推直到任务收敛。第一轮模型基于任务目标和已知信息做推理产出一份结构化的行动计划明确说清楚“我要查什么、用什么工具查、参数是什么”第二轮执行器严格按照这份计划去调用工具把真实结果拿回来第三轮把观察结果写回状态模型再判断是继续下一轮还是收尾出报告。整个过程里模型的每一次“想”都落在磁盘上每一次“做”都有对应的返回你随时可以回放某一轮它到底为什么这么决策。我第一次用这套结构做应用分析最直观的感受不是效果变好了而是能 debug 了。以前模型输出一段不对劲的内容你只能反复改提示词靠玄学现在你可以打开step-03.reason.json看到它在第3轮误判了“用户反馈里提到的崩溃问题属于历史版本”你直接补一条工具返回的版本字段问题就解决了。这种可干预性是纯提示词方案永远给不了的。1.2 Reason、Execution、Action三个环节各自在干什么把REA拆开看三个环节的职责边界非常清晰理解这一点你后面读配置文件和中间产物才不会懵。Reason环节是整个循环的大脑。输入是“任务目标 历史轮次的观察摘要 可用工具清单”输出是一份严格符合schema的JSON里面至少要包含三样东西当前对任务的判断、下一步意图、以及要调用的工具名和参数。注意这里的关键词是“严格符合schema”不是自由文本。为什么一定要结构化因为自由文本没法被程序可靠地解析一旦解析失败整条链路就断了。我在实际项目里踩过这个坑早期用自然语言描述下一步动作模型有时候写“我打算先查一下应用的下载量”有时候写“先查询下载量数据”解析器得写一堆正则兜底最后还是经常挂。改成强制JSON schema之后稳定性提升了一个量级。Execution环节是手脚它完全不懂业务只做三件事校验工具名是否在白名单里、校验参数是否符合工具的入参定义、调用工具并把结果原样返回。这里必须强调“完全不懂业务”这一点很多人喜欢在执行器里加业务判断比如“如果查的是评论就先过滤掉广告”结果就是执行器越来越臃肿模型的行为越来越不可预测。执行器就该是一个愚蠢但可靠的调度器。Action环节严格说不是一个独立步骤而是把执行结果写回状态、更新步数、判断是否终止的逻辑层。它要处理的事情包括把观察结果截断到合理长度几百条评论全塞回去会直接撑爆上下文、更新已完成的子任务清单、检查是否触发终止条件步数上限、目标达成、连续无进展。这个环节最容易被忽视但它直接决定了你的Agent是跑三轮出结果还是跑二十轮烧光预算。1.3 为什么我不建议你从零手写这套循环有人会说REA循环这么简单我自己写个while循环不就完了理论上没错我第一版就是手写的两百行代码跑得也挺欢。但真到要交付的时候你会发现缺的东西全是“非功能需求”状态怎么持久化、断点怎么续跑、工具调用失败了怎么重试、每次运行的中间产物怎么归档、多轮对话的上下文怎么压缩。这些加起来少说是两三千行的工程量而且每换一个业务场景就要重写一遍。rea-agents这个脚手架的价值不在于它多聪明而在于它把这些脏活累活在初始化阶段就帮你铺好了。npx rea-agents setup一条命令跑完你会得到一个带默认配置、示例工具、运行产物目录、以及一个能跑通的最小demo的工程骨架。你要做的只是改配置、换工具、调提示词。这也是我建议新手从脚手架入手的原因先让它跑起来看清楚一轮完整循环的输入输出长什么样再去改比你对着文档啃三天强得多。提示脚手架生成的默认配置是“能跑通”级别不是“能上生产”级别。默认步数上限、超时时间、日志粒度都偏保守第一次跑通之后一定要按自己的场景重新调一遍这部分我在第6节会详细说。2. 五分钟跑通npx rea-agents setup 的完整实操2.1 动手之前先把这几个前置条件确认了在敲命令之前有几个环境项必须先确认不然你会在初始化阶段就卡住而且报错信息通常很含糊浪费时间。第一是Node版本。这类基于npx分发的脚手架普遍要求 Node 18 以上部分依赖会用 ES Module 的顶层 awaitNode 16 直接崩。跑node -v确认一下如果低于18用版本管理工具切一个别硬扛。第二是包管理缓存和网络。npx 每次执行会先检查本地缓存没有就去拉取。第一次跑会慢一些属于正常现象。如果你所在的环境对出网有限制建议提前把依赖装到本地用npx --no-install的方式跑具体做法是先在项目目录里npm i -D rea-agents之后所有命令都加--no-install既快又稳。第三是模型访问凭证。REA循环里Reason环节需要调用模型所以你必须准备好对应的 API Key 和 endpoint。脚手架一般读取环境变量常见的是REA_MODEL_API_KEY和REA_MODEL_BASE_URL这两个。我习惯在项目根目录建一个.env.local写进去之后在.gitignore里排除掉避免误提交。检查项最低要求验证命令常见坑Node 版本18.xnode -v16.x 下报Unexpected tokennpm 版本9.xnpm -v过低时 npx 解析包名失败磁盘可用空间500MBdf -h运行产物累积很快模型凭证有效 Key见下变量名写错导致空值透传出网能力可访问包源npm ping内网环境需配私有源凭证这块我建议加一个自检脚本在跑 setup 之前先手动验证一次模型是否可达。因为 setup 阶段通常也会做一次“连通性测试”如果凭证有问题它会在初始化末尾抛一个笼统的失败你还得回头排查半天。自己先测一遍能省下十几分钟。# 简单的连通性自检替换成你自己的 endpoint 和模型名 curl -s -X POST $REA_MODEL_BASE_URL/chat/completions \ -H Authorization: Bearer $REA_MODEL_API_KEY \ -H Content-Type: application/json \ -d {model:YOUR_MODEL_NAME,messages:[{role:user,content:ping}],max_tokens:8}返回里有正常的choices字段说明链路是通的可以往下走了。2.2 setup交互流程逐条拆解真正执行npx rea-agents setup的时候它是个交互式流程会连着问你几个问题。我把常见的问题序列和我的选择理由一条条说清楚你照着自己的场景选就行。npx rea-agents setup第一个问题通常是项目名和目录。直接回车会用当前目录名作为项目名。我一般会显式输入一个带业务含义的名字比如app-analysis-demo因为这个名字会写进配置文件的project字段后面运行产物目录也是按它来组织的。名字起得随意几个月后回头看runs/目录你会一脸懵。第二个问题是选择Agent模板。脚手架一般内置几个比如analyst分析型偏重多轮检索与归纳、coder偏重代码读写、researcher偏重长链路搜索。做应用分析选analyst就够了它的默认提示词里已经内置了“先收集事实、再做判断、最后出结构化报告”的约束省得你从零写。第三个问题是模型配置。这里会让你填模型名有的版本还会问 temperature 和 max tokens。我的经验是Reason环节的 temperature 一定要压到 0.2 以下。因为这个环节的输出要被程序解析成JSON温度高了它会开始“自由发挥”偶尔给你加个注释、加个省略号解析直接跪。至于 max tokens先设个 2048 保底跑通了再往上调。第四个问题一般是工具选择。脚手架会列出一批内置工具让你勾选比如http_fetch、file_read、file_write、search、shell。这里有个原则只勾你这一轮真正要用的。工具清单越长Reason环节的提示词越长模型选错工具的概率越高token 消耗也越大。做应用分析我第一轮只勾http_fetch抓页面、file_write存中间产物、file_read读上一次的结果三个够用了。最后一步它通常会问要不要生成示例任务。强烈建议选是。示例任务里一般包含一个可直接运行的输入文件和一份预期输出结构你第一次跑通就靠它。跑通之后再改造成自己的任务比从空白开始快得多。整个过程顺利的话两分钟内结束。结束后终端会打印一段摘要列出生成的目录、需要你手动填的配置项、以及建议的执行命令。这段摘要建议直接复制存到笔记里后面调试经常要对照。2.3 生成目录拆开看每个文件都别浪费setup 跑完之后ls -la看一眼典型的目录结构大致是这样不同版本命名可能有出入但职责划分基本一致app-analysis-demo/ ├── .env.local # 凭证记得 gitignore ├── .rea/ │ ├── config.yaml # 全局运行时配置 │ └── schema/ │ └── action.schema.json # Reason输出的JSON schema ├── agents/ │ └── analyst.agent.yaml # Agent定义提示词、工具白名单、终止条件 ├── tools/ │ ├── http_fetch.tool.yaml │ └── file_write.tool.yaml ├── tasks/ │ └── sample.task.yaml # 示例任务可直接跑 └── runs/ # 运行产物空的先说.rea/config.yaml这是全局配置管的是“运行时行为”步数上限、超时、日志级别、产物保留策略。我通常第一步就改两个值max_steps从默认的 20 调到 10log_level从info调到debug。前者防止跑飞烧钱后者让你能看到每一轮的完整提示词调试期非常有用。# .rea/config.yaml 关键片段 project: app-analysis-demo runtime: max_steps: 10 # 步数上限超了强制终止 step_timeout_ms: 60000 # 单步超时 log_level: debug # 调试期开 debug artifacts: keep_last_n_runs: 20 # 只保留最近20次运行产物 truncate_observation: 4000 # 观察结果截断长度再说agents/analyst.agent.yaml这个文件是整条链路的核心我建议你第一次就把它从头读到尾。它至少包含四块内容系统提示词定义角色和输出纪律、工具白名单、终止条件、以及输出格式约束。系统提示词里通常会有类似“在信息不足时优先调用检索工具不要凭记忆作答”这样的硬约束这条别删它是抑制幻觉的第一道闸门。tasks/sample.task.yaml是输入模板一般长这样name: sample-app-analysis goal: | 分析目标应用的基础信息、核心功能、用户反馈中的主要问题 产出一份不超过 1500 字的结构化分析报告。 inputs: target: example-app dimensions: - 功能清单 - 用户评价 - 更新节奏 output: format: markdown sections: - 概览 - 功能拆解 - 用户反馈摘要 - 风险与机会看到dimensions这个字段了吗这就是我前面说的“把任务拆成可执行的子目标”。模型拿到这个列表Reason环节就会围绕每个维度去规划检索动作而不是漫无目的地乱查。这个字段设计得好不好直接决定生成报告的质量。3. REA循环的核心机制掰开揉碎讲3.1 Reason环节结构化输出是稳定性的命根子Reason环节的产物是整条链路上唯一需要被程序严格解析的东西所以它的设计必须围绕“可解析”来做。脚手架通常会在.rea/schema/action.schema.json里定义一个 action 对象最少包含这几个字段{ type: object, required: [thought, action, tool, args], properties: { thought: { type: string, description: 当前对任务进展的判断一句话说清 }, action: { type: string, enum: [call_tool, finish, ask_human] }, tool: { type: string, description: 当action为call_tool时必填 }, args: { type: object, description: 工具入参 }, progress: { type: array, items: {type: string}, description: 已完成子任务清单用于收敛判断 } } }这里有几个设计细节值得说。action用枚举而不是自由字符串是为了让执行器能穷举分支避免出现“模型发明了一个新动作类型”这种崩盘情况。progress这个字段特别有用它让模型自己维护一份“已经查过什么”的清单每一轮都把这份清单带上模型就不会反复查同一个东西。我做过对比加了progress字段之后相同任务的重复工具调用次数下降了大约四成。还有一个坑要提醒不要在schema里用additionalProperties: false之外的强约束把模型逼死。有些版本的模型遇到复杂schema会开始输出不完整的JSON或者干脆输出一段解释文字。稳妥做法是在Agent配置里加一条“只输出JSON不要任何前后缀说明”同时让解析层带一层宽松兜底先把输出里的第一个{到最后一个}之间的内容截出来再做解析。这层兜底能救回大概百分之几的失败case别省。提示调试期一定要把每轮 Reason 的原始输出落盘。我见过太多人只看解析后的结果然后对着一个空对象抓耳挠腮其实原始输出里模型已经写了一段“抱歉我无法完成”一看就知道是提示词约束不够或者工具描述有歧义。3.2 Execution环节工具描述写得越像说明书模型选得越准执行器本身没什么好讲的它是纯机械的。真正决定这一环质量的是工具的元数据也就是tools/*.tool.yaml里怎么描述这个工具。我见过最糟糕的工具描述就一句话“fetch a url”。模型看到这个描述根本不知道它适不适合当前场景经常拿它去抓需要登录的页面然后拿到一堆重定向HTML白瞎一轮。好的工具描述应该包含这个工具能做什么、不能做什么、参数的含义和格式、返回什么结构、典型调用示例。# tools/http_fetch.tool.yaml name: http_fetch description: | 抓取一个公开可访问的网页并返回正文纯文本。 适用公开的应用介绍页、更新日志页、公开评测文章。 不适用需要登录态的页面、动态渲染的SPA页面会拿不到内容。 返回{ status: 200, title: ..., text: ... } 其中 text 已去除HTML标签长度上限 8000 字符。 parameters: type: object required: [url] properties: url: type: string description: 完整的http/https地址必须带协议前缀 max_chars: type: integer default: 6000 description: 返回正文的最大字符数超过会被截断 example: url: https://example.com/app/overview max_chars: 4000注意不适用那一行。这不是可选项这是给模型划边界。写上之后模型在规划阶段就会自己避开那些它抓不动的地方转而用别的工具或者直接标注“该信息无法获取”。这比你在后面手动过滤无效结果省事太多了。另外执行器返回的观察结果一定要做截断。一个应用介绍页抓下来可能是几万字符原样塞回上下文一次就顶掉你一大半窗口。截断策略我一般分两层工具层面按max_chars截运行时层面再按truncate_observation兜底。两层都留着因为你永远不知道模型会传一个多大的max_chars进来。3.3 Action环节收敛条件设计不好Agent就会原地打转Action环节最核心的一件事是判断什么时候停。做过的人都知道Agent跑飞的主要形态就两种一种是无限循环反复查同一个东西另一种是过早收尾信息还没收集完就急着出报告。这两种问题都得靠收敛条件来治。我一般会设三层终止条件从紧到松第一层是硬上限。max_steps到了直接停不管有没有完成。这是安全阀防止预算失控。做应用分析这种任务我实测下来 6 到 8 步基本够了每步一次工具调用覆盖三到四个维度所以设 10 是合理的。第二层是无进展检测。连续两轮progress清单没有新增任何条目就判定为卡住了直接终止并输出当前已有信息。这一条特别管用因为模型在遇到“查不到”的时候很容易不甘心反复换个说法再查一遍。有了这条它最多浪费一轮就会被迫收手。第三层是目标达成。当progress覆盖了任务dimensions里的全部条目且最后一轮action字段返回finish就正常收尾。# agents/analyst.agent.yaml 收敛配置片段 termination: max_steps: 10 no_progress_rounds: 2 finish_on_all_dimensions: true on_terminate: emit_partial_report: true # 未完成也输出已有信息别丢emit_partial_report这个开关很关键。Agent 因为超时或者卡住被迫终止时如果直接丢弃前面的所有成果你会非常沮丧。打开它至少能拿到一份“部分完成”的报告里面标明哪些维度没查到这份东西本身就有价值——它告诉你下一步该补什么数据源。4. 第一次应用分析实战从输入到报告的全链路4.1 任务怎么定义决定报告长什么样跑通示例任务之后第一件事就是把它改造成你自己的任务。这一步看着简单实际上最考验功力因为任务定义写得含糊后面模型所有的努力都会跑偏。我的做法是把“分析”这个模糊动作拆成几个可被单次工具调用满足的子维度。比如“用户反馈”这个维度如果只写“分析用户评价”模型会不知道去哪个来源查、查多少条、按什么维度归纳。改写成“从公开评论区检索最近 200 条评价按功能诉求、稳定性问题、使用门槛三类归纳每类给出三条代表性描述”模型立刻就知道该怎么规划了。name: my-first-app-analysis goal: | 对一个目标应用做基础面分析输出一份可直接给产品团队看的简报。 要求所有事实性陈述必须有对应的工具来源无法确认的信息标注为“待核实” 严禁基于常识补充。 inputs: target: target-app-name dimensions: - name: 定位与功能 how: 抓取应用介绍页提取功能清单归纳为不超过8条 - name: 用户反馈 how: 检索评论区取最近200条按诉求类型分组每组给3条原话 - name: 更新节奏 how: 抓取版本历史页统计近12个月的版本数与平均间隔 output: format: markdown sections: [概览, 功能拆解, 用户反馈, 迭代节奏, 待核实项] max_length: 1500 constraints: - 每个章节末尾附上信息来源的工具调用编号 - 数量类结论必须给出统计口径constraints里那两条是我加的私货效果非常明显。要求“附上来源编号”之后模型在 Reason 环节就会主动考虑“这个结论需要哪个工具支撑”凭空捏造的情况大幅减少。要求“给出统计口径”能治另一种病模型说“评论中抱怨稳定性问题的占多数”你不追问它永远不会说这个“多数”是 55% 还是 90%。加上这条约束它会老老实实写“200条中识别出 78 条涉及稳定性占比 39%”。4.2 跑起来之后盯住中间产物而不是最终结果命令本身很简单npx rea-agents run --agent analyst --task tasks/my-first-app-analysis.task.yaml终端会实时打印每一轮的摘要形如[step 1] actioncall_tool toolhttp_fetch args{url: .../overview} [step 1] observation: status200, text_len5120 [step 2] actioncall_tool toolhttp_fetch args{url: .../versions} [step 2] observation: status200, text_len2340 [step 3] thought功能与版本信息已获取评论区需要换检索工具 [step 3] actionfinish第一次跑我的建议是别急着看最终报告先去看runs/目录。里面按时间戳分了子目录每一轮都有三个文件step-NN.reason.json、step-NN.action.json、step-NN.observation.json。把第1轮和第3轮的 reason 文件对比着看你会非常直观地感受到模型是怎么“想”的第1轮它在探索thought 字段写的是“需要先确认目标应用的基本定位”第3轮它已经能说“功能与版本信息已获取”并且progress数组里列了两条已完成项。我踩过的一个坑就在这里。第一次跑的时候第3轮模型直接判定 finish但我看progress只有两条缺了“用户反馈”这个维度。翻step-03.reason.json才发现它认为“评论区需要专门的检索工具而当前工具白名单里没有所以跳过”。这其实是合理的——我确实没给它配检索工具。问题出在任务定义里明确要求了这个维度但工具没到位。于是我补了一个search_public工具进白名单重跑一次第3轮它就正常去检索了。这件事给我一个很实在的教训Agent 的行为异常八成不是模型笨是你给它的能力边界和任务要求对不上。工具清单、任务维度、提示词约束这三者必须自洽。对不上时优先检查是不是某个维度没有对应的工具支撑。4.3 结果校验怎么判断这份报告能不能用报告生成之后别直接拿去用。我一般做三步校验每一步都很快。第一步是来源对齐。报告里标注了来源编号的陈述逐个回observation文件核对。这一步主要是防“张冠李戴”——模型把版本历史页里的信息说成是介绍页里的。抽查个五六条就够了命中率低于八成说明提示词约束还不够硬。第二步是数量核对。所有带数字的结论回原始观察数据重算一遍。这一步最容易发现问题。我曾经遇到过报告写“近12个月发布9个版本”但原始版本页里清清楚楚列了14个。原因是模型在截断后的文本里只看到了前9条max_chars设小了。这种错误人眼很难发现必须回原数据算。第三步是待核实项复盘。报告里标注“待核实”的部分其实是最有价值的信息——它精确告诉你数据缺口在哪。如果某个维度全都是“待核实”那说明这个维度的工具链路根本没通得回头补。校验项方法通过标准不通过的处理来源对齐抽查5-6条陈述回查observation命中率 ≥ 80%强化提示词里的来源约束数字准确带数字结论全部重算误差为0检查截断长度是否过小覆盖度对照dimensions逐项检查全部有结论或标注待核实补工具或补数据源幻觉率找出无来源的事实陈述≤ 2条加“无来源不陈述”硬约束这三步做完大概五分钟。别嫌麻烦前面省下来的时间会在你发现报告里有一半是编的那一刻加倍还回去。5. 踩坑实录那些文档里不会写的故障5.1 初始化阶段的几个经典报错报错一Cannot find module rea-agents。八成是 npx 缓存脏了或者你在一个奇怪的目录里跑。先npm cache verify再换个干净目录重试。如果还是不行说明你的包源配置有问题检查一下 npm config 里的 registry。报错二跑到一半卡在“正在检测模型连通性”。这类脚手架通常只给一个总的超时提示不告诉你具体卡在哪。我的排查顺序是先用 2.1 节那段 curl 自测一遍通了再看环境变量名有没有写错比如把REA_MODEL_API_KEY写成REA_API_KEY很多脚手架对空值不做校验会一直重试到超时。最后检查 endpoint 后面是不是多了一个斜杠这种细节问题能让你排查半小时。报错三交互式问答跑到一半终端乱码或者丢输入。这个在 Windows 的一些终端里很常见交互式库对 ANSI 转义支持不好。解决办法是换终端或者找找脚手架有没有--non-interactive之类的参数用配置文件一次性把所有选项喂进去。我习惯后者还能顺便把配置存成模板下次直接复用。5.2 运行阶段最烦人的两个问题问题一不收敛反复查同一个东西。这个我在 3.3 节讲了收敛条件的配置但还有一种情况是条件设了也没用——因为模型的progress字段每次都在变但变的都是措辞不是内容。比如第一轮写“已获取应用介绍”第二轮写“应用介绍页信息已收集”看着是新增实际上是同一件事。这种情况得在提示词里明确要求“progress 里每条必须是可验证的完成项措辞一旦确定不要改写”或者干脆在执行器层面做个简单的相似度去重。问题二JSON解析失败。表现是某一轮突然抛Unexpected token或者Unexpected end of JSON input。原因通常有三个输出被 max_tokens 截断这个最隐蔽因为前一半是合法JSON后一半没了、模型在JSON前后加了解释文字、模型用了单引号或者尾逗号。对应的处理调大 max_tokens 并加上“输出必须完整”的提醒、加前后缀截取兜底、以及找一个能容忍尾逗号的宽松解析器。提示给 Reason 环节的提示词里加一句“如果你不确定如何调用工具返回 actionask_human 而不是猜测”能挡掉相当一部分解析失败。模型遇到不确定的场景时宁可让它开口问也别让它硬编一个不合法的 JSON。5.3 一份可以直接对照的排查速查表现象最可能原因快速验证处理方式第一步就 finish任务描述太抽象模型认为无需动作看 step-01.reason.json 的 thought重写 goal拆出具体维度循环不结束max_steps 过大 无进展检测未开看 progress 是否重复开 no_progress_rounds工具参数报 schema 错误工具定义里 required 与模型输出不一致对比 args 和 tool.yaml放宽 required 或加默认值观察结果为空抓取目标需登录或为动态渲染看 observation 的 status换数据源或换抓取工具报告全是“待核实”工具白名单缺关键工具看 tools 目录实际清单补工具并重跑token 消耗异常高单轮 observation 太长看 text_len 字段调小 max_chars 与截断长度同一事实反复出现progress 未去重对比相邻两轮 progress措辞去重或执行器层面去重这张表我贴在工位上遇到问题先扫一眼八成能定位到。剩下两成基本是模型本身的波动重跑一次常常就好了——这也是为什么我建议把runs/里的产物留着方便对比两次运行的差异判断到底是配置问题还是随机性。6. 跑通之后让它真正能用的几个调整6.1 加一个自己的工具比调十次提示词都管用脚手架内置的工具是通用型的真做业务分析一定会缺。我第一次做应用分析卡在“更新节奏”这个维度——版本历史页是动态渲染的http_fetch抓回来是一堆空壳什么也拿不到。当时我尝试改提示词让模型“换一种方式获取”折腾了半小时毫无进展后来花了二十分钟写了个简单的工具问题瞬间解决。加工具的流程很直接在tools/下建一个 yaml 描述文件再在agents/analyst.agent.yaml的allowed_tools列表里加上名字。工具的执行逻辑如果脚手架支持内联脚本就直接写不支持就走本地 HTTP 服务的形式——定义里写清楚 endpoint执行器负责转发。# tools/release_history.tool.yaml name: release_history description: | 获取目标应用的版本发布历史返回结构化的版本列表。 适用需要统计迭代频率、版本号规律、大版本节点时使用。 不适用需要具体版本内容变更细节时应改用 http_fetch 抓取发布说明。 parameters: type: object required: [target] properties: target: type: string description: 应用标识 months: type: integer default: 12 description: 回溯月数 returns: type: array items: version: string released_at: string notes_len: integer注意returns这一段。把它写清楚模型拿到结果后归纳起来会准确得多。如果不写模型面对一个 JSON 数组经常会把字段名读错、或者把时间戳当成版本号。这个细节投入产出比极高。6.2 成本与延迟把该省的地方省下来REA 循环的成本是线性的——步数越多成本越高而且每轮都要带上完整的历史上下文所以实际上是超线性的。我做过的几个优化效果都比较实在。第一压缩历史观察。不要把每一轮的完整 observation 都塞回上下文只保留“本轮新增的关键事实”摘要。执行器可以在写回状态时让一个小模型或者规则做一次抽取把上千字的页面正文压成三五条要点。这一步能把上下文长度砍掉一大半。第二按维度并行。如果你的任务维度之间没有依赖关系比如“功能清单”和“用户反馈”互不影响完全可以把它们拆成多个独立的小任务并行跑最后再合并成一份报告。总步数可能增加但单次上下文长度大幅下降整体延迟和成本反而更优。第三缓存工具结果。同一个 URL 在一次运行里被抓两次是常见浪费。执行器层面加一个简单的内存缓存key 用工具名 参数哈希能省掉不少重复调用。优化手段预期收益实施成本适用场景历史观察压缩上下文降 50%-70%中需写抽取逻辑长链路多轮任务维度并行拆分延迟降 40% 左右中需做结果合并维度间无依赖工具结果缓存重复调用降 30%低执行器加缓存同一来源多次查询调低 max_tokens单次成本降 20%极低改配置输出格式简单时6.3 建一个小评测集不然你永远不知道改动是好是坏这一点是我认为最被低估的。很多人调 Agent 的方式是“改一版提示词跑一个 case感觉好像好点了就这么定”。这种调法在跑了二十个 case 之后会彻底失效因为你根本记不清哪一版在哪个 case 上表现更好。我的做法很简单挑十个有代表性的目标每个手工标注一份“最低可接受答案”不需要完美只要包含必须出现的关键事实和必须避免的错误类型。每次改动之后批量跑一遍统计三个指标维度覆盖率、事实准确率、平均步数。三个数字一起看改动是赚是亏一目了然。# 粗略的批量评测脚本思路就是这么简单 for task in tasks/eval/*.task.yaml; do npx rea-agents run --agent analyst --task $task --out runs/eval-$(date %s) done跑完把runs/eval-*里的报告和标注比对人工过一遍大概二十分钟。听起来笨但它让我避免了好几次“为了修一个 case 而搞坏八个 case”的惨剧。尤其是提示词这种东西改动是全局生效的没有评测集你就是在盲改。我个人在实际操作中的体会是REA 这套范式真正的门槛不在技术而在耐心——耐心去看每一轮的中间产物耐心去核对每一条来源耐心去建那个看起来毫无技术含量的评测集。前五分钟跑通很容易真正让它稳定产出可信结果靠的是后面这些琐碎的功夫。工具箱给你的是一副骨架能不能长出肉来还是得看你自己往里填什么。