AI agent 工具结果标准化：把不同 API 返回统一成可决策的结构

AI agent 调用一个工具时，返回什么都还好处理；当它同时接入知识库、任务系统、文件系统、消息系统和外部 API，问题就来了：有的工具返回 status，有的返回 ok，有的把错误写在文本里，有的没有来源和置信度。模型看到这些结果，很难稳定做下一步决策。

工具结果标准化，是让 agent 从“读一堆杂乱返回”变成“根据统一结构决策”。它不要求所有业务工具重写，只要求每个工具在进入模型前经过一层 adapter。

先给结论：每个工具结果都要有统一外壳

建议无论内部工具如何实现，都包装成同一套结构：

{
  "success": true,
  "data": {},
  "confidence": 0.86,
  "source": "knowledge_base",
  "nextAction": "continue",
  "error": null
}

统一外壳不限制业务数据，只统一 agent 判断所需字段。一个可靠的工具结果，不只是告诉 agent “成功了没有”，还要告诉它“这个结果能不能信、来自哪里、下一步该继续还是停下”。

推荐的 ToolResult 协议

可以先用下面这份协议做最小标准：

interface ToolResult<TData = unknown> {
  success: boolean
  data: TData | null
  confidence: number
  source: ToolSource[]
  nextAction: 'continue' | 'retry' | 'ask_user' | 'human_review' | 'stop'
  error: ToolError | null
  meta: {
    toolName: string
    toolVersion: string
    traceId: string
    durationMs: number
    cached: boolean
  }
}

interface ToolError {
  type: 'validation_error' | 'permission_denied' | 'timeout' | 'rate_limited' | 'not_found' | 'state_conflict' | 'unknown'
  message: string
  retryable: boolean
  userMessage?: string
}

interface ToolSource {
  type: 'document' | 'file' | 'api' | 'database' | 'user_input'
  id: string
  label?: string
  url?: string
}

这份结构的关键是把“业务结果”和“决策信号”分开。data 是业务数据，nextAction 是流程控制，meta 是排查线索。

一、success 只能表达工具是否执行成功

success 不等于答案一定正确。它只说明工具调用是否成功完成。比如搜索工具成功返回 3 条结果，但结果相关性低，仍然应该通过 confidence 或 nextAction 表达不确定。

把执行成功和内容可信分开，agent 才不会把“查到了东西”误当成“查到了正确答案”。

例如搜索工具查到 5 条结果但都很弱，应该这样返回：

{
  "success": true,
  "data": { "items": [] },
  "confidence": 0.32,
  "source": [],
  "nextAction": "ask_user",
  "error": null,
  "meta": {
    "toolName": "searchDocs",
    "toolVersion": "2026-05-06",
    "traceId": "tool_001",
    "durationMs": 183,
    "cached": false
  }
}

这不是工具失败，而是“工具成功执行，但结果不足以支持继续”。

二、confidence 要服务下一步判断

置信度不一定要复杂模型计算，也可以来自规则：完全匹配标题给高分，模糊匹配给中分，没有来源给低分。

重要的是让 agent 不要把低质量结果当成强依据。

置信度最好有来源规则，而不是拍脑袋。举个知识库检索的例子：

最终分数不必绝对精确，但要稳定。稳定的置信度规则比一句“模型判断相关”更容易调试。

三、source 和 traceId 让结果可追溯

工具结果必须知道来源。知识库要有文档 id，文件工具要有路径，API 要有请求 id。否则错误出现时无法回看。

{
  "source": {
    "type": "document",
    "id": "pricing-rules-2026",
    "section": "售后修改范围"
  },
  "traceId": "tool_abc_123"
}

来源字段也是生成引用、做日志和评测的重要依据。

source 字段不要只写一个字符串。至少要让人能找回原始依据：

{
  "source": [
    {
      "type": "document",
      "id": "doc_website_brief_rule_v4",
      "label": "官网 brief 填写规则",
      "url": "/docs/brief-rule-v4"
    },
    {
      "type": "user_input",
      "id": "message_784",
      "label": "用户原始需求"
    }
  ]
}

没有来源，agent 输出就很难被审查；没有 traceId，工具失败就很难被复盘。

四、nextAction 比自然语言错误更稳定

工具返回“没有找到相关资料”不够。最好给出下一步建议：继续、重试、补充信息、人工确认、停止。

这样模型可以按状态走，而不是猜错误文案。

系统也可以直接用 nextAction 驱动流程：

function resolveToolNextStep(result: ToolResult) {
  if (result.nextAction === 'continue') return { type: 'MODEL_CONTINUE' }
  if (result.nextAction === 'retry') return { type: 'RETRY_TOOL', retryable: result.error?.retryable }
  if (result.nextAction === 'ask_user') return { type: 'ASK_USER', message: result.error?.userMessage }
  if (result.nextAction === 'human_review') return { type: 'PAUSE_FOR_REVIEW' }
  return { type: 'STOP_RUN' }
}

这就是标准化的收益：模型、工作流引擎、日志系统能围绕同一组字段协作。

五、用 adapter 包住旧工具，而不是强迫所有工具重写

很多项目已经有旧 API。不要一开始就重构所有工具，可以先写适配层：

async function searchDocsTool(input): Promise<ToolResult> {
  const startedAt = Date.now()
  try {
    const response = await legacySearchApi(input.query)
    const items = response.results ?? []
    return {
      success: true,
      data: { items },
      confidence: scoreSearchResults(items),
      source: items.map((item) => ({ type: 'document', id: item.id, label: item.title })),
      nextAction: items.length ? 'continue' : 'ask_user',
      error: null,
      meta: {
        toolName: 'searchDocs',
        toolVersion: '2026-05-06',
        traceId: input.traceId,
        durationMs: Date.now() - startedAt,
        cached: false
      }
    }
  } catch (error) {
    return {
      success: false,
      data: null,
      confidence: 0,
      source: [],
      nextAction: 'retry',
      error: {
        type: 'timeout',
        message: String(error),
        retryable: true,
        userMessage: '资料查询暂时超时，可以稍后重试。'
      },
      meta: {
        toolName: 'searchDocs',
        toolVersion: '2026-05-06',
        traceId: input.traceId,
        durationMs: Date.now() - startedAt,
        cached: false
      }
    }
  }
}

adapter 的价值在于把混乱留在工具内部，把稳定结构交给 agent。

六、失败案例：错误写在 data 里，agent 继续生成错误结果

一个查询工具失败时返回 { data: "timeout" }，没有 success: false。agent 把 timeout 当成资料内容，继续生成答案。修复后，工具统一返回 success: false、error.type: external_timeout、nextAction: retry，流程才变得可控。

七、标准化 Checklist

• 每个工具是否有统一外壳
• success 是否只代表调用成功
• 是否有 confidence 或质量信号
• source 是否能追溯来源
• error 是否结构化
• nextAction 是否明确
• 工具结果是否进入日志和评测
• 旧工具是否经过 adapter 统一格式
• 低置信度结果是否不会被当成强依据
• source 是否足够支撑审查和引用

结语

工具结果标准化不是为了代码整齐，而是为了让 agent 能稳定决策。统一 success、confidence、source、error、meta 和 nextAction 后，工具越多，系统反而越容易维护；否则每加一个工具，都会给模型增加一份新的猜谜题。

延伸阅读：

• AI Agent 工具调用设计
• AI Agent 工具注册表治理
• AI agent 错误分类与恢复策略
• AI Agent 可观测性设计