[!info] related notes

• 所属 MOC: Tool Calling Engineering MOC
• 相关: Tool Execution, Tool Result Context

Tool Result Normalization

一句话定义

Tool Result Normalization 是将不同工具的返回值统一为标准格式的过程。LLM 期望收到清晰、结构化的文本，但工具可能返回各种格式。

核心原理

先确定状态，再包装数据

执行层明确传递 success、error 或 unknown 等结果类别，归一化层不能仅凭返回值是否为 None 推断业务成功。None 也可能是一次合法的空结果。

数据尽量保持原有 JSON 类型；不要先把 dict/list 编成字符串，再塞进 JSON 外壳。截断时在字段或记录边界生成摘要，并标记省略；不能把半截 JSON 冒充完整数据。

Python 示例：有限列表的合法 JSON 包装

示例只接受已筛选、已限流的 JSON 值，不实现任意对象转换、脱敏或 token 预算。只截取最外层列表条目，嵌套字符串仍需由上游限制。

import json
from typing import Any


def normalize_success(data: Any, max_items: int = 10) -> str:
    if max_items < 0:
        raise ValueError("max_items must be non-negative")
    truncated = isinstance(data, list) and len(data) > max_items
    payload = data[:max_items] if isinstance(data, list) else data
    return json.dumps(
        {"status": "success", "data": payload, "truncated": truncated},
        ensure_ascii=False,
        allow_nan=False,
    )

调用方已经确认成功后才用此函数；错误或结果未知走独立状态。非 JSON 值、循环引用、NaN 等序列化失败要作为适配错误处理，不冒充工具成功或触发写操作重试。

常见坑

1. 一律 str(result)：丢失数字、布尔值、列表和对象的结构。
2. 把列表上限当总大小上限：一条记录仍可能非常大；完整输出预算见 Tool Result Context。
3. 错误消息直接回显：按 Tool Error Handling筛选稳定错误类别与摘要。

参考资料

• Tool Execution
• Tool Result Context