Agent-First 工具 API 全文翻译：为 LLM 代理重造企业服务接口

结论

这是 arXiv 论文《Agent-First 工具 API：为 LLM 原生执行重新思考企业服务接口》（Agent-First Tool APIs: Rethinking Enterprise Service Interfaces for LLM-Native Execution）的全文中文翻译。作者是 A2A Lab 的 Kai Pan 与 Rong Hou，提交于 2026 年 5 月 11 日（v2 于 2026 年 8 月 20 日），采用 CC BY 4.0 许可，允许全文翻译与再发布。

原文的核心判断：LLM 代理正在成为企业软件系统的一等操作者，但它们调用的 API 仍然是为「人驱动的 UI」设计的。传统 CRUD 接口的五个假设（调用者知道精确参数、响应是可渲染数据、一次请求就够、权限等于用户权限、错误就是 HTTP 状态码）在调用者变成 LLM 规划器时全部崩塌。作者提出 Agent-First 工具 API 范式：六动词语义协议（semantic_search → resolve_candidates → preview_action → execute_action → verify_result → recover_from_error）、规范化工具契约 NTC（每个响应附带置信度、证据出处、建议下一步）、双层治理管线（能力权限+对象范围权限，动态风险升级+内建审批流）。在一个跨 6 个业务域、85 个工具的多租户 SaaS 生产系统上验证：任务成功率从 64% 提升到 88%，ID 幻觉错误从 28% 降到 4%，错误恢复率从 12.5% 提升到 72.7%，代价是单工具令牌开销 +300%（但任务级净开销反而下降）。

对企业启示：这篇论文给出了「让 Agent 可靠地操作业务系统」的完整工程蓝图——描述性输入代替精确 ID、写操作前预览、执行后验证、幂等键强制、风险分级审批。这些模式与 MCP 正交互补（MCP 管传输，Agent-First 管语义与治理），可直接用于企业工具网关与 Agent 平台的设计评审。

以下为忠实全文翻译。

原文全文翻译

标题与作者

Agent-First 工具 API：为 LLM 原生执行重新思考企业服务接口

Kai Pan、Rong Hou

单位：A2A Lab　邮箱：kaipan@a2alab.cn

摘要

大语言模型（LLM）代理正迅速成为企业软件系统的一等操作者，然而它们调用的 API 仍然是为人类驱动的 UI 设计的。传统 CRUD 接口假设调用者知道精确参数、返回不带决策支持元数据的原始数据，并且缺乏面向自主执行的内置治理。这种错配迫使代理开发者陷入脆弱的提示工程与临时的错误处理。

我们提出 Agent-First 工具 API 设计范式，把工具接口重新构想为「目标达成协议」而非「表单提交端点」。我们的方法引入三项核心贡献：（1）六动词语义协议（semantic_search、resolve_candidates、preview_action、execute_action、verify_result、recover_from_error），把每次工具调用结构化为一个多阶段推理循环；（2）规范化工具契约（Normalized Tool Contract，NTC），为每个响应附加置信度分数、证据出处与建议的下一步行动；（3）双层治理管线，把基于能力的权限与对象范围权限相结合，配合动态风险升级与内建审批工作流。我们在一个覆盖 6 个业务域、85 个工具的生产 SaaS 系统中验证了该范式。对比分析表明，Agent-First API 减少了歧义诱发的失败、实现了结构化错误恢复，并在无需外部编排层的情况下强制执行企业级访问控制——这些能力是传统 CRUD 接口所不具备的。

索引词：LLM 代理、工具 API、API 设计、企业治理、多租户系统、代理式 AI

I 引言

工具增强型大语言模型的出现催生了企业软件架构的根本转变。不再是人类操作员浏览图形界面，而是基于 LLM 的规划器自主地选择、参数化并调用后端服务。这一转变暴露出一个关键的设计错配：这些代理调用的 API 是为另一种消费者构建的。

传统 CRUD（创建、读取、更新、删除）API 体现了五个假设，当调用者是 LLM 规划器而非人类控制的前端时，这些假设全部崩塌：

假设 1：调用者知道精确参数。CRUD 端点期望精确标识符——门店 ID、用户 UUID、类别代码。然而 LLM 代理从一个自然语言目标出发（「找到上个月开业的市中心分店」），必须通过搜索与消歧把它解析成标识符。

假设 2：响应是可渲染的数据。REST API 返回为 UI 渲染设计的 JSON 载荷。代理不做渲染；它做推理。它需要置信度分数、证据出处与可执行的下一步建议——这些元数据在传统响应中是缺失的。

假设 3：一次请求就足够。CRUD 假设每个用户动作一次往返。代理运行在多轮推理循环中，每次工具调用产生的观察都为后续规划决策提供信息。

假设 4：权限等于用户权限。传统访问控制绑定到已认证的用户。当代理代表用户行动时，需要第二个权限层：这个工具被允许做什么——独立于用户的 UI 级权限。

假设 5：错误就是 HTTP 状态码。400 Bad Request 能告诉人类开发者哪里出了问题。代理需要结构化的失败描述——候选替代项、建议的更正，以及它无需人工干预就能执行的恢复策略。

这些错配不是表面问题；它们反映了一种范式鸿沟。关于函数调用、工具选择与代理框架的现有工作处理的是工具边界之上的编排，却把工具接口本身留作一个遵循传统 CRUD 约定的黑盒。

本文提出 Agent-First 工具 API 范式，把工具接口当作一等设计产物，为 LLM 原生消费而优化。我们的贡献是：

1. 六动词语义协议，把每次工具交互分解为搜索、消歧、预览、执行、验证与恢复阶段，提供代理所需的结构化推理脚手架。
2. 规范化工具契约（NTC）响应规范，为每个工具输出附加置信度、证据、结果引用与下一步行动建议，使代理能够做出知情的规划决策。
3. 双层治理管线，把基于能力的权限与四级对象范围隔离（租户→品牌→门店→用户）相结合，配合动态风险升级与内建审批工作流。
4. 生产验证：在多租户 SaaS 系统中跨 6 个业务域的 85 个工具上完成，附定量分析与案例研究，证明该范式的有效性。

