一次工具调用的完整生命周期

模型说"我要调 get_weather(北京)"
  → 这是个合法工具吗？（查表）
  → 这个工具需要审批吗？（HITL 检查）
  → 参数合法吗？（输入 guardrail）
  → 真正执行工具
  → 输出合法吗？（输出 guardrail）
  → 把结果包装成对话历史的一项
  → 加入下一轮循环的输入

// agents/run_step.go:103（骨架）
func processModelResponse(agent, tools, handoffs, resp, toolNotFound) (*processedResponse, error) {
    // 建两张查找表：handoff 和 function
    handoffMap := map[string]Handoff{...}
    functionMap := map[string]*FunctionTool{...}

    for _, item := range resp.Output {
        switch item.Type {
        case "message":       // 普通消息
            newItems = append(newItems, &MessageOutputItem{...})
        case "reasoning":     // 推理（o1 系列）
            newItems = append(newItems, &ReasoningItem{...})
        case "function_call": // 工具/handoff 调用
            // 先查 handoffMap（handoff 优先）
            if h, ok := handoffMap[item.Name]; ok {
                handoffs = append(handoffs, toolRunHandoff{h, call})
            } else if t, ok := functionMap[item.Name]; ok {
                functions = append(functions, toolRunFunction{t, call})
            } else {
                // 模型调用了一个不存在的工具！
                unknownTools = append(unknownTools, call)
            }
        }
    }
    return &processedResponse{NewItems, Functions, Handoffs, ToolsUsed, UnknownTools}
}

// agents/run_step.go:52
const (
    ToolNotFoundError ToolNotFoundBehavior = iota         // 默认：中断 run
    ToolNotFoundReturnToModel                              // 把错误喂回模型让它自纠
)

// agents/run_step.go:165（骨架，顺序至关重要）
func (r *runner) executeToolsAndSideEffects(...) (*singleStepResult, error) {
    // 1. 收集模型产出的 items
    step.NewStepItems = append(step.NewStepItems, processed.NewItems...)

    // 2. HITL 分区：哪些要立即执行，哪些要等审批
    toRun, interruptions, rejected := partitionByApproval(processed.Functions, ...)

    // 3. 有任何待审批的 → 立即暂停（不执行任何东西）
    if len(interruptions) > 0 {
        return stepInterruption 结果
    }

    // 4. 并发执行函数工具
    toolOutputs := runFunctionTools(toRun, ...)

    // 5. 处理模型调用不存在工具的情况
    for _, call := range processed.UnknownTools {
        合成错误输出，回喂模型
    }

    // 6. Handoff 优先（如果有 handoff，走 handoff 分支）
    if len(processed.Handoffs) > 0 {
        return executeHandoff(...)
    }

    // 7. 没有工具可调？→ 判定最终输出
    if !processed.hasToolsToRun() {
        return stepFinalOutput, 取最后一条 message
    }

    // 8. 否则继续下一轮
    return stepRunAgain
}

// agents/run_step.go:179
toRun, interruptions, rejected := partitionByApproval(processed.Functions, ...)
if len(interruptions) > 0 {
    return stepInterruption  // 一个要审批，全部暂停
}

// agents/run_step.go:197
toolOutputs := runFunctionTools(toRun, ...)

// agents/run_step.go:277（骨架）
func runFunctionTools(tools []toolRunFunction, ...) []toolOutput {
    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(MaxToolConcurrency)  // 限流

    for _, tr := range tools {
        tr := tr  // 经典 Go 闭包陷阱
        g.Go(func() error {
            // 完整的工具调用流水线（见下面）
            return nil
        })
    }
    g.Wait()
}

1. 构造 ToolContext（含 CallID、Arguments）
2. callToolStart hook（第 19 章）
3. 输入 guardrail（第 14 章）
4. 开 function span（第 25 章）
5. invokeTool（真正调用，支持超时）
6. 错误处理（FailureErrorFunction 回喂 vs 中断）
7. 输出 guardrail
8. callToolEnd hook
9. 把输出包装成 function_call_output item

// agents/tool.go:73-78
// FailureErrorFunction 非 nil → 把错误信息喂回模型，让模型自愈
// FailureErrorFunction 为 nil → 错误中断整个 run

// agents/tool.go:84
func DefaultToolErrorFunction(_, _, err error) string {
    return "An error occurred while running the tool. Please try again. Error: " + err.Error()
}

tool := agents.NewFunctionTool("critical_op", "...", criticalOp)
tool.FailureErrorFunction = nil  // 出错就中断，不回喂

// agents/run_items.go:204（简化）
func newFunctionCallOutputItem(callID string, output any) RunItem {
    // output 是 any，需要序列化
    // 字符串直接用，结构化输出走 content list，其余 stringify
    return &FunctionCallOutputItem{
        CallID: callID,
        Output: stringifyToolOutput(output),
    }
}

// agents/run_step.go:213
if len(processed.Handoffs) > 0 {
    return executeHandoff(...)
}

模型返回 function_call
  → 分类：handoff？function？不存在？（processModelResponse）
  → HITL 分区：要审批的立即暂停（partitionByApproval）
  → 并发执行：errgroup + MaxToolConcurrency（runFunctionTools）
  → 每个工具的九步流水线：ctx → hook → 输入护栏 → span → 执行 → 错误处理 → 输出护栏 → hook → 包装
  → 错误回喂或中断（FailureErrorFunction）
  → 包装成 function_call_output item（newFunctionCallOutputItem）
  → 加入历史，进入下一轮循环