1. 先聊聊为什么需要"专用智能体"这个物种

1.1 通用助手看着聪明，用起来却总差一口气

大模型Agent这个概念爆火之后，团队里最常出现的动作是：拿一个通用System Prompt，把公司API全接进去，然后祈祷它能自己搞定一切。结果通常是——它确实"什么都能聊"，但该干活的时候到处拉胯：任务没拆解清楚就急着调工具，工具一多就选择困难，上下文越搞越长，输出格式隔三差五变一变。说白了，通用Agent是通才，不是专才，让它十项全能等于让它事事半吊子。

我体会特别深的一个场景是做客服工单处理。通用Agent能理解用户问题，但让它同时判断工单分类、查询订单系统、拟回复话术、判别是否需要人工介入，这几个动作挤在一起，效果非常不稳定。分类偶尔错、回复语气忽冷忽热、明明该转人工却自作主张道歉了事。问题不在模型，而在设计——一个Agent承担了太多职责，本质上是把多个决策点混在同一个上下文里，互相干扰。

专用智能体（specialist agents）就是专门解决这个问题的：一个Agent只负责一类任务，输入输出边界清晰，工具集收敛到必要范围，Prompt围绕单一职责反复打磨。它不需要博学，只需要在自己那一亩三分地上做得可靠。全科医生头疼脑热都能看，但真到心脏手术还得找专科医生，Agent也是这个道理。

1.2 专用智能体的核心成本不在模型，而在"工程化"

很多人以为开发一个专用Agent就是写两句Prompt，真上手做才发现大头全在后面：模型选型、工具封装、上下文管理、评估集维护、版本管理、部署更新、线上监控，每一项都要人力。我算过一笔账，一个中等复杂度的业务Agent，光是把开发、联调、部署、评估这条链路跑顺，在没有工具辅助的情况下至少两到三周，其中大半时间浪费在重复劳动上。

这中间最磨人的是部署环节。Prompt改了要重新发版，工具接口换了要对齐入参，Agent逻辑调优要回滚，模型接口更新又可能影响线上。传统软件开发的CI/CD、版本管理、灰度发布意识，在Agent开发里经常是空白。我见过不少团队，Agent已经上线了，改Prompt靠SSH到服务器上改环境变量，模型参数和业务代码混在一个服务里，怎么优雅怎么来完全谈不上。

所以当我看到Recurse这个项目时，第一反应就是"终于有人把这块骨头啃了"。Recurse标榜的"Develop and deploy specialist agents faster"，不是吹模型能力强，而是把Agent开发流程标准化、把部署链路工程化，让开发者把精力放在任务拆解和Agent本身的质量上。下面我结合自己用下来的经验，拆一拆它到底做了什么，以及为什么这样做是对的。

2. Recurse的核心理念：把Agent开发变成"叠积木"

2.1 递归拆解：复杂任务不是Prompt写出来的，是拆出来的

Recurse这个名字本身就透露了它的关键思想：递归。项目创始人有个很直白的观点——一个复杂的业务请求，靠一段长Prompt让单个Agent从头干到尾，既脆弱又难维护；正确的做法是把这个请求递归拆成若干子任务，每个子任务交给一个专用的子Agent，子Agent遇到复杂情况还可以再往下拆。整棵任务树由编排引擎统一调度，而不是把所有逻辑塞进一个模型上下文里。

这个设计我深有同感。拿"处理用户退款咨询"来说，直接丢给一个通用Agent，它要考虑意图识别、政策匹配、订单查询、风险判断，还要组织话术，每个环节都是独立的决策，挤在一起很容易串味。用递归拆解之后，任务树大概是这样的：根节点是退款咨询处理，下一层分出意图分类、政策检索、订单状态查询三个子任务，每个子任务对应一个专用Agent；意图分类Agent只判断用户是想退款、想投诉还是只想问问进度，做完就把结果交给调度器，由调度器决定下一步调用谁。每一层职责单一，Prompt可以写得非常聚焦，工具调用路径也变得可预测。