我们强调，我们的贡献与 MCP 等传输层标准正交。MCP 标准化工具如何被发现与调用；我们处理工具应当暴露什么、响应应如何支持自主决策。两层互补：Agent-First 工具可以作为 MCP 服务器部署，把传输互操作性与语义可靠性结合起来。

II 背景与相关工作

II-A 函数调用标准

OpenAI 的函数调用 API 与 Anthropic 的工具使用协议标准化了 LLM 如何通过 JSON Schema 声明可用工具并接收结构化调用请求。这些工作聚焦工具的声明与调用格式，但对执行治理、响应语义或多阶段交互模式没有任何规定。

II-B 工具增强 LLM

Toolformer 证明 LLM 能学会在生成过程中插入 API 调用。Gorilla 训练模型从文档生成准确的 API 调用。ToolBench 与 API-Bank 构建了工具选择与排序的基准。TaskMatrix.AI 提出把基础模型与数百万 API 连接。这些工作处理「调用哪个工具、如何调用」，但假设工具接口是固定的、CRUD 形状的。

II-C 代理框架

LangChain、AutoGPT、CrewAI 与 MetaGPT 为多步代理执行提供编排层。ReAct 范式交错推理与行动；MRKL 路由到专家模块。这些框架定义了工具层之上的规划循环，但把单个工具当作返回非结构化结果的原子函数。

II-D API 网关与访问控制

Kong 与 Envoy 等 API 网关提供限速、认证与路由。OAuth 2.0 与 RBAC 定义访问控制模型。然而，它们运行在传输层或身份层，对代理特有的语义（如工具风险级别、多轮上下文、审批门控执行）毫无感知。

II-E 多代理通信协议

多代理系统的近期工作引入了通信协议，如 Google 的 Agent-to-Agent（A2A）协议及各种代理间消息标准。这些协议处理代理之间如何协调，但不规定单个代理应如何与底层工具层交互。我们的工作与之正交：它定义代理到工具的接口，任何多代理协议都可以构建其上。

II-F 模型上下文协议（MCP）

模型上下文协议（MCP）已成为 AI 代理生态中工具发现与调用传输的事实标准。MCP 标准化了代理如何发现可用工具（经 tools/list）与调用它们（经 JSON-RPC 的 tools/call），提供了一个通用的「插头形状」，类比网络中的 TCP/IP。

然而，MCP 刻意对工具语义保持不可知。它把工具当作黑盒：传统 CRUD 端点与 Agent-First 工具在 MCP 传输层无法区分。关键的是，当底层工具遵循传统 CRUD 设计时，第 I 节识别的五个架构错配在 MCP 兼容系统中完全持续存在：

• MCP 的输入模式仍要求精确参数值（如 UUID）；它对描述性输入不提供解析机制。
• MCP 响应是任意 JSON/文本内容，没有强制的决策支持元数据（置信度、证据、下一步行动）。
• tools/call 是单次请求-响应交换；MCP 未定义多阶段交互协议。
• MCP 把授权完全委托给工具实现；它不指定治理管线或风险评估。
• MCP 错误响应（isError: true 加文本消息）不提供结构化恢复指导。

用网络术语说，MCP 提供传输层与会话层，而我们的 Agent-First 范式运行在应用层。MCP 解决连通性；Agent-First API 解决可靠性与可治理性。

II-G 研究缺口

表 I 总结了现有方法的覆盖范围。没有先前工作系统地定义「代理原生的工具 API 应该长什么样」——它应如何接受输入、构造输出、执行权限并支持多阶段交互。Agent-First 工具 API 范式填补了这一缺口。

表 I：研究缺口分析——现有方法的覆盖范围

\* 兼容：Agent-First 工具可以作为 MCP 服务器暴露，继承 MCP 的发现与传输能力，同时增加语义与治理层。 † 标记为部分，因为这些框架在代理层支持多轮编排，但底层工具接口缺乏原生的多阶段交互协议（例如没有内建预览语义或结构化验证反馈）。

III Agent-First 工具 API 设计

III-A 六动词语义协议

我们定义一个工具交互协议，由六个语义动词构成，把每次代理-工具交换结构化为一个目标达成循环。设 T 表示工具，q 表示代理的自然语言意图。

我们首先给出协议的形式化有限状态机（FSM）：

定义 1（协议 FSM）。协议 Π(T,q) 是一个七元组状态机 (Q, Σ, δ, q_init, F, q_error)，其中：

• 状态集：Q = {q_init, q_candidates, q_resolved, q_previewed, q_executed, q_verified, q_error}
• 字母表：Σ = {S, R, P, E, V, C, failure}
• 转移函数 δ：
• δ1：δ(q_init, S) = q_candidates
• δ2：δ(q_candidates, R) = q_resolved
• δ3：δ(q_resolved, P) = q_previewed
• δ4：δ(q_previewed, E) = q_executed
• δ5：δ(q_resolved, E) = q_executed（跳过预览）
• δ6：δ(q_executed, V) = q_verified
• δ7：δ(q_error, C) = q_resolved（恢复）
• δ8：δ(q_*, failure) = q_error（任意状态）
• 终止：F = {q_verified} ∪ {q_executed | mode=read}

该 FSM 保证任何有效任务都不会永久停滞：每个非终止状态都至少有一条出边转移，且错误状态总是允许经 C 恢复。

定义 2（六动词协议）。一次完整的工具交互是一个序列：Π(T,q) = ⟨S, R, P, E, V, C⟩（式 1），各阶段定义如下：

