AI 代理工具结果太大怎么办：Go 用引用句柄隔离上下文与原始响应

AI 代理调用搜索、数据库或文件工具时，最容易被忽略的不是调用失败，而是返回成功却把几万字原始结果直接塞进下一轮上下文。更稳的做法是把原始响应存起来，只把短摘要和引用句柄交给模型；需要细节时，再由应用按句柄取回并核对状态。

工具结果要分成两条路径：原始内容进入存储，摘要与 resultHandle 进入 ContextItem。句柄无效或状态未 ready 时，宁可明确失败，也不要把半截结果当成事实。

工具结果过大，真正挤压的是哪一段上下文

一个工具调用通常同时产生两类信息：模型需要知道“查到了什么”的摘要，以及程序稍后可能要复核的原始响应。把二者混成一个字符串，结果越详细，后续指令、历史对话和工具参数能留下的空间越少。

这里的趋势信号很明确：代理系统开始把上下文当作有限的工作区，把原始工具响应当作可追溯的外部数据。它并不等于删除细节，而是延后细节进入模型的时机。

用 Go 把摘要和原始响应拆成两条数据流

先定义工具结果和上下文条目。示例中的字段都是应用层对象，不依赖某一家模型服务：

type ToolResult struct {
    Name    string
    Raw     []byte
    Summary string
}

type ContextItem struct {
    Summary     string
    ResultHandle string
}

func buildContextItem(r ToolResult) (ContextItem, error) {
    handle, err := storeRawResult(r)
    if err != nil {
        return ContextItem{}, err
    }
    return ContextItem{
        Summary:      r.Summary,
        ResultHandle: handle,
    }, nil
}

关键点在返回顺序：先执行 storeRawResult，拿到 ResultHandle 后才组装 ContextItem。如果存储失败，不能只留下一个看似完整的摘要，否则模型后续引用时会发现句柄不存在。

句柄不是字符串别名，还要有可核对的状态

只保存一个随机字符串仍然不够。工具执行、落盘和异步索引之间可能有短暂间隔，回取方需要知道句柄当前能不能读：

type ResultState string

const (
    pending ResultState = "pending"
    ready   ResultState = "ready"
    failed  ResultState = "failed"
)

type StoredResult struct {
    Handle string
    State  ResultState
    Raw    []byte
}

func loadForFollowUp(s StoredResult) ([]byte, error) {
    if s.State != ready {
        return nil, fmt.Errorf("result %s is %s", s.Handle, s.State)
    }
    return s.Raw, nil
}

状态判断要放在回取入口，而不是交给模型猜。pending 表示仍在准备，failed 表示原始结果不可用；只有 ready 才能把内容送进后续提示。错误信息可以记录句柄和状态，但不要把敏感原文直接写进日志。

哪些角色会从这种隔离方式中受益

模型上下文的编排层最先受益：它只负责组织摘要、用户问题和少量引用，不再承担原始响应的长期保存。存储层则可以按句柄设置过期时间、访问权限和审计字段。

做评测的人也更容易复现问题。一次回答引用了哪个 resultHandle、当时处于什么状态、回取了多少字节，都能在应用日志中对齐。这里的收益是可追踪性，不是保证模型答案一定正确。

落地时要防住三类反效果

• 摘要丢失关键条件。摘要必须保留过滤条件、时间范围和结果数量，否则模型会拿着句柄却不知道原始数据的适用边界。
• 句柄无限存活。给原始结果设置过期策略，过期后返回明确的不可用状态，不要悄悄换成另一份相似数据。
• 回取权限过宽。句柄应绑定会话、租户或任务身份；能猜到句柄不应等于能读取原始响应。

还要留意大小阈值。小结果不一定值得单独存储，但判断标准应来自上下文预算、数据敏感级别和回取成本，而不是固定套用一个“超过多少字节就分离”的数字。

一套紧凑的采用路径

1. 先统计工具结果的原始字节数、摘要字节数和实际进入上下文的长度。
2. 为原始响应增加存储接口，返回唯一的 resultHandle 和初始状态。
3. 让上下文只接收 Summary 与 ResultHandle，并在回取处强制检查 ready。
4. 补齐过期、权限、失败重试和审计字段，再用一组大结果与空结果做回归。

如果业务始终只需要摘要，句柄可以只保留短期审计用途；如果用户经常追问原始证据，则应把回取动作做成明确的工具调用，避免应用在后台悄悄扩大上下文。

常见问题

把原始结果存起来会不会让系统更慢？

会增加一次写入或读取，但可以避免每轮都携带完整结果。应结合回取频率、存储延迟和上下文成本测量，而不是只比较单次工具调用耗时。

resultHandle 能直接放进用户可见回答吗？

通常不应直接暴露。它更适合作为应用内部引用，用户需要证据时由权限校验后的工具返回可展示内容。

pending 状态能不能先让模型继续推理？

可以继续处理不依赖原始结果的部分，但不能把 pending 当作已读取。需要证据的步骤应等待 ready 或明确返回未就绪。

什么时候不值得做结果分离？

结果很短、不会跨轮次复用且不含敏感数据时，直接放入上下文更简单。是否分离应由实际长度、复用率和权限要求共同决定。

总结

AI 代理的工具调用正在从“返回一段文本”转向“返回可管理的证据引用”。Go 代码里的核心变化只有两步：用 storeRawResult 把原始响应落到应用控制的存储，再让 ContextItem 只携带摘要和 resultHandle。配合 pending、ready、failed 状态，上下文压力、权限边界和失败处理才真正分开。