这就是Recurse和市面上很多"多Agent框架"的区别。它不是简单地让几个Agent自由聊天、互相传话，而是用递归结构把任务拆分成一棵有明确边界的树，每个节点是一个可独立开发、独立测试、独立部署的Agent。好处非常直接：任何一个节点出问题，定位和回滚都不会牵连整棵树。用的时候我最大的感受是，"写Agent"变成了"拼Agent"，新手也能很快上手。

2.2 声明式Agent定义：一份YAML搞定大部分配置

Recurse把Agent定义做成了声明式配置。你不用先读一堆代码，而是会看到一个agents目录，里面每个子目录就是一个Agent，核心是agent.yaml。这份文件定义了Agent的角色边界、使用的模型、可调用的工具、提示词模板、递归策略和可观测配置。下面是我在实际项目里写的一个工单分类Agent的配置骨架：

name: ticket_classifier description: 判断用户工单的类型，只输出 className 字段 model: provider: openai-compatible name: gpt-4o-mini temperature: 0 max_tokens: 200 prompt: template: prompts/classify_prompt.tmpl variables: - user_message - channel tools: - name: get_channel_info with: { channel_id: string } recursion: max_depth: 2 on_uncertain: escalate_to_human observability: metrics: true traces: true

我特别看重这里的两点。第一是temperature直接配成0，分类任务要的是稳定输出，不是创造性发挥；第二是recursion段，它规定了Agent自己拿不准时是继续拆子任务还是直接转人工。Recurse允许在声明文件里显式控制递归策略，这让每层Agent都有止损机制，不会无限往下钻。相比在Prompt里写"如果你不确定该怎么办"，这种配置化的控制可靠得多。

声明式的好处不只是清晰，更重要的是它能进入版本管理。Agent的角色边界、模型选择、工具授权全部以文本形式存在，评审的时候打开git diff就能看到改了啥，回滚也只需要切一个提交。这种做法是从基础设施即代码里借来的思路，放到Agent开发里一样成立。

2.3 工具即API：统一注册、自动鉴权

专用Agent免不了要调外部系统，工具管理一直是Agent工程里的老大难。Recurse的做法是引入一个"工具注册表"（Tool Registry），所有能被Agent调用的能力都以标准接口注册，统一声明入参出参、鉴权方式和超时策略。开发Agent的人不用关心工具背后的系统差异，只需要在配置里声明工具名和传入参数。

我举个例子。团队里有个内部订单查询服务，以前要想让Agent调用它，得自己写一段Function Calling的代码，还要处理鉴权、错误码、连接池。在Recurse里，只需要给这个服务写一个薄薄的适配层，然后注册成工具：

recurse tool add order_query \ --endpoint http://order-svc:8080/query \ --auth bearer \ --schema-order '{"order_id": "string"}'

注册之后，任何Agent声明tools里包含order_query，就能直接使用。Recurse会在运行时自动完成鉴权注入、参数校验、超时重试和错误码归一化，开发者不用在每个Agent里重复处理这些破事。工具和Agent分离还有个额外好处：一个服务接进来，十个Agent都能复用，管线能力像积木一样积累。

不过我也踩过坑：工具不是越多越好。Agent能调用的工具列表里每多一项，模型做工具选择的负担就重一分，误调用的概率也跟着涨。Recurse的配置体系虽然让人可以很轻松地给Agent挂上二十个工具，但真正上线时我建议每个Agent的工具数尽量控制在五六个以内，宁可重新拆一个Agent，也不要让一个Agent变成工具箱管理员。这个度，用几轮评估集跑一下就知道了。

3. 实操：用Recurse从0到1开发一个工单分类Agent

3.1 环境准备与项目初始化

我习惯先从一个最小的场景跑通全链路，再逐步加复杂度。第一次接触Recurse，建议你也不要一上来就挑战那种二十个子任务的庞然大物，先做一个"工单分类Agent"这种单一职责的，把开发、测试、部署整套流程走一遍，然后再去碰递归拆分。下面是我的完整操作记录。

