实战一：从 0 写一个客服 Agent

// 查订单工具
type getOrderArgs struct {
    OrderID string `json:"order_id" jsonschema:"description=订单号"`
}

getOrder := agents.NewFunctionTool("get_order", "查询订单状态和详情", func(ctx, tc, args getOrderArgs) (string, error) {
    order := db.QueryOrder(args.OrderID)
    if order == nil {
        return "订单不存在", nil
    }
    // 安全检查：只能查当前用户的订单
    if order.UserID != tc.RunContext.UserID {
        return "无权查看此订单", nil  // 不报错，但返回无权
    }
    return fmt.Sprintf("订单 %s：状态=%s，金额=%.2f，商品=%s",
        order.ID, order.Status, order.Amount, order.Items), nil
})

// 退款工具，需要审批
type refundArgs struct {
    OrderID string  `json:"order_id"`
    Reason  string  `json:"reason"`
}

refundTool := agents.NewFunctionTool("process_refund", "处理退款（需要审批）", func(ctx, tc, args refundArgs) (string, error) {
    refundID := refundService.Process(args.OrderID, args.Reason)
    return fmt.Sprintf("退款已发起，退款单号 %s", refundID), nil
})
refundTool.NeedsApproval = true  // 第 12 章，退款要审批

// 人工客服 Agent（被 handoff 的目标）
humanAgent := &agents.Agent{
    Name: "人工客服",
    Instructions: agents.StaticInstructions("你是人工客服坐席。Agent 转交来的问题由你处理。"),
    // 人工 Agent 没有工具，它把问题记下来，转给真人坐席
}

// 客服 Agent
supportAgent := &agents.Agent{
    Name: "客服助手",
    Instructions: agents.StaticInstructions(`你是电商客服助手。
- 先理解用户问题
- 查订单用 get_order
- 退款用 process_refund（会触发审批）
- 处理不了的问题，转给人工客服
- 绝不泄露其他用户的信息`),
    Model: "openai/gpt-4o",
    Tools: []agents.Tool{getOrder, refundTool},
    Handoffs: []agents.Handoff{
        agents.HandoffTo(humanAgent),  // 第 15 章，转人工
    },
}

// 输入护栏，防 prompt injection
supportAgent.InputGuardrails = []agents.InputGuardrail{{
    Name: "no_injection",
    Run: func(ctx, rc, agent, input) (agents.GuardrailFunctionOutput, error) {
        text := extractText(input)
        // 检测常见的 injection 模式
        patterns := []string{"忽略之前的指令", "ignore previous instructions", "你现在是"}
        for _, p := range patterns {
            if strings.Contains(strings.ToLower(text), p) {
                return agents.GuardrailFunctionOutput{
                    TripwireTriggered: true,
                    OutputInfo: "疑似 prompt injection",
                }, nil
            }
        }
        return agents.GuardrailFunctionOutput{}, nil
    },
}}

// 输出护栏，防 PII 泄露
supportAgent.OutputGuardrails = []agents.OutputGuardrail{{
    Name: "no_pii",
    Run: func(ctx, rc, agent, output) (agents.GuardrailFunctionOutput, error) {
        text := fmt.Sprint(output)
        if matchPII(text) {  // 检测身份证、手机号等
            return agents.GuardrailFunctionOutput{
                TripwireTriggered: true,
                OutputInfo: "输出含 PII",
            }, nil
        }
        return agents.GuardrailFunctionOutput{}, nil
    },
}}

// 每个用户一个 Session
userSession := memory.NewFileSession("sessions", fmt.Sprintf("user-%s", userID))

func handleCustomerMessage(userID, message string) string {
    // 带 Session + Provider + Tracer
    sess := memory.NewFileSession("sessions", fmt.Sprintf("user-%s", userID))

    // RunContext 带 UserID（工具里要用）
    rc := agents.NewRunContext(ctx)
    rc.UserID = userID

    result, err := agents.Run(ctx, supportAgent, message, agents.RunOptions{
        Session:       sess,
        ModelProvider: router,
        RunContext:    rc,
        Hooks:         agents.CompositeRunHooks(loggingHooks, metricsHooks),
    })

    if err != nil {
        // 检查是不是 HITL 中断
        if result != nil && result.State != nil {
            // 退款需要审批，通知审批系统
            notifyApprovalSystem(result.State)
            return "您的退款请求已提交，等待审批中"
        }
        return "抱歉，出错了：" + err.Error()
    }

    return result.FinalOutputString()
}

用户："我上周买的手机还没到"
  → Agent 推理：需要查订单
  → 调 get_order(order_id="?")  ← 需要订单号
  → Agent："请问您的订单号是多少？"

用户："12345"
  → 调 get_order(order_id="12345")
  → 工具校验：订单 12345 属于当前用户 ✅
  → 返回："订单 12345：状态=已发货，预计明天到达"
  → Agent："您的订单已发货，预计明天到达"

用户："太慢了，我要退款"
  → Agent 推理：用户要退款
  → 调 process_refund(order_id="12345", reason="物流太慢")
  → HITL！退款需要审批 → 暂停
  → 返回："退款请求已提交审批"

（审批人员同意）

  → ResumeRun → 执行退款
  → Agent："您的退款已处理，退款单号 RF-xxx，3-5 个工作日到账"