Agent 的行动层：从「生成文字」到「真实执行」的工程跨越

我曾经以为，让 AI 「发一封邮件」是个简单需求——不就是调个 Gmail API？

等真正做起来才发现，这件事有三层复杂度：第一层是认证（OAuth 授权、令牌刷新、多账号隔离）；第二层是工具描述（怎么告诉模型这个工具能做什么、参数是什么格式）；第三层是动作语义（用户说「发邮件给张工」，模型要先解析意图，再映射到正确的工具调用，再处理执行结果）。

每一层单独拿出来都不算难，但三层叠加在一起，再乘以「1000 个应用」，就成了一个真正的工程问题。

「行动层」是什么，为什么它单独成为一个问题

LLM 天然擅长的是文字——生成代码、解释逻辑、分析文档。但「生成一段发邮件的代码」和「实际把邮件发出去」之间，有一条执行鸿沟。

跨越这条鸿沟需要：

1. 工具定义：用 JSON Schema 或函数签名描述工具的能力和入参，让模型能推理「什么时候该用这个工具，该传什么参数」。
2. 执行运行时：实际调用第三方 API，处理网络异常、速率限制、分页等脏活。
3. 授权管理：OAuth 令牌的获取、存储、刷新，以及不同用户之间的隔离。

这三件事合在一起，就是 Agent 的「行动层」。它不在 Prompt 里，不在模型里，完全是工程基础设施。

自建 vs 托管路由器：一个真实的取舍

最直接的做法是自建：为每个需要对接的服务写一个工具函数，注册到 Agent 的工具列表，自己处理 OAuth。

自建的优点是完全可控——工具的语义、入参格式、返回结构都可以精确裁剪；对安全性有强要求的场景（例如操作生产数据库、处理敏感数据）必须走这条路。

但自建的成本随对接数量线性增长。如果 Agent 需要同时操作邮件、日历、任务系统、代码仓库，自建意味着维护 N 套 OAuth 流 + N 套工具定义。这时候，托管工具路由器（Managed Tool Router）就成了另一个选项：用统一的 API Key 换取对成百上千个应用的预集成访问，OAuth 授权流由平台托管，工具描述由平台维护。

取舍很清晰：

| 维度 | 自建工具链 | 托管路由器 | |------|-----------|-----------| | 工具数量 | 少量、高度定制 | 大量、通用覆盖 | | 安全控制 | 完全自主 | 依赖平台 | | 维护成本 | 随对接数量增长 | 较低 | | 语义精度 | 可精细调优 | 受平台约束 | | 适合场景 | 核心业务动作 | 辅助集成、快速原型 |

实际工程中，我倾向于混用：核心业务动作自建（权限可审计、语义可控），周边集成用托管（日历提醒、消息推送、文档归档）。

OAuth 授权流：一个经常被低估的工程难点

行动层里最容易被原型阶段忽视、生产阶段暴雷的环节是 OAuth。

原型阶段通常用固定的个人 API Token，一切正常。上到多用户场景，问题才开始出现：

• 令牌刷新：access token 过期后，Agent 执行到一半报 401，怎么优雅重试？
• 多账号隔离：同一个 Agent 服务多个用户，每个用户的令牌不能混用。
• 授权中断：首次授权需要浏览器跳转，如何在 Agent 执行流中插入「等待人工授权」的暂停点，完成后自动继续？

第三个问题最有意思。Agent 执行是一个状态机，遇到需要人工介入的步骤，不能简单地抛异常——它需要「挂起当前上下文、通知用户授权、用户完成后恢复执行」。托管路由器通常把这个流程内化了（提供 OAuth 跳转链接，用户完成后回调），但如果是自建，这套挂起-恢复机制需要自己设计。

行动层的最小可行架构

如果从零开始为 Agent 搭行动层，我会先确认三件事：

1. 工具清单要小：只注册 Agent 当前任务实际需要的工具，不要把「所有可能用到的」都预注册。工具越多，模型在工具选择上犯错的概率越高。

2. 每个工具响应要包含状态语义：不只是返回数据，还要告诉模型「成功 / 失败 / 需要授权 / 需要等待」，让模型能做下一步决策。

3. 高风险动作要有确认节点：发邮件、创建 Issue、推送消息这类不可逆操作，在 Agent 自动执行前加一个「预览确认」步骤，把要执行的动作摘要给用户，再落实。

一句话心法

让 Agent 「能说」很容易，让它「能做」需要把行动层当作一等公民来设计。