Recurse提供了一个命令行工具，安装方式很简单，macOS和Linux都支持：

brew install recurse-cli recurse --version

然后是初始化项目。Recurse的推荐结构是按Agent划分目录，根目录下有一个全局的recurse.yaml，用来配置模型供应商、工具注册表地址、默认部署目标等信息。初始化一个叫helpdesk的项目：

recurse init helpdesk --template agent cd helpdesk tree -L 2

初始化完的目录大致长这样：

helpdesk/ recurse.yaml agents/ ticket_classifier/ agent.yaml prompts/classify_prompt.tmpl tests/classify_cases.jsonl tools/ channel_tool.py

这里的recurse.yaml我建议一开始就设置好模型供应商信息，后面所有Agent默认走这个配置。一个最小配置长这样：

project: helpdesk defaults: model: provider: openai-compatible name: gpt-4o-mini timeout_seconds: 30 tool_registry: endpoint: http://localhost:8080

还有个细节容易忽略：Recurse默认要求每个Agent目录里必须有tests目录，这是为了保证Agent不是"写完即扔"，而是有一组可重复执行的评估用例。我一开始觉得这个要求多此一举，后来越用越觉得这是整个项目最值钱的设计之一。

3.2 编写Agent定义与注册工具

初始化完，第二步就是写Agent定义。工单分类Agent的输入是用户消息和渠道来源，输出是工单类型。在agent.yaml里先把模型和工具声明好：

name: ticket_classifier description: 将用户工单分为退款、投诉、进度咨询、其他四类 model: provider: openai-compatible name: gpt-4o-mini temperature: 0 prompt: template: prompts/classify_prompt.tmpl variables: - user_message - channel tools: [] recursion: max_depth: 1

然后写提示词模板。这里我强烈建议把输入拼装逻辑全部放到模板里，而不是在代码里用字符串拼接，否则后面维护Prompt和代码的对应关系会非常痛苦。我的classify_prompt.tmpl大致是这样：

你是一个工单分类专家。请根据用户消息和渠道信息，判断工单类型。 只允许输出以下四类之一，不要输出解释： - refund - complaint - inquiry - other 用户消息：{{user_message}} 渠道：{{channel}}

接下来注册工具。我做一个很小的"渠道解码"工具，先让链路通起来，再慢慢加订单查询这类重工具。注册方式就是上一节说的recurse tool add，也可以直接把Python函数写在agents/ticket_classifier/tools/channel_tool.py里，Recurse会扫描目录自动识别：

from recurse import tool @tool(name="get_channel_info", description="获取用户所在渠道的详细信息") def get_channel_info(channel_id: str) -> dict: mapping = {"app": "移动端", "web": "网页端", "sms": "短信端"} return {"channel": mapping.get(channel_id, "未知")}

注意这个工具的入参和出参都是JSON可序列化的，Recurse会把它转成Function Calling的schema，所以函数注释和类型标注要写完整，这是工具能被正确调用的关键。我第一次写的工具函数出参是一个Python对象，模型拿到的却是一个序列化后的字符串，排查了半天才发现是类型标注不规范导致的。

3.3 本地调试与评估：先把"准"做出来

开发过程中最常做的事情就是本地调试。Recurse有一个交互式的debug命令，可以模拟请求、查看中间决策过程：

recurse run agents/ticket_classifier \ --input '{"user_message": "我上周买的鞋子开胶了想退款", "channel": "app"}'

第一次跑的时候，我遇到一个挺有意思的现象：模型没有输出refund，而是输出了complaint。光看字面，用户说鞋子开胶想退款，确实容易被理解为投诉，但在客服体系里这种应该归类为refund，而不是complaint。问题出在提示词太笼统，没有给出判定优先级。我在模板里加了一条规则：

判定优先级：如果用户明确表达退款意向，归为refund，而不是complaint。 除非用户使用了辱骂性词汇，才归为complaint。

