[!info] related notes

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

Tool Result Normalization

一句话定义

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

核心原理

归一化流程

工具返回值 (dict / str / list / Exception)
    │
    ▼
类型判断
    │
    ├─ dict → JSON 序列化
    ├─ list → 截断 + JSON 序列化
    ├─ str → 直接使用
    ├─ Exception → 错误信息格式化
    └─ None → "无结果"
    │
    ▼
长度控制 (截断到 max_tokens)
    │
    ▼
标准格式:
{
  "status": "success" | "error",
  "data": ...,
  "error": "...",
  "truncated": true | false
}

Python 实现

class ToolResultNormalizer:
    def __init__(self, max_tokens: int = 1000):
        self.max_tokens = max_tokens

    def normalize(self, result: any, error: str = None) -> str:
        if error:
            return json.dumps({
                "status": "error",
                "error": error,
            }, ensure_ascii=False)

        if result is None:
            return json.dumps({"status": "success", "data": None})

        # 序列化
        if isinstance(result, (dict, list)):
            text = json.dumps(result, ensure_ascii=False, indent=2)
        else:
            text = str(result)

        # 截断
        max_chars = self.max_tokens * 4
        truncated = len(text) > max_chars
        if truncated:
            text = text[:max_chars] + "\n... (truncated)"

        return json.dumps({
            "status": "success",
            "data": text,
            "truncated": truncated,
        }, ensure_ascii=False)

常见坑

1. 不做归一化: 有的返回 dict 有的返回 str，LLM 处理不一致
2. 不做截断: 大结果撑爆上下文
3. 错误信息太技术化: LLM 看不懂

参考资料

• Tool Execution
• Tool Result Context