[!info] related notes

• 所属 MOC: Context Engineering MOC
• 相关: Tool Runtime, Context Compression

Tool Result Context

一句话定义

Tool Result Context 是工具执行结果注入到 LLM 上下文中的格式和策略。工具返回的结果可能是 JSON、文本、表格、错误信息，需要格式化后再注入。

核心原理

注入格式

# 工具结果作为 tool message 注入
messages.append({
    "role": "tool",
    "tool_call_id": "call_xxx",
    "content": json.dumps(result, ensure_ascii=False, indent=2)
})

结果压缩

def format_tool_result(result: any, max_tokens: int = 1000) -> str:
    """格式化工具结果"""
    if isinstance(result, dict):
        text = json.dumps(result, ensure_ascii=False, indent=2)
    elif isinstance(result, list):
        # 列表只保留前 N 项
        if len(result) > 10:
            text = json.dumps(result[:10], ensure_ascii=False, indent=2)
            text += f"\n... (共 {len(result)} 项，已截断)"
        else:
            text = json.dumps(result, ensure_ascii=False, indent=2)
    else:
        text = str(result)

    # 截断
    if len(text) > max_tokens * 4:  # 粗略估算
        text = text[:max_tokens * 4] + "\n... (结果已截断)"

    return text

错误结果处理

def format_tool_error(error: Exception) -> str:
    """格式化工具错误"""
    return f"工具执行失败: {type(error).__name__}: {str(error)}"

常见坑

1. 结果太大: 工具返回了 10KB 的 JSON，撑爆上下文
2. 不做格式化: 原始 JSON 不易读
3. 不处理错误: 工具失败了但没有错误信息
4. 不截断: 数据库查询返回了 1000 条记录全部注入

参考资料

• Tool Runtime
• Context Compression