阶段 1：语义搜索（S）。给定意图 q，工具返回一个排序候选集 C = {(c_i, s_i)}，其中 c_i 是候选实体，s_i ∈ [0,1] 是相关性分数。S(T,q) → {(c_i, s_i) | s_i ≥ τ_s}（式 2）。与 CRUD 的精确匹配 GET /resource?id=X 不同，语义搜索接受描述性、含糊或部分的输入。

阶段 2：解析候选（R）。当 |C| > 1 且没有候选的 s_i ≥ τ_r（自动解析阈值）时，工具返回一个消歧提示：若存在 s_i ≥ τ_r 则返回 c*，否则返回 disambiguate(C)（式 3）。

阶段 3：预览行动（P）。在改变状态之前，工具产生一个试运行摘要，显示将会改变什么：P(T, c*, θ) → (Δ_preview, risk_assessment)（式 4），其中 θ 是行动参数，Δ_preview 是投影的状态差异。

阶段 4：执行行动（E）。工具在事务边界内应用变更：E(T, c*, θ) → (r, audit_record)（式 5）。写模式工具通过调用方提供的幂等键强制幂等性。

阶段 5：验证结果（V）。执行后，工具重读受影响的状态并与代理的原始意图比较：V(r, q) → (match: bool, evidence: E)（式 6）。

阶段 6：从错误恢复（C）。在任何阶段失败时，工具返回结构化恢复指导：C(error) → (cause, candidates, suggestion)（式 7），而不是不透明的 HTTP 错误码。

并非每次调用都遍历全部六个阶段。只读工具通常只使用 S（可选地加 R）。协议是一个能力包络：工具通过其 ToolDescriptor 声明它支持哪些动词。

算法 1：代理-工具交互循环（伪代码要义）：输入代理意图 q、工具 T、阈值 τ_s、τ_r；输出结果 r 或结构化错误。步骤：① C ← S(T,q)（语义搜索）；② 若 C 为空，返回 C("no_match")；③ 若 |C|=1 或存在 s_i ≥ τ_r，取 c* 为分数最高者，否则 c* ← agent_disambiguate(R(C))；④ 若 T.mode ∈ {write, commit}：(Δ, risk) ← P(T, c, θ)；若风险要求审批则挂起等待审批；(r, audit) ← E(T, c, θ)；(match, E) ← V(r, q)；若不匹配，返回 C("verification_failed", E)；⑤ 否则（只读）：r ← NTC(answer=summarize(C), refs=C)；⑥ 返回 NTC(r)。

III-B ToolDescriptor：声明式工具注册

每个工具通过一个声明式描述符注册，为 LLM 规划器提供足够的元数据以做出知情的工具选择。

清单 1：ToolDescriptor 模式

ToolDescriptor = {
  "name": str,               # 动词.名词 格式
  "domain": str,             # 业务域
  "mode": enum("read","write","commit"),
  "source": enum("system","third_party","mcp","model_native","skill","ops_cli"),
  "risk_level": enum("low","medium","high","critical"),
  "approval_required": bool,
  "input_schema": JSONSchema,
  "output_schema": JSONSchema,
  "permission_policy": {"capability": str, "object_scope": str},
  "idempotency_key_fields": [str],
  "supported_verbs": [str],
  "description": str         # 给 LLM 的自然语言描述
}

mode 字段具有架构意义。read 工具没有副作用，可以推测性地调用。write 工具在调用者范围内改变状态。commit 工具产生不可逆或跨范围的效果（例如向所有门店发布内容），总是需要预览并可能需要审批。

source 字段支持出处感知的规划。系统原生工具有保证的 SLA；第三方与 MCP 工具可能有延迟波动；模型原生工具（如摘要）在进程内运行。

III-C 规范化工具契约（NTC）

NTC 把每个工具响应标准化为一个 LLM 规划器可以在其上推理的决策支持结构。

清单 2：规范化工具契约

NTC = {
  "ok": bool,
  "answer": str,             # 给规划器的自然语言摘要
  "tool_contract_version": 1,
  "result_refs": [{"type": str, "id": str, "title": str, "actions": [str]}],
  "requires_confirmation": bool,
  "confidence": float,       # ∈ [0,1]
  "evidence": [{"type": str, "detail": any}],
  "next_actions": [{"action": str, "label": str, "ref_count": int}]
}

NTC 服务四个关键功能：

（a）决策支持。confidence 字段（∈[0,1]）让规划器决定是继续、寻求确认还是尝试替代工具。低于 0.7 的分数触发自动消歧。

（b）证据出处。evidence 数组提供可验证的依据——匹配计数、应用的过滤条件、查阅的来源——使规划器能审计自己的推理链。

（c）行动连续性。next_actions 数组建议合乎逻辑的后续工具，缩小规划器的搜索空间，防止走进死胡同的工具序列。

（d）结果可追溯性。result_refs 数组携带带类型的实体引用，下游工具可以直接消费，消除对自然语言描述的重新解析。

置信度校准。工具作者指定的静态置信度分数提供了基线，但不适应运行时表现。我们引入一个基于贝叶斯更新的滑动窗口校准机制。设 c_static 表示作者指定的置信度，p̂_w 表示最近 w=100 次调用的经验成功率。校准后的置信度为：

c_calibrated = α·c_static + (1−α)·p̂_w，α = 0.3（式 8）

这一公式保留了工具作者的先验知识（权重 30%），同时让观测到的表现占主导（70%）。在我们的 85 个生产工具中，校准后的置信度分布为 μ=0.78、σ=0.12、范围 [0.45, 0.95]。c_calibrated < 0.5 的工具被标记供开发者审查，因为持续的低置信度表明存在设计问题或领域错配。

为验证校准，我们抽取了 20 个已解决的代理任务，把工具报告的置信度与人工标注的正确性做比较。期望校准误差（ECE）为 0.087，表明中等程度的对齐。虽然绝对 ECE 表明校准精度仍有改进空间，但置信度分数表现出高判别力：高置信度（>0.8，实际成功率 91%）与低置信度（<0.6，48%）工具之间 43 个百分点的实际成功率差距，证实了它作为规划器行动选择决策信号的可靠性。

