AI Agent真正需要App提供什么才能完成一件有用的事

过去一年，AI Agent从演示视频走进了真实工作流。开发者们很快发现一个尴尬的事实：让Agent在浏览器里点来点去，远不如让App主动暴露一组干净的能力来得可靠。但到底该暴露什么、暴露到什么粒度、权限怎么收，行业里还没有共识。

最近一个来自RSS源的公开征集把这个问题直接摊开了：一个Agent到底需要从你的App里拿到什么，才能替你完成一件真正有用的事？ 征集的发起方没有给出答案，而是邀请开发者描述具体工作流、指出卡点。这种"先问再做"的姿态，本身就说明问题还没有标准答案。

从假设到追问：Agent集成不是API文档的搬运

很多团队最初的想法很简单：把现有REST API包一层，让Agent调用就行了。实际做下来会发现，给人类开发者用的API和给Agent用的能力接口，是两套东西。

人类开发者能读文档、理解上下文、处理异常、在失败后换个姿势重试。Agent不会。它拿到的是一个没有语义的端点列表，以及一个模糊的自然语言目标。中间那层"翻译"如果没做好，Agent就会陷入反复调用、参数乱填、或者干脆幻觉出一个不存在的接口。

征集方提到"答案不断让我们惊讶"，这句话值得琢磨。惊讶通常来自两种落差：一是开发者以为自己已经准备好了，实际反馈显示没有；二是某些被忽视的小设计，恰恰是Agent能否跑通的关键。

Agent向你索要的，可能和你想的不一样

把各家反馈归纳一下，Agent对App的诉求大致落在几个层面。

意图可发现，而不是端点可调用

Agent需要知道"这个App能帮我做什么"，而不是"这个App暴露了哪些函数"。一个商品App，人类看的是按钮和导航，Agent需要的是"查询订单状态""发起退货""比较同类商品价格"这类带语义的动作描述。

这意味着能力清单要用人话写，并且明确每个动作的前提条件、输入含义和可能的输出形态。把这些当成文档附属品，往往会成为Agent失败的第一现场。

状态可读，且是结构化地可读

Agent执行多步任务时，必须知道当前处于什么状态。页面上的文字、图标、加载动画，对人类是信号，对Agent是噪音。结构化地暴露"订单已发货""余额不足""需要用户二次确认"这类状态，能让Agent决定下一步是继续、暂停还是放弃。

失败要能被理解，而不是只返回一个错误码

人类看到500会去翻日志，Agent看到500只能猜。返回信息里带上失败原因、可选的补救路径、以及是否值得重试，能显著降低Agent的无效循环。这一点在跨App编排时尤其关键——A应用失败后，Agent需要判断是换B应用还是回头问用户。

语义化错误与机器可读错误在Agent场景下的区别值得单独说清。 传统API设计里，错误码（如404、500）和简短message是给人类开发者看的，他们能结合日志、文档和上下文推断原因。但对Agent来说，它缺少这种外界知识，一个裸错误码就可能被解读成"这条路走不通"或"需要重试"，从而触发无意义循环。语义化错误要求返回结构化的机器可读字段，例如error_type（永久失败/暂时失败/需授权/需用户确认）、retryable布尔值、suggested_action（换工具、降级、问用户）以及user_message。Web标准中的RFC 7807（Problem Details for HTTP APIs）提供了一种可借鉴的格式，用type、title、detail、instance四个字段表达问题。更成熟的做法是定义一套领域内的错误分类枚举，让Agent无需猜测即可编排后续步骤，尤其在跨App任务中，错误语义统一是决定Agent能否优雅降级的关键。

权限边界要显式，而不是靠Agent自觉

Agent拿了用户的授权去操作，能做什么、不能做什么，最好在接口层就限定死。仅靠提示词约束"不要动钱包"，在真实场景里不够可靠。把高风险动作设计成必须显式确认，既保护用户，也保护App自己。

这里的核心概念是能力授权与最小权限原则在Agent场景的延伸。传统OAuth为第三方应用授予的是粗粒度scope（如"读取邮箱"），但Agent替用户执行动作时，需要更细的"动作级"许可，例如"可以为这一笔订单发起退货"而不是"可以修改所有订单"。业界常用两种手段落地：一是意图绑定令牌（intent-bound token），令牌里写入具体动作、目标资源、有效期和金额上限，越界即拒绝；二是人在回路确认（human-in-the-loop），对支付、删除、发送等高风险动作要求用户显式点按确认，而不是靠提示词里的"请不要……"约束。可验证凭证（Verifiable Credentials）和去中心化身份（DID）也被讨论用于Agent身份与授权，让App能验证"这是谁授权的Agent、授权了什么"。这些机制共同把权限从"君子协定"变成接口层的硬边界。

工作流卡在哪里：三类被反复提到的断点

征集方向开发者要"工作流"和"断点"，说明提问者关心的不是抽象原则，而是具体卡壳的地方。

第一类断点在登录与身份。Agent替用户操作时，用谁的账号、以什么身份、会话如何延续，很多App没有为这种场景准备。人机共用的登录态和Agent专用的授权通道，需要分开设计。

第二类断点在跨App的交接。一个有用任务往往横跨多个应用，比如从邮件里提取信息再填入表格。单个App能力再干净，交接处没有统一约定，Agent还是要靠截图和坐标硬凑。

第三类断点在"最后一公里"的确认。Agent把事做到99%，最后一步要不要替用户点下去？不同App给出的答案不同，用户的预期也不同。把确认时机设计成可配置的，可能比一刀切更实际。

这对开发者意味着什么

如果Agent真的成为App的重要入口，那么"面向Agent的接口设计"会变成和"面向人类的UI设计"并列的一等公民。现在的征集本身就是一个信号：标准还没定，谁先把自己的工作流和卡点讲清楚，谁就更有机会影响后面的约定。

对App团队来说，眼下能做的不是等标准，而是从自己最常被请求的那一个任务开始，把它的能力描述、状态反馈和失败信息整理成Agent能读的形式。一件事跑通，比一百个端点暴露出去更有价值。

作为补充说明，以上关于能力与断点的归纳来自公开征集的讨论方向和常见的Agent集成经验，并非征集方给出的最终结论；该征集仍在进行，欢迎开发者提交各自的具体工作流。

背景补充

Agent专用身份通道可以理解为一种"委托式访问"模式。人类登录一般靠账号密码或已有会话，而Agent作为用户的代理人，需要的是可被撤销、可被审计、范围受限的凭据。常见的实现方向包括：为每个Agent会话发放短期委托令牌（delegated token），明确标注委托人、被委托Agent、授权动作和时间窗口；在服务端维护"用户- Agent -会话"三元组，使App能区分"这是用户亲自操作"还是"Agent代表用户操作"。这和传统的机器对机器（M2M）客户端凭据不同，因为Agent的授权来源始终是人，只是执行者变成了软件。如果App不为这种场景设计独立通道，就只能复用人的登录态，导致Agent行为无法与用户行为区分，审计和撤销都会失效。