加了这条之后，分类准确率明显提升。这个例子恰好说明：开发Agent很大一部分工作不是写代码，而是打磨提示词里的判定规则，而且这些规则最好是从错误用例里反推出来的，而不是拍脑袋写出来的。

光靠几个手工用例还不够，Recurse支持用JSONL文件定义评估集，然后跑批量评估。我把测试用例放在tests/classify_cases.jsonl里，每行是一个包含输入和期望输出的用例，大约准备三四十条覆盖边界场景。跑评估的命令很简单：

recurse eval agents/ticket_classifier --dataset tests/classify_cases.jsonl

评估通过之后，Recurse会生成一份报告，包含准确率、token消耗、工具调用次数这些指标。我建议把这份报告归档到制品里，每次改动Agent配置之前先跑一遍旧评估集，确认没有回归再继续。做Agent最怕的就是"这次改好了一个bug，结果三个旧场景又坏了"，评估集是唯一能拦住回归的网。

4. 部署链路：像发Maven包一样发Agent，像管配置一样管Prompt

4.1 制品与版本：Agent也要走CI/CD

部署Agent最忌讳的操作方式是什么？把代码一顿scp到服务器，然后重启服务。Recurse把Agent开发流程和传统软件的制品管理对齐了：Agent配置、提示词、工具代码统一打包成一个"Agent制品"，制品有版本号、有构建时间、有依赖清单，发布到制品仓库之后，部署环境只认版本号，不认"最新代码"。

这个思路和Java生态里Maven deploy到远程仓库是同一个道理。你在本地把Agent打包好，推到远程制品仓库，部署环境再从仓库拉取指定版本。这样做最大的好处是版本可追溯：线上出了诡异问题，我可以直接说"这是ticket_classifier@1.4.2跑出来的结果"，而不是"刚才有人改过Agent目录下的某个文件"。我有一次线上Agent行为异常，排查到最后发现是有人把服务器上的Prompt文件手动改过，制品仓库里完全没记录。从那以后我再也不允许任何绕过制品管理的发版方式。

Recurse的打包发布命令我通常这么用：

recurse package agents/ticket_classifier --version 1.4.2 recurse publish helpdesk/ticket_classifier:1.4.2 --registry myrepo

这里的publish目标就是一个兼容OCI的制品仓库，也可以对接现有公司的Artifactory或者Harbor。发布之后，部署端用一条命令拉取并校验签名：

recurse deploy helpdesk/ticket_classifier:1.4.2 --cluster pre-prod

4.2 用ConfigMap管Prompt，改提示词不用重发镜像

Agent制品构建成容器镜像后，一个很容易犯的错是把Prompt模板和模型参数打进镜像里。看起来省事，实际是给自己埋雷：提示词是业务上迭代最快的部分，一个灰度话术的调整可能一天改三次，每次都重新build镜像、推仓库、再滚动更新，既慢又容易出错。

Recurse的推荐做法是把Prompt模板、Agent模型参数这些"配置类信息"放进Kubernetes的ConfigMap，容器启动时挂载进去。这样改提示词只需要更新ConfigMap，然后滚动重启Pod，镜像本身完全不动。这个思路和部署传统应用时把application.yml抽出来是一样的，只是这里抽离的是模型上下文相关的配置。

我通常会建一个configmap.yaml：

apiVersion: v1 kind: ConfigMap metadata: name: ticket-classifier-config labels: app: ticket-classifier data: classify_prompt.tmpl: | 你是一个工单分类专家。请根据用户消息和渠道信息，判断工单类型。 只允许输出以下四类之一： - refund - complaint - inquiry - other 如果用户明确表达退款意向，归为refund，而不是complaint。 用户消息：{{user_message}} 渠道：{{channel}} model.yaml: | temperature: 0 max_tokens: 200

在Deployment里把它挂载到容器的配置目录，Recurse的Agent运行时启动时会优先读取ConfigMap里的配置，覆盖制品内嵌的默认值。这个设计让我在线上改Prompt时非常从容，改完配置等Pod滚动起来，再跑几个真实请求验证就行，不用动镜像。

4.3 部署到Kubernetes：从ConfigMap到滚动更新

把Recurse构建的Agent镜像部署到Kubernetes，整体流程和我部署普通服务几乎没有区别，但有三个地方要特别注意。

第一个是环境变量注入。模型供应商的API Key、工具系统的访问令牌这类敏感信息，绝对不能放进ConfigMap，要用Secret挂载，Recurse运行时支持从标准环境变量读取模型凭证，这样可以不把Key写进Agent YAML。

第二个是健康检查。Agent服务不能只检查进程活着没，更要检查模型依赖是否可用。我习惯把readinessProbe指向Recurse生成的健康检查端点，这个端点会实际测试一次最小模型调用和工具注册表连通性，避免出现"容器起来了但模型接口超时导致全量报错"的情况。

第三个是资源限制。Agent服务看起来是个HTTP服务，但实际是个高消耗型服务，每个请求都要走模型API，内存和CPU占用比普通应用高很多。我最初按传统服务的标准配资源，结果线上频繁OOM，排查很久才发现是请求并发上来之后token缓冲区膨胀所致。后来给Agent容器单独调了内存配额，也加了并发上限，才稳定下来。

Deployment的骨架大致这样：

apiVersion: apps/v1 kind: Deployment metadata: name: ticket-classifier spec: replicas: 3 selector: matchLabels: app: ticket-classifier template: metadata: labels: app: ticket-classifier spec: volumes: - name: agent-config configMap: name: ticket-classifier-config containers: - name: agent image: myrepo/helpdesk/ticket-classifier:1.4.2 ports: - containerPort: 8080 envFrom: - secretRef: name: agent-secrets volumeMounts: - name: agent-config mountPath: /opt/agent/config readinessProbe: httpGet: path: /healthz port: 8080 resources: requests: memory: 256Mi cpu: 250m limits: memory: 1Gi cpu: "1"

部署用标准的kubectl apply就能搞定。Recurse提供的一个小增强是deploy命令会先生成这份YAML，再做一次配置校验，比如提前发现ConfigMap里模板变量引用错误，而不是等到Pod启动失败才知道。

5. 踩坑实录：递归编排常见的五个坑

5.1 子任务拆得越细，上下文越容易丢

递归拆解听起来优雅，用起来第一个坑就是上下文丢失。根Agent拿到用户原始问题，拆出子任务，子Agent只收到父Agent传下来的片段，很多时候片段里缺了关键信息。尤其是在工单场景下，用户的一句话往往包含多个意图，单把"我想退款"传给子Agent而丢掉"我上周买的鞋开胶了"这个上下文，子Agent就很难做出正确的分类。

我的解决思路是建立一条轻量的"共享上下文通道"。父Agent在拆解时，除了传入子任务的专用输入，还要把必要的背景摘要一并带上。Recurse在递归编排引擎里提供了一个context字段，专门用于在父子Agent之间传递经过压缩的上下文。我习惯在模板里固定声明"必须把用户原始诉求原样传给子任务"，虽然会多花一点token，但换来的是准确率的大幅提升，这笔账很划算。

5.2 Agent踢皮球，递归变成死循环

第二个坑比上下文丢失更隐蔽：子Agent发现自己处理不了，把任务又抛回给父Agent，父Agent觉得该子Agent管，循环往复。Recurse虽然设了max_depth，但默认行为是触顶之后抛出异常，如果没有兜底，整个请求就废了。这个问题在真实业务里很常见，因为模型对"自己的能力边界"并没有那么清醒。

我给每个递归节点都配上明确的兜底策略，原则就一条：宁可转人工也不要踢皮球。在agent.yaml的recursion段里，我把on_uncertain配置成了escalate_to_human，并设置max_depth不超过3。考虑到真实业务的成本，一个请求如果拆到第三层还搞不定，说明这个场景本身就该交给人了。代码逻辑里还可以额外加一个递归次数计数器，超过阈值就触发告警，方便我定期检查哪些任务经常触顶，反过来优化任务树结构。

5.3 Prompt与代码版本不同步，线上行为诡异

我踩过最疼的坑就是这个。ConfigMap的好处是改提示词方便，代价是提示词很容易和Agent代码版本脱节。我给某个Agent加了一个新工具，代码和工具定义都更新到1.5.0了，但线上ConfigMap里挂的Prompt还是1.4.2时代写的，内容里压根没提这个新工具。结果模型在不知道工具有用的情况下被场景逼着强行调用，参数各种乱填，报错率飙升。

现在我的规范是：ConfigMap和Agent镜像用同一个版本号命名，prompt文件首行用注释写明关联的Agent版本，发布checklist里必须包含"核对ConfigMap版本与镜像版本"这一项。Recurse的deploy命令会校验制品版本和配置版本是否匹配，不过我还是会在本地脚本里再加一道检查，双保险。

5.4 模型行为漂移：同一段Prompt，三个月后效果不一样

模型接口方更新、模型权重调整、厂商暗改行为，这些事不在你的控制范围内，但会直接体现在Agent输出上。同一个Prompt，三个月前分类准确率96%，今天只剩87%，这不是配置出了问题，而是模型变了。我遇到过最离谱的一次是模型供应商静默升级了基础模型，Temperature=0的分类结果都出现了明显变化。

对策就两句话：模型版本要固定，评估要常跑。Recurse支持在Agent配置里锁定模型的版本快照，不要用"最新版"这种漂移目标。同时，我把评估命令挂进了发布流水线，每次部署前必须跑一遍评估集，准确率低于阈值就阻止发布。这个习惯救过我很多次，尤其是大版本模型更新的时候，旧的评估集就是一面照妖镜。

5.5 可观测性：Agent排障不能靠瞎猜

最后一个坑来自运维视角。Agent服务出问题，不像普通服务那样看个日志栈就能定位。模型为什么这么调工具、中间经历了哪些步骤、每步花了多少token，如果你没有追踪数据，排查起来完全靠猜。Recurse内置了tracing支持，但我发现很多人都没认真配。

我会重点记录三类信息：请求链路轨迹、每个节点的决策理由、token消耗分布。决策理由尤其关键，我会要求提示词模板里增加一个"最后输出一行json，说明你的判定依据"的步骤，这样线上出问题时可以快速回溯是哪个Agent的哪条上下文导致了偏差。没有这些数据，任何排障都只是碰运气。日志里我也会单独把agent_id和request_id打出来，方便把一次完整请求的所有子Agent执行轨迹串成一条线。

6. 我的几点真实体会

玩了一轮Recurse下来，我最想说的是别把"递归"理解成银弹。任务拆解确实是个好思想，但拆多深、每层放什么职责、什么时候止损，这些都需要根据业务场景和成本约束反复调。我见过有人把简单的一句话分类任务硬拆成五层Agent树，结果延迟翻了几倍，准确率反而下降。正确的做法是从一个单Agent加一层递归开始，用评估集量化收益，再决定要不要继续拆。

如果让我给团队一个建议，那就是评估集一定要在最开始就建。模型输出不像代码有明确的正确错误，你觉得它表现好，很多时候只是你挑的例子恰好没踩到边界。只有把几十上百条边界用例固化下来，Agent开发才有资格被叫"工程"。我在这个项目里最大的收获，与其说是学会了Recurse的配置语法，不如说是养成了一套围绕评估集迭代的习惯。

至于部署，我的体会是别等Agent"完美"了再上生产。先让它在一个狭小的任务范围里跑起来，配上完善的trace和兜底策略，再逐步扩大边界，比憋大招稳得多。Recurse这套"制品化+ConfigMap配Prompt+滚动更新"的链路，谈不上花哨，但它让Agent开发和传统服务开发终于有了同一种节奏，团队协作的门槛也因此低了不少。这才是它让我觉得faster的根本原因。