当Agent成为客户，API应如何重构

我试用了 Holded 几周，体验非常糟糕。并不是因为它做得不好——它其实并不差。问题在于，它是为另一个时代打造的：你进入一个漂亮的 UI，点击操作，手动上传发票，再查看仪表盘。

问题是，我现在几乎已经不再亲自打开网站了。我会直接询问 Agent，而 Agent 用不了漂亮的 UI。

这句话听起来像一句宣传口号，所以接下来我会把它落实为具体的技术决策。如果你认同 Agent 就是新的用户，那么产品中有四件事会随之改变，而且没有一件是“在页面角落添加一个 chatbot”。

1. OpenAPI 不再只是文档，而会成为产品界面

当用户是人类时，API 只是提供给集成开发者的附加能力。当用户是 Agent 时，API 才是产品，UI 反而成了附加能力。

这会带来一个令人不太舒服的结果：你的 spec 必须公开且完整，无须预先登录。如果要求 Agent 注册之后才能查看目录，它就无法发现你能做什么。

curl -s https://api.aikount.com/openapi.json | jq '.paths | keys | length'
# 345

345 个 endpoint，采用 OpenAPI 3.1，无须身份验证即可访问。如果你的 spec 藏在一个需要注册的开发者门户后面，那么对 Agent 而言，它就等于不存在。

2. Endpoint 必须使用领域语言，而不是数据库语言

这是我见过最多的错误，而我自己也最先犯过。

一个诚实的 CRUD 会暴露 PATCH /documents/{id}，然后让客户端自行判断：哪些字段组合起来才表示“把这笔账对上”。人类可以对照文档解决这个问题；Agent 却可能自己编造一种字段组合，而在会计领域，编造组合就意味着生成了一笔错误的会计分录。

另一种方案是暴露意图，而不是暴露数据变更操作：

POST /api/v1/reconciliations/auto
POST /api/v1/purchases/autogen-from-movements
GET  /api/v1/contacts/{contact_id}/tax-suggestion

这三个 endpoint 并不是 CRUD 之上的语法糖。每一个都封装了一项业务决策，而这些决策过去只存在于会计人员的脑子里。把它们作为独立 endpoint 暴露出来，可以同时获得两个好处：Agent 无须重新推导这些决策，而你也可以随时修改内部逻辑，不会破坏任何客户端。

一条实用原则是：如果 Agent 为了完成某件事，需要按照特定顺序串联四次调用，那么这个调用顺序本身，就是你缺少的那个 endpoint。

3. 有些操作 Agent 可以执行，另一些则绝不应该允许它执行

关于“给你的 Agent 提供工具”，有一件没人会告诉你的事：有些工具根本就不应该存在。

在会计领域，这条界线相当清晰：提出建议是可逆的，正式提交则不可逆。Agent 可以读取银行流水，把一笔收款与对应发票匹配起来，并提出记账建议。但未经人工检查，它不能关闭一个会计期间，也不能向西班牙税务局 AEAT 提交任何资料。

这类限制应该通过状态来建模，而不是依赖 prompt 里的良好意愿：

POST /api/v1/journal/{entry_id}/lock

一笔分录被锁定之后，Agent 就不能再修改它。Veri*Factu 记录通过 hash 串联，而且不接受“抱歉，我弄错了”这种解释，因此它拥有独立的资源和独立的重试机制：

GET  /api/v1/verifactu/records
POST /api/v1/verifactu/records/{record_id}/retry

注意，这里把 retry 设计成了一个显式 endpoint。当客户端是一个会自行重试的 Agent 时，重试必须是由你控制并记录的操作，不能是模型临时编出来的循环。如果 API 没有定义“重试”究竟意味着什么，Agent 就会替你做出定义，而通常的结果就是产生重复数据。

4. Agent 的 onboarding 本身就是一项产品能力

我们有一个名为“连接你的 AI Agent”的按钮。它会生成一把带有 scopes 的 API key，并提供一条已经组装好的命令，你可以直接把它交给 Claude、ChatGPT 或 Gemini。无须任何手动配置，也不用从 PDF 里复制 API 的 base URL。

身份验证采用 Bearer，既支持会话 JWT，也支持以 agl_ 为前缀的长 key：

Authorization: Bearer agl_...

这个前缀并不是装饰。当凭证意外泄漏到日志或代码仓库时，可识别的前缀能让你自动检测并撤销它。如果你的 key 只是一个裸 UUID，那就根本没有明确的特征可供搜索。

我们构建 Aikount，是为了解决自己的问题：只需发送一条 WhatsApp 消息，就能知道我的西班牙有限责任公司 SL 当前的真实状态，而不必打开管理面板，再连续浏览六个页面。它提供的是真正面向西班牙的会计能力，包括 PGC、Modelo 303、Veri*Factu，以及通过 PSD2 与银行连接。

但我从中获得的技术经验，远不止适用于这个垂直领域：

公开发布无需登录即可访问的 spec，否则对 Agent 来说，你就不存在。

暴露意图，而不是数据变更操作。如果调用必须按照固定顺序串联，就说明还缺少一个 endpoint。

从设计上区分可逆操作与不可逆操作，并通过状态实现这种区分，而不是依靠 prompts。

像对待用户 onboarding 一样对待 Agent 的接入，因为它本质上就是用户 onboarding。

如果你想亲自尝试，spec 已公开在 api.aikount.com/openapi.json。免费套餐支持每年最高 24,000 欧元的开票额，无须绑定银行卡，也不会把不同模块拆开收费。

我非常希望听到反方观点。因此，如果你认为暴露意图而不是 CRUD，会让 API 与业务领域耦合得过深，欢迎在评论区告诉我。这也是我思考最多的一项批评。

如需采取进一步措施，你可以考虑屏蔽此人和／或举报滥用行为。