Agent 接入现有 API 的权限与架构选择

把现有 API 接给 AI Agent，最容易低估的不是模型会不会选错工具，而是它选错之后，系统是否仍能守住权限和业务边界。原文的核心主张很明确：模型负责提出调用，代码负责授权与执行。

作者围绕接口盘点、工具设计、凭证隔离、重试和灰度上线，给出了一套工程建议。它没有展示实测收益，但对准备让 Agent 查询账单、修改数据或执行支付的团队，提供了一份值得逐项核对的接入框架。

接入之前，先分清哪些接口会改变业务状态

现有 API 能被业务代码调用，不代表适合直接开放给 Agent。查询账单和扣款都可能只是一次 HTTP 请求，但出错后的代价完全不同。

作者建议先盘点认证方式、分页、限流、错误码和副作用。副作用就是调用之后发生的实际变化，例如创建记录、修改状态或扣钱。这份清单应成为后续工具设计与权限控制的依据。

随后才是选择接入方式：

• 接口少、变化少时，可以直接使用函数调用（function calling），由应用代码承接模型生成的结构化参数。
• 多个 Agent 共用 API，或者需要统一执行权限策略时，可以增加网关层，把检查集中起来。
• 需要跨客户端复用工具时，可以考虑 MCP，但不能把高权限凭证交给不可信的 MCP server。

这几种方案解决的需求不同。原文没有提供性能、成本或维护量对比，因此不宜把它们理解成逐级升级的路线。

工具要让模型选得准，权限要让代码守得住

作者强调，一个工具只承载一个有意义的动作，名称要准确，描述要说明何时使用，参数尽量少且有明确类型。返回结果也应简洁、结构化，避免把整份数据丢给模型筛选。

例如，需要让 Agent 查询账单，就应围绕查询动作定义工具，而不是给它一个什么都能做的通用 API 入口。作者认为工具数量增加会降低选择准确率，但没有给出测试集、模型配置或下降幅度。这是一条设计建议，不能当成已量化的规律。

更关键的是：工具描述和执行权限是两层约束。

模型负责提出调用，应用代码负责决定这次调用能否执行。

在提示词里写「只读」，不会让一个具备写权限的 token 自动失去写权限。作者建议为 Agent 建立独立于人类用户的身份，发放短期、限定任务范围的 token，并在代码中检查权限。只读账单的 Agent，就不应该持有可修改账单的凭证，更不应通过提示词传递凭证。

重试之前，要先保证同一笔操作不会执行两次

调用失败之后直接重试，是接入写接口时很危险的习惯。请求超时只能说明调用方没收到结果，不能证明服务端没有完成扣款。

作者引用 Stripe 的幂等键（idempotency key）模式：同一次业务操作通过同一个标识，让服务端识别重复请求，避免重复执行。

幂等键要在请求发出前生成，不能等失败后再补。

否则，请求处理中发生崩溃时，客户端可能已经失去识别原操作的依据。原文没有进一步说明幂等键如何持久化、重启后如何恢复，这部分仍需结合业务实现。

错误也不能一概重试：参数错误应修正参数，权限错误应转交处理，遇到 429 则采用退避与随机抖动，避免多个请求同时再次冲击服务。

上线同样需要分阶段推进，并为后果重大的动作设置审批。原文提出了方向，但没有给出灰度比例、审批规则或回滚流程。

我的判断

我认同作者把问题落在接口与权限设计上。工具描述影响模型如何选择，授权代码决定系统允许它做什么。对于会修改数据、触发支付的工具，后者必须独立成立。

相比直接暴露一整套接口，从小工具集和受限凭证开始，更容易检查调用路径。相比每个 Agent 分别实现策略，网关适合集中治理；但如果只有少量稳定接口，额外引入网关或 MCP 也会增加维护工作。

这篇更像工程经验清单。作者没有提供生产事故复盘、工具规模对照实验或接入效果数据，也没有展开审计日志的具体实现。因此，它适合用来检查方案是否遗漏关键边界，不能据此断言某种架构一定更可靠。

能拿来做什么

• 在 Node 服务接入 Agent 前，先按只读、写入、支付等实际影响整理接口，并记录认证、分页、限流和错误码，再决定开放哪些工具。
• 把工具定义收敛到明确的业务动作，为参数设置类型约束，并裁剪返回字段，让模型更容易选择和消费结果。
• 在执行工具的服务端代码中检查权限，为 Agent 配置独立身份和短期任务凭证，避免依赖提示词约束访问范围。
• 接入写操作时，先设计幂等键与错误分类，再开放自动重试；对后果重大的动作保留审批，并分阶段上线。