III-D 描述性输入优于精确 ID

Agent-First API 的一个定义性原则是：工具接受描述性输入并在内部执行解析，而不是要求调用者提供精确标识符。

考虑一个工单创建场景。CRUD API 要求：

POST /api/tickets/
{"store_id": "550e8400-e29b-41d4-a716", "category_id": 7, "assignee_id": "user_42"}

Agent-First 的等价物接受：

ticket.create({"store": "downtown branch", "category": "equipment maintenance", "assignee": "the morning shift manager"})

工具内部对每个描述性字段调用 semantic_search，解析候选，并返回带置信度分数的 NTC 响应。如果「downtown branch」匹配两家门店，工具返回消歧提示，而不是以 404 失败。

这一设计把解析负担从 LLM 的上下文窗口（幻觉风险高）转移到确定性后端逻辑（精确匹配与模糊搜索可靠）。

IV 企业治理管线

企业环境中的自主代理执行要求超越传统 API 安全的治理机制。我们提出一个六层验证管线与一个带动态风险升级的双层权限模型。

IV-A 六层验证管线

每次工具调用在到达处理器之前都经过六个验证阶段：

1. 模式验证（Schema Validation）。输入参数对照工具的 input_schema（JSON Schema）验证。类型不匹配、缺失必填字段与约束违规以结构化错误消息捕获，引导代理自我纠正。
2. 能力权限（Capability Permission）。代理的角色对照能力矩阵检查：角色 r 是否有权限调用工具 t？这是一个粗粒度的 RBAC 式检查。
3. 对象范围（Object Scope）。即使角色拥有能力，它也只能操作其范围内的对象。我们强制一个四级层级：范围 = 租户 ⊃ 品牌 ⊃ 门店 ⊃ 用户（式 9）。门店经理只能在其分配的门店内搜索工单。
4. 风险评估（Risk Assessment）。工具的基础 risk_level 基于运行时因素动态调整（见 IV-C 节）。
5. 审批门（Approval Gate）。若评估的风险超过自动执行阈值，请求被挂起，参数快照被持久化，审批请求被派发。只有批准后才恢复执行。
6. 执行（Execution）。经过验证与批准的请求在事务边界内到达工具处理器。

（图 1：代理工具调用的六层验证管线：请求 → 1.模式验证 → 2.能力权限（RBAC）→ 3.对象范围（租户/品牌/门店/用户）→ 4.动态风险评估 → 5.审批门 → 6.处理器执行。）

IV-B 双层权限模型

传统 RBAC 把「我能做什么」（能力）与「我能看到什么」（对象范围）混在单一权限检查里。代理执行要求分离这两种关切：

第 1 层：基于能力的权限。能力矩阵 M ∈ {0,1}^{|R|×|T|} 把角色 R 映射到工具 T。例如，「store_manager」角色可以调用 ticket.create 与 ticket.search，但不能调用 brand.config.update。能力是静态的，在部署时配置。

第 2 层：对象范围权限。在运行时，每次数据访问都被代理的组织范围过滤。「门店 A」的门店经理调用 ticket.search 时只收到属于门店 A 的工单，即使工具本身有能力查询所有工单。

这种分离确保能力检查快速（矩阵查找）而范围检查准确（查询时过滤）。关键的是，工具发现只按租户划定范围——租户内发布的所有工具对该租户全体成员可见——而执行按完整层级划定范围。

IV-C 动态风险升级

静态风险级别对企业环境不够。一个 ticket.create 工具在创建一张工单时是低风险的，在批量创建 50 张时是中风险的。我们定义五个运行时风险因子：

表 II：动态风险升级因子

最终风险级别为：risk_final = clamp(risk_base + Σ_i δ_i, low, critical)（式 10），其中 risk_base 由工具注册的 risk_level 字段决定，编码为 low=0、medium=1、high=2、critical=3。

从最终风险级别到审批要求的映射是：risk_final ≥ 2（high）⇒ requires_approval = true。处于低或中最终风险的工具立即执行，无需人工干预。

跨品牌协作。在多品牌组织中，总部角色拥有一个 cross_brand 能力标志。当该标志存在时，跨品牌升级因子（+1 级）被自动豁免，防止对授权人员的合法跨品牌操作产生不必要的审批开销。

跨租户操作被无条件阻断，不论风险计算结果如何——这是一条硬隔离边界。

IV-D 审批集成

当工具调用触发审批门时，系统：

1. 把完整调用上下文（工具名、参数、已解析实体、风险评估）序列化为持久快照。
2. 基于工具的 permission_policy 向指定审批人派发审批请求。
3. 挂起代理的执行链，返回一个 requires_confirmation: true 并附预计等待时间的 NTC 响应。
4. 批准后，反序列化快照并从精确挂起点恢复执行，确保无参数漂移。
5. 拒绝后，返回带审批人理由的结构化拒绝，代理可将其呈现给用户。

这一设计消除了对外部工作流引擎的需要。审批是工具执行运行时的原生原语。

非阻塞审批。关键的是，审批等待不阻塞代理的执行线程。当调用触发审批门时，代理收到一个 requires_confirmation: true 与 pending_approval_id 的 NTC 响应。代理随后可以继续其他任务、告知用户待处理状态，或规划替代行动。批准（或拒绝）后，系统派发一个异步回调来恢复挂起的执行链——代理经事件流收到通知，可以把结果纳入其下一个规划周期。这一设计防止单个高风险操作死锁整个代理会话。

V 实现与架构

V-A 系统总览

Agent-First 工具 API 范式实现在一个生产级多租户 SaaS 工单管理系统内。技术栈包括：

• 后端：Django 4.x 与 Django REST Framework（DRF）用于 CRUD API 层；自定义工具运行时用于 Agent API 层。
• 流式：Server-Sent Events（SSE）用于实时代理响应流。
• 数据库：PostgreSQL 加 pgvector 扩展，用于语义搜索索引。
• 任务队列：Celery 加 Redis，用于异步工具执行与审批工作流。
• 规模：跨 6 个业务域的 85 个注册工具，核心运行时代码超过 7,000 行。

V-B 端到端调用链

一次完整的代理交互遍历以下管线：用户自然语言输入 → 对话 API（SSE）→ 记忆简报构建 → LLM 规划器（工具选择）→ 网关管线［模式→能力→范围→风险→审批］→ 工具处理器 → NTC 规范化 → 规划器观察 → 下一步行动/最终响应。

LLM 规划器接收 NTC 格式的观察，决定是调用另一个工具（继续推理循环）还是为用户合成最终响应。该循环持续到规划器判定用户目标已达成，或遇到不可恢复的错误。

V-C 双 API 架构

一个关键架构决策是维护两个平行的 API 表面：

传统 CRUD API 服务人类操作的管理仪表盘。它遵循 RESTful 约定：面向资源的 URL、分页列表视图、表单兼容的输入模式。这些端点驱动用 Vue.js 构建的管理面板。

Agent 工具 API 专门服务 LLM 规划器。它使用动词-名词命名（ticket.search、store.resolve），接受描述性输入，返回 NTC 格式的响应。

两个 API 层共享相同的底层 Django 模型、权限框架与审计日志基础设施。它们只在接口形状上分叉——输入接受模式、响应格式与交互协议。这一共享基础确保一致性：经 Agent 工具 API 创建的工单与经 CRUD API 创建的工单在数据库中无法区分。

（图 2：双 API 架构——人类 UI 与 LLM 代理分别经 CRUD API（DRF）与 Tool API（NTC）汇聚到共享的模型+权限+审计层，再到 PostgreSQL + Redis + Celery。）

V-D 工具命名约定与发现

工具遵循严格的「动词.名词」命名约定（如 ticket.search、brand.config.update、training.build.run），服务双重目的。对 LLM 规划器，名称本身编码了行动与目标领域，减少对冗长描述解析的需要。对治理管线，层级化名称支持通配符能力规则（例如授予某角色 ticket.* 访问权）。

工具发现按租户划定范围：租户内发布的所有工具对该租户全体成员可见。这一设计选择反映「可见性不是授权」原则。门店店员可以看到 brand.config.update 存在，但会被能力层拒绝执行。这种透明性使 LLM 规划器能对完整能力空间做推理，并在请求的行动不可用时生成有信息量的解释（「我能看到品牌配置工具存在，但你的角色没有使用权限」）。

V-E 幂等性与事务安全

所有写模式与提交模式工具通过调用方提供的幂等键强制幂等性。键由工具的 idempotency_key_fields 指定的输入参数子集计算。若在可配置窗口（默认 24 小时）内检测到重复键，工具返回首次执行的缓存结果而不是重新执行。

这对代理可靠性至关重要。LLM 规划器可能因超时、含糊观察或上下文窗口截断而重试工具调用。没有强制幂等性，重试的 ticket.create 会产生重复工单。通过把幂等性做成框架级保证而非可选的工具特性，我们消除了整类代理诱发的数据损坏。

V-F 可复现性：完整 NTC I/O 示例

为便于复现，我们提供两个代表性工具的完整请求-响应示例，展示 NTC 契约的实际形态。

示例 1：ticket.search（只读模式工具，仅阶段 S）。请求：{"tool": "ticket.search", "input": {"query": "overdue maintenance tickets at downtown", "filters": {"status": "open"}}}。NTC 响应（节选）：ok: true；answer:「在市中心分店找到 3 张开放的维护工单，其中 2 张已逾期」；result_refs 携带三张工单的类型/ID/标题/可用动作；requires_confirmation: false；confidence: 0.92；evidence 包含 {type: "count", detail: {total: 3, overdue: 2}} 与 {type: "match", detail: {store: "Downtown Branch", match_score: 0.97}}；next_actions 建议 ticket.update（更新逾期工单优先级，ref_count 2）与 ticket.escalate（把逾期工单上报经理，ref_count 2）。

示例 2：ticket.create（写模式工具，阶段 S→R→P→E）。展示描述性输入（"store": "downtown branch"）经语义搜索返回多个候选、消歧、预览（含自动分配的处理人、预估优先级与投影 SLA）后执行，返回 confidence 0.95 与 result_refs [{type: "ticket", id: "T-2024-0042"}] 的 NTC。

VI 评测

我们沿四个维度评测 Agent-First 工具 API 范式：端到端对比实验、定量工具分布分析、动词覆盖分析与展示端到端行为的案例研究。

VI-A 端到端对比实验

为量化 Agent-First 设计的实际影响，我们在相同 LLM 与提示条件下做了一个受控实验，比较两种 API 范式。

实验设置。我们选择了跨 6 个业务域（工单管理、门店运营、培训、SOP 合规、资源管理与品牌配置）的 50 个代表性自然语言任务。每个任务在两种配置下执行：

• 基线（CRUD+ReAct）：MiniMax-M2.7 LLM 配传统 CRUD REST API 与标准 ReAct 提示。代理必须自行解析 ID、经 HTTP 状态码处理错误，并在无结构化指导下重试。
• Agent-First：同一 MiniMax-M2.7 LLM 配 Agent-First 工具 API（六动词协议、NTC 响应）与相同的 ReAct 提示。代理利用语义搜索、结构化消歧与 NTC 引导的下一步行动。

对 CRUD 基线，代理被提供详尽的 API 文档与针对 ID 查找和结构化错误重试优化的少样本提示，确保它代表传统范式下可达到的最佳表现。

两种配置使用相同的系统提示模板、温度设置（t=0.1）与最大轮数限制（每任务 10 轮）。任务由两名人类评估员判定成功/失败，评估者间一致性 Cohen's κ = 0.91。

结果。表 III 给出对比指标。

表 III：端到端对比实验结果（n=50 任务）

关键发现。Agent-First 范式实现了任务成功率 37.5% 的提升与错误恢复 5.8 倍的改善。这些收益有可度量的代价：平均延迟高 48%、令牌消耗高 37%，归因于多阶段验证协议。然而，歧义诱发失败的显著减少（从 28% 到 4%）证明这些成本是值得的，确认了「描述性输入接受 + resolve_candidates」的组合有效消除了 LLM 代理操作 CRUD API 的主要失败模式——幻觉或错误的标识符。

尽管有多阶段协议，平均 API 调用反而减少（4.8 → 3.2），解释在于消除了探索性重试循环：CRUD 代理经常做出失败了的投机调用，而 Agent-First 代理接收 next_actions 指导，被引向正确的后续工具。

VI-B 定量分析

VI-B1 工具分布。表 IV 总结了 85 个生产工具在模式、风险级别与审批要求上的分布。

表 IV：按模式、风险与审批的工具分布

该分布揭示了一个刻意设计：大多数工具（52.9%）是读模式，让代理自由收集信息。写与提交工具构成其余 47.1%，其中近四分之一需要显式审批——反映企业治理姿态。

VI-B2 Agent-First 与 CRUD 对比。表 V 沿十个设计维度系统比较 Agent-First 工具 API 与传统 CRUD API。

表 V：Agent-First 工具 API vs 传统 CRUD API——设计对比

VI-B3 领域覆盖。表 VI 显示工具在各业务域的分布：培训 16（build.run、course.create）、运营 12（brand.search、user.role.assign）、门店时间线 9（timeline.search、timeline.link）、第三方 8（sync.run、mapping.apply）、资源 7（asset.search、asset.create）、SOP 6（item.search、item.create）、工单 5（ticket.search、ticket.create）、其他 22（memory、capability、ai_event）。

VI-C 案例研究：工单创建流程

我们追踪一个代表性场景——「为市中心分店创建一张维护工单」——在两种范式下的路径。

Agent-First 路径（5 阶段）：

1. store.semantic_search("downtown branch") → 返回 2 个候选，置信度 0.85 与 0.72。
2. store.resolve_candidates([store_A, store_B]) → 代理基于上下文选择门店 A。
3. ticket.preview_action(store=A, category="maintenance") → 返回带自动分配处理人、预估优先级与投影 SLA 的草稿。
4. ticket.execute_action(confirmed_draft) → 创建工单，返回 confidence: 0.95 与 result_refs: [{type: "ticket", id: "T-2024-0042"}] 的 NTC。
5. ticket.verify_result("T-2024-0042") → 确认工单存在、匹配意图，返回证据。

CRUD 路径（3 步，但脆弱）：

1. 用户经下拉框手动查找门店 ID → GET /api/stores/?search=downtown。
2. 用户用 store_id、category_id、assignee_id 填表 → POST /api/tickets/。
3. 无自动验证；用户目视检查结果页。

Agent-First 路径涉及更多 API 调用，但提供关键优势：（a）消歧被优雅处理而不是静默失败；（b）预览阶段在状态变更之前捕获错误；（c）执行后验证自动闭合反馈环。CRUD 路径更短，但假设调用者（或其背后的人）在 ID 选择上不出错——当调用者是易幻觉标识符的 LLM 时，这一假设失效。

VI-D 风险升级有效性

我们分析动态风险升级系统在生产调用中的行为：

表 VII：风险升级统计

跨品牌自动升级达到 100% 准确率，因为它是一条确定性规则（任何触及不同品牌实体的操作触发 +1 风险级），而非概率分类器。误报升级（被不必要升级的操作）保持在 2% 以下，表明风险因子设计避免了过度保守。

在 4 周评测期的 1,247 次写/提交调用中，发生了 23 次误报升级（1.84%）。一个代表性案例：一位总部运营经理的跨品牌库存查询被升级，因为系统缺少为新入职角色配置的 cross_brand 能力标志——通过更新该角色的能力集解决。

VI-E 动词覆盖分析

并非所有工具都需要完整六动词协议。表 VIII 刻画了我们 85 个生产工具的实际动词覆盖。

表 VIII：生产工具的六动词协议覆盖

该分布确认了一个设计原则：协议是能力包络，不是强制管线。只读工具（44.7%）只实现语义搜索（S），这对信息检索任务足够。动词的渐进增加与运营风险相关：修改状态的工具增加解析（R）与执行（E）；有不可逆效果的工具增加预览（P）与验证（V）；只有最高风险工具实现完整恢复（C）阶段。

关键的是，当工具缺少某些阶段时，规划器跳过那些阶段，但不会退化为 CRUD 式行为。NTC 响应结构无论动词覆盖如何都始终存在——即使是仅 S 的工具也返回置信度、证据与下一步行动。缺少某个动词意味着该阶段不适用，而不是工具回退到非结构化响应。

VI-F 性能开销分析

Agent-First 范式引入了必须与其可靠性收益权衡的可度量开销。

令牌开销。一个 NTC 响应平均 320 令牌，而原始 JSON CRUD 响应为 80 令牌——每响应增加 300%。然而这一单工具成本在任务级被抵消：因为 next_actions 指导平均每任务消除 1.6 次探索性重试调用，净令牌预算向有利方向移动。

表 IX：令牌与延迟开销分析

负值表示消除重试尝试带来的节省。每工具开销反映 NTC 格式化相对原始 JSON 响应的额外成本；每任务净开销计入完整代理任务生命周期中的重试减少。

延迟分解。多阶段协议平均每次工具调用增加 1.5 秒（主要来自预览与验证阶段）。然而失败的 CRUD 调用触发的重试循环平均每次失败浪费 2.8 秒。由于 Agent-First 工具失败频率更低（错误恢复率 72.7% vs 12.5%），任务级净延迟平均减少 1.3 秒。

成本收益总结。开销模式一致：Agent-First 的单次调用成本更高，但单任务成本更低。这一权衡对企业部署有利——在那里任务完成可靠性比单次调用延迟更重要，且人工干预（CRUD 22% vs Agent-First 6%）带有可观的运营成本。

VII 讨论

局限。六动词语义协议目前通过 mode 字段与工具命名约定强制执行，而非形式化接口契约。工具不被要求实现全部六个动词；许多读模式工具只实现 semantic_search。一个形式化类型系统或接口定义语言（IDL）将强化合规保证。

NTC 置信度分数目前由工具作者指定而非学习得到。一个基于历史调用结果训练的校准置信度模型可以改善规划器的决策质量。

我们的评测在单一生产系统内进行。虽然该系统是多租户的并横跨六个业务域，用不同技术栈（如 Java/Spring、Go 微服务）做跨系统验证将强化普适性主张。

LLM 选择与普适性。虽然更强的前沿模型（如 GPT-4o）可能通过优越的推理在 CRUD 环境中表现出更好的错误恢复，但精确 ID 要求与自然语言意图之间的根本错配仍然是架构性的。我们的范式把解析负担从模型的概率推理转移到确定性后端逻辑，提供即使最强 LLM 也无法仅靠提示词交付的正确性保证。选择 MiniMax-M2.7 作为评测模型证明 Agent-First API 即使用中档模型也带来可观收益，暗示该范式的收益与模型能力扩展正交。

与 MCP 的关系。MCP 定义了工具发现与调用的传输层标准。我们的范式正交且互补：MCP 充当传输层（工具发现与 RPC 调用），Agent-First API 充当语义应用层（交互协议、响应契约与治理管线）。

一个 Agent-First 工具可以通过直接的映射无缝暴露为 MCP 服务器：（1）ToolDescriptor 直接映射到 MCP 的 tools/list 模式，input_schema 充当 MCP 工具的 inputSchema；（2）六动词协议中的每个动词可以暴露为独立的 MCP 工具端点（如 ticket.search、ticket.preview、ticket.execute），或在有状态的 MCP 会话内编排；（3）NTC 响应被序列化为 MCP tools/call 响应中的 content 字段；（4）治理管线在返回结果前于服务端执行，对 MCP 客户端透明。

这一分层架构意味着采用 Agent-First 设计不需要放弃 MCP——相反，它用自主企业代理所需的语义丰富性与安全保证增强 MCP 兼容工具。没有 Agent-First 语义的 MCP 只是加速了对仍表现出第 I 节所述 CRUD 失败模式的工具的访问；MCP 之上的 Agent-First 把互操作性与可靠性结合起来。

双 API 维护成本。维护两个 API 表面（CRUD + Agent）带来工程开销。依我们的经验，成本被三个因素缓解：（a）两个 API 共享相同的 Django 模型与业务逻辑层，只有接口翻译被重复；（b）Agent 工具 API 比 CRUD API 更粗粒度（85 个工具 vs 超过 200 个 REST 端点），减少了表面积；（c）NTC 规范化层是通用的，每个工具只需要一个薄适配器。

普适性。虽然在工单管理系统中验证，该范式的核心抽象——语义动词、NTC 响应、双层权限、动态风险——是领域无关的。任何 LLM 代理与后端服务交互的企业系统（ERP、CRM、ITSM、HRM）都可以采用 Agent-First API 模式。关键前提是组织愿意维护共享公共数据层的两个 API 表面。

框架集成。一个自然的问题是 Agent-First 工具如何与 LangChain、LlamaIndex 等现有代理框架集成。我们识别两种可行的适配模式：

模式 1：动词级分解。六动词工具的每个动词注册为 LangChain 中独立的 StructuredTool（如 ticket_semantic_search、ticket_resolve_candidates、ticket_execute_action）。所有工具共享一个公共 NTC 响应解析器，把置信度、证据与下一步行动提取到代理的观察格式中。该模式保留框架原生的工具选择机制，同时暴露完整多阶段协议。

模式 2：生命周期包装器。整个六动词循环封装在单一 AgentTool 中，内部编排 S→R→P→E→V→C 序列。包装器接受自然语言目标，基于工具的 supported_verbs 执行相应阶段，返回统一的 NTC 结果。该模式集成更简单，但牺牲了规划器在阶段之间干预的能力。

实践中，高风险工具优先用模式 1（规划器应在确认执行前审查预览），低风险只读工具适合模式 2（完整循环是机械的）。混合方法——读模式工具用模式 2、写/提交模式工具用模式 1——结合两者优点。

未来工作。三个方向值得研究：（1）工具组合安全的形式化验证——证明任意工具调用序列保持系统不变量；（2）用来自规划器反馈的强化学习做自动 NTC 置信度校准；（3）把双层权限模型扩展到支持跨组织代理委托（例如供应商的代理在客户的租户内以受限能力运行）。此外，我们计划探索六动词协议如何扩展以支持长时间运行的异步工具（如耗时数小时的训练数据管线构建），带进度报告与部分结果交付。我们还计划用过程代数（如 CSP 或 π-演算）形式化验证六动词协议，证明无死锁性与完备性，确保没有有效任务会永久卡在中间状态。

VIII 结论

本文引入了 Agent-First 工具 API 范式——为 LLM 原生执行对企业服务接口的系统性重新设计。通过用六动词语义协议替代 CRUD 的表单提交模型、经规范化工具契约标准化响应、并通过带动态风险升级的双层权限管线嵌入治理，我们弥合了 LLM 代理如何推理与传统 API 如何行为之间的根本鸿沟。

我们的生产部署——多租户 SaaS 系统中跨 6 个业务域的 85 个工具——证明该范式在实践中可行、架构上合理，并能有效实现自主代理执行，同时保持企业级访问控制与可审计性。Agent-First 工具 API 不仅是一次 API 重设计；它是生产企业环境中可信代理式 AI 的先决条件。

（参考文献：原文列出 25 条参考文献，包括 Toolformer、Gorilla、ToolBench、API-Bank、TaskMatrix.AI、OpenAI 函数调用、Anthropic 工具使用、MCP、ReAct、MRKL、LangChain、AutoGPT、CrewAI、MetaGPT、Kong、Envoy、OAuth 2.0、RBAC、A2A 协议等；此处按学术惯例不逐条翻译，读者可查原文。）

中文解读与企业落地方法

原文对企业最有价值的四个判断

第一，五大 CRUD 假设的崩塌清单是一份现成的工具接口评审标准。企业在建 Agent 平台或工具网关时，可以把五个假设当作检查表：工具是否要求精确 ID？响应是否只有原始数据？是否假设单次调用？权限是否只有用户一层？错误是否只是状态码？五项中任何一项为「是」，该工具对 Agent 就是不友好的。

第二，「描述性输入+后端确定性解析」是消灭 ID 幻觉的正确分工。实测数据：ID 幻觉错误从 28% 降到 4%。原则是把解析负担从 LLM 上下文窗口（幻觉高发区）移到确定性后端（精确匹配可靠）。这一分工思想适用于所有 Agent-系统集成场景，不只是工单系统。

第三，双层权限模型给了多租户 SaaS 一个可直接抄的答案。能力矩阵（角色×工具，静态）+对象范围（租户⊃品牌⊃门店⊃用户，查询时过滤）+「可见性不是授权」的工具发现策略+跨租户硬阻断，四件套构成了代理权限治理的最小完备集。动态风险升级的七因子表（受影响数量、跨品牌、覆盖已发布、批量、不可逆、单实体、同门店）可直接作为企业审批策略的起点。

第四，成本账要算在任务级而不是调用级。NTC 每响应多 240 令牌（+300%），但任务级净省 680 令牌、净省 1.3 秒延迟——因为结构化指导消除了 1.6 次探索性重试。这提醒企业：评估 Agent 基础设施改造的 ROI 时，用「每任务成本」与「人工干预率」（22%→6%）作为主指标，单调用开销是误导性指标。

落地步骤

1. 工具接口审计：盘点现有供 Agent 调用的 API，按五大假设逐条打分，输出「Agent 友好度」清单。
2. 按动词覆盖分级改造：读工具只加语义搜索+NTC 包装（44.7% 的工具属于此类，改造成本低）；写工具加解析+执行+幂等键；不可逆工具加预览+验证；最高风险工具加恢复。
3. 实施 NTC 响应契约：所有工具响应统一包装为 ok/answer/confidence/evidence/result_refs/next_actions/requires_confirmation 结构；置信度用「作者先验 30% + 近 100 次成功率 70%」滑动校准，低于 0.5 的工具触发人工审查。
4. 搭六层验证管线：模式验证→能力权限→对象范围→动态风险评估→审批门→执行，作为工具网关的强制路径；审批用快照挂起+异步回调，不阻塞代理会话。
5. 幂等键框架级强制：写/提交工具一律要求调用方幂等键，重复键返回缓存结果（默认 24 小时窗口）。
6. 与 MCP 分层共存：把 Agent-First 工具暴露为 MCP 服务器（ToolDescriptor→tools/list，NTC→content），传输归 MCP、语义与治理归工具层。

人工复核点与失败条件

• 失败条件：让 LLM 在上下文里自行解析实体 ID（幻觉高发）——解析必须在后端确定性完成。
• 失败条件：写操作没有预览阶段就执行（原文预览是捕获错误的关键关口）。
• 失败条件：审批等待阻塞代理线程（必须异步回调，防止单操作死锁会话）。
• 失败条件：跨租户操作参与风险计算（原文：无条件硬阻断，不做权衡）。
• 人工复核点：risk_final ≥ high 的操作审批；置信度 <0.7 触发的消歧；验证失败（verification_failed）后的处置决策。

试点与验收

• 试点场景：选一个 Agent 需操作业务系统的场景（工单、审批、报表、配置管理均可），改造 5—10 个工具为 Agent-First 接口。
• 试点周期：8 周。第 1—2 周：工具审计与 NTC 契约设计；第 3—5 周：动词分级改造+六层管线；第 6—7 周：50 任务级对比实验（CRUD vs Agent-First，同一模型）；第 8 周：复盘。
• 基线：CRUD+ReAct 的任务成功率、ID 幻觉率、错误恢复率、人工干预率、每任务调用数与令牌消耗（参照原文：64%、28%、12.5%、22%、4.8、1,840）。
• 验收指标：
• 质量：任务成功率 ≥85%（原文 88%）；ID 幻觉 ≤5%；错误恢复率 ≥70%。
• 治理：写/提交工具 100% 强制幂等；高风险操作 100% 过审批门；跨租户阻断 100%；误报升级 <2%。
• 成本：每任务净令牌与净延迟不高于 CRUD 基线（原文净省 680 令牌、1.3 秒）；人工干预率 ≤8%。
• 扩大条件：试点指标达标，NTC 契约与六层管线模板化，推广到其余业务域工具。
• 停止条件：任务成功率提升不显著（<10 个百分点）而成本明显上升，或治理管线引入的延迟使交互式场景不可用——回到「CRUD+编排层补偿」方案并复盘。

出处

• 机构：A2A Lab
• 作者：Kai Pan、Rong Hou
• 日期：2026 年 5 月 11 日提交（v1；v2 2026 年 8 月 20 日）
• 原文标题：Agent-First Tool APIs: Rethinking Enterprise Service Interfaces for LLM-Native Execution
• URL：https://arxiv.org/abs/2605.10555
• 许可：CC BY 4.0，允许全文翻译与再发布，须署名

PRIMARY_SOURCE: https://arxiv.org/abs/2605.10555