给所有想转Agent开发或者Agent进阶同学的一些建议

// 传统开发：确定性逻辑
func CheckOutdoorActivity(city string) string {
    weather := GetWeatherAPI(city)  // 一定返回 {Temp, Weather, Wind}

    switch weather.Weather {
    case"晴":
        if weather.Temp >= 15 && weather.Temp <= 35 {
            return"适合户外运动"
        }
        return"温度不适宜"
    case"阴":
        return"可以做户外运动，但要注意天气变化"
    default:
        return"不适合户外运动"
    }
}

// 输入"北京"，每次运行结果完全一致
// 出了问题，断点调试一路跟下去就行

// Agent开发：概率性逻辑
// 使用 Go 版 LangChain: github.com/tmc/langchaingo
import (
    "github.com/tmc/langchaingo/agents"
    "github.com/tmc/langchaingo/tools"
    "github.com/tmc/langchaingo/llms/openai"
)

// 定义工具：查询天气
func getWeatherTool() tools.Tool {
    return tools.GenericTool{
        Name:        "get_weather",
        Description: "查询指定城市的天气，返回温度、天气状况、风力",
        Run: func(ctx context.Context, input string) (string, error) {
            return weatherAPI(input), nil
        },
    }
}

llm, _ := openai.New(openai.WithModel("gpt-4o"))

toolList := []tools.Tool{getWeatherTool()}

systemPrompt := `你是一个户外运动顾问。根据用户提供的城市天气，判断是否适合户外运动。
判断规则：
- 晴天、温度15-35度：适合
- 阴天：可以，但需注意
- 雨天/大风/高温/低温：不适合
请给出判断并解释原因。`

agent := agents.NewOpenAIFunctionsAgent(llm, toolList)
executor := agents.NewExecutor(agent)

result, _ := executor.Call(ctx, map[string]any{
    "input": "北京天气怎么样？",
})

// 同样输入"北京"，可能出现：
// 第1次："北京今天晴天，25度，非常适合户外运动！" ✅
// 第2次："北京今天晴天，25度，非常适合户外运动。推荐去公园跑步。" ✅ 还给了建议
// 第3次："北京今天天气不错，应该可以户外运动吧？" ⚠️ 不确定的语气
// 第4次：`{"suitable": true}` ❌ 输出格式不符合预期！

// 定义期望的输出结构体
type ActivityAdvice struct {
    Suitable   bool   `json:"suitable"`
    Reason     string`json:"reason"`
    Suggestion string`json:"suggestion"`
}

// 在Prompt中要求LLM输出JSON格式，然后用 json.Unmarshal 解析
systemPrompt := `你是一个户外运动顾问。请严格按照以下JSON格式输出：
{"suitable": true/false, "reason": "判断理由", "suggestion": "具体建议"}
不要输出任何其他内容。`

// 调用后解析
var advice ActivityAdvice
if err := json.Unmarshal([]byte(llmOutput), &advice); err != nil {
    // 输出格式不对，触发重试或降级
    log.Warn("输出格式解析失败", "output", llmOutput, "error", err)
}

// 跑100次，统计成功率
successCount := 0
for i := 0; i < 100; i++ {
    output, err := executor.Call(ctx, map[string]any{
        "input": "北京天气怎么样？",
    })
    if err != nil {
        continue
    }
    var advice ActivityAdvice
    if json.Unmarshal([]byte(output), &advice) == nil {
        successCount++
    }
}
fmt.Printf("成功率: %.2f%%\n", float64(successCount)/100*100)

var advice ActivityAdvice
if err := json.Unmarshal([]byte(agentOutput), &advice); err != nil {
    // 降级方案：用更简单的方式重新请求，或返回兜底
    advice = ActivityAdvice{
        Suitable:   false,
        Reason:     "解析失败",
        Suggestion: "请重试",
    }
}

langchaingo（Go Agent框架）
├── llms（模型交互层）
│   ├── openai —— 调用OpenAI/GPT
│   ├── ollama —— 本地模型推理
│   └── anthropic —— 调用Claude
├── chains（链式调用）
│   ├── LLMChain —— 基础链
│   ├── ConversationalRetrievalQA —— 对话检索链
│   └── MapReduce —— 长文本总结
├── agents（智能体）
│   ├── tools —— 工具定义
│   ├── OpenAIFunctionsAgent —— 函数调用Agent
│   └── Executor —— 执行循环（ReAct模式）
├── vectorstores（向量数据库）
│   ├── chroma —— ChromaDB
│   ├── milvus —— Milvus
│   └── pgvector —— PostgreSQL向量扩展
└── documentloaders（文档加载）
    ├── PDF/Text/Markdown加载器
    └── 文档切片器

// ===== 步骤1：定义工具 =====
// 工具是Agent的手，让LLM能执行实际操作
import"github.com/tmc/langchaingo/tools"

func searchKnowledgeBaseTool() tools.Tool {
    return tools.GenericTool{
        Name:        "search_knowledge_base",
        Description: "搜索公司内部知识库，查询产品文档、技术规范等信息",
        Run: func(ctx context.Context, query string) (string, error) {
            // 实际项目中这里接向量数据库
            return fmt.Sprintf("关于'%s'的搜索结果：...", query), nil
        },
    }
}

func createTicketTool() tools.Tool {
    return tools.GenericTool{
        Name:        "create_ticket",
        Description: "创建工单。输入格式：{\"title\": \"工单标题\", \"priority\": \"高/中/低\"}",
        Run: func(ctx context.Context, input string) (string, error) {
            var req struct {
                Title    string`json:"title"`
                Priority string`json:"priority"`
            }
            json.Unmarshal([]byte(input), &req)
            return fmt.Sprintf("已创建工单：%s，优先级：%s", req.Title, req.Priority), nil
        },
    }
}

// ===== 步骤2：创建Agent =====
// Executor是Agent的大脑：接收任务 → 思考 → 调工具 → 观察结果 → 继续思考 → 输出答案
toolList := []tools.Tool{searchKnowledgeBaseTool(), createTicketTool()}

llm, _ := openai.New(
    openai.WithModel("gpt-4o"),
    openai.WithToken("sk-xxx"),
)

agent := agents.NewOpenAIFunctionsAgent(llm, toolList)
executor := agents.NewExecutor(
    agent,
    agents.WithMaxIterations(5),    // 防止无限循环
    agents.WithCallbacksHandler(callbacks.LogHandler{}), // 打印思考过程，调试必备
)

// ===== 步骤3：运行并观察 =====
result, _ := executor.Call(ctx, map[string]any{
    "input": "客户反馈登录页面打不开，帮我查一下有没有相关文档，有的话创建工单",
})
// callbacks.LogHandler 会输出：
// > Thought: 用户想查登录问题的文档，我需要先搜索知识库
// > Action: search_knowledge_base
// > Action Input: "登录页面打不开"
// > Observation: 找到1篇相关文档：《登录模块故障排查指南》
// > Thought: 有相关文档，现在创建工单
// > Action: create_ticket
// > Action Input: {"title": "客户反馈登录页面打不开", "priority": "高"}
// > Observation: 已创建工单...
// > Final Answer: 已为您查到相关文档并创建了高优先级工单。

// 生产级Agent封装——可靠性设计
type ProductionAgent struct {
    maxRetries      int
    fallbackResp    string
    maxInputTokens  int
}

func NewProductionAgent() *ProductionAgent {
    return &ProductionAgent{
        maxRetries:     3,
        fallbackResp:   "抱歉，系统繁忙，请稍后重试。",
        maxInputTokens: 100000,
    }
}

// InvokeWithRetry 带指数退避重试的调用
func (pa *ProductionAgent) InvokeWithRetry(ctx context.Context, executor *agents.Executor, input map[string]any) (string, error) {
    var lastErr error

    for attempt := 0; attempt < pa.maxRetries; attempt++ {
        // 1. 输入校验
        inputStr, ok := input["input"].(string)
        if !ok || len(inputStr) == 0 {
            return pa.fallbackResp, fmt.Errorf("输入不合法")
        }

        // 2. Token预算检查
        if estimatedTokens := estimateTokens(inputStr); estimatedTokens > pa.maxInputTokens {
            input["input"] = truncateText(inputStr, pa.maxInputTokens)
        }

        // 3. 调用Agent
        result, err := executor.Call(ctx, input)
        if err != nil {
            lastErr = err
            log.Warn("Agent调用失败，准备重试", "attempt", attempt+1, "error", err)
            // 指数退避：1s → 2s → 4s
            time.Sleep(time.Duration(1<<attempt) * time.Second)
            continue
        }

        // 4. 输出校验
        if !pa.validateOutput(result) {
            lastErr = fmt.Errorf("输出格式异常: %s", result)
            time.Sleep(time.Duration(1<<attempt) * time.Second)
            continue
        }

        return result, nil
    }

    return"", fmt.Errorf("重试%d次后仍失败: %w", pa.maxRetries, lastErr)
}

// SafeInvoke 最终安全调用——带兜底
func (pa *ProductionAgent) SafeInvoke(ctx context.Context, executor *agents.Executor, input map[string]any) string {
    result, err := pa.InvokeWithRetry(ctx, executor, input)
    if err != nil {
        log.Error("Agent调用彻底失败，使用兜底回复", "error", err)
        return pa.fallbackResp
    }
    return result
}

import time
import json
from functools import wraps

def trace_agent_call(func):
    """Agent调用追踪装饰器"""
    @wraps(func)
    def wrapper(*args, **kwargs):
        trace_id = f"trace_{int(time.time() * 1000)}"
        start = time.time()
        
        log_entry = {
            "trace_id": trace_id,
            "timestamp": start,
            "input": str(kwargs.get("input", ""))[:200],  # 截断存储
        }
        
        try:
            result = func(*args, **kwargs)
            log_entry.update({
                "duration_ms": (time.time() - start) * 1000,
                "status": "success",
                "output_length": len(str(result)),
            })
            return result
        except Exception as e:
            log_entry.update({
                "duration_ms": (time.time() - start) * 1000,
                "status": "error",
                "error": str(e),
            })
            raise
        finally:
            # 写入日志（生产环境用结构化日志如JSON Lines）
            print(json.dumps(log_entry, ensure_ascii=False))
    
    return wrapper

// 成本感知的Agent
type ModelCost struct {
    Input  float64// 每百万token美元
    Output float64
}

var modelCostMap = map[string]ModelCost{
    "gpt-4o":           {Input: 2.5, Output: 10.0},
    "gpt-4o-mini":      {Input: 0.15, Output: 0.6},
    "claude-3.5-sonnet": {Input: 3.0, Output: 15.0},
}

// RouteByComplexity 按任务复杂度选模型——简单任务用小模型，省钱
func RouteByComplexity(task string) string {
    simpleKeywords := []string{"总结", "分类", "提取"}
    complexKeywords := []string{"分析", "推理", "代码"}

    for _, kw := range simpleKeywords {
        if strings.Contains(task, kw) {
            return"gpt-4o-mini"// 简单任务，便宜约17倍
        }
    }
    for _, kw := range complexKeywords {
        if strings.Contains(task, kw) {
            return"gpt-4o"// 复杂任务，用大模型
        }
    }
    return"gpt-4o-mini"// 默认用小模型
}

// EstimateCost 估算单次调用成本
func EstimateCost(model string, inputTokens, outputTokens int) float64 {
    cost, ok := modelCostMap[model]
    if !ok {
        return0
    }
    returnfloat64(inputTokens)/1_000_000*cost.Input + float64(outputTokens)/1_000_000*cost.Output
}

// 实际效果示例：
// 一句话总结任务：gpt-4o ≈ $0.001，gpt-4o-mini ≈ $0.00006
// 日处理10万次总结：gpt-4o ≈ $100/天，gpt-4o-mini ≈ $6/天
// 差距是17倍！

// 评估数据集示例
type EvalCase struct {
    Input            string
    ExpectedTools    []string// 期望调用的工具
    ExpectedKeywords []string// 期望包含的关键词
    Difficulty       string
}

var evalDataset = []EvalCase{
    {
        Input:            "帮我查一下北京的天气，适合跑步吗？",
        ExpectedTools:    []string{"get_weather"},
        ExpectedKeywords: []string{"温度", "适合", "不适合"},
        Difficulty:       "easy",
    },
    {
        Input:            "客户说登录不了，帮我查文档、创工单、发通知给运维",
        ExpectedTools:    []string{"search_kb", "create_ticket", "send_notification"},
        ExpectedKeywords: []string{"工单", "通知", "文档"},
        Difficulty:       "hard",
    },
    // ... 至少准备50-100条
}

type EvalResult struct {
    Total         int
    ToolAccuracy  float64
    KeywordRecall float64
}

func EvaluateAgent(executor *agents.Executor, dataset []EvalCase) EvalResult {
    var r EvalResult
    r.Total = len(dataset)

    for _, c := range dataset {
        result, _ := executor.Call(context.Background(), map[string]any{"input": c.Input})

        // 工具调用准确率
        calledTools := extractCalledTools(result)
        if stringSliceEqual(calledTools, c.ExpectedTools) {
            r.ToolAccuracy++
        }

        // 关键词召回率
        outputLower := strings.ToLower(result)
        matched := 0
        for _, kw := range c.ExpectedKeywords {
            if strings.Contains(outputLower, kw) {
                matched++
            }
        }
        r.KeywordRecall += float64(matched) / float64(len(c.ExpectedKeywords))
    }

    r.ToolAccuracy = r.ToolAccuracy / float64(r.Total) * 100
    r.KeywordRecall = r.KeywordRecall / float64(r.Total) * 100
    return r
}

// Multi-Agent 编排：技术文章写作团队
type ArticleTask struct {
    Topic     string
    Research  string// 研究资料
    Draft     string// 初稿
    FinalDraft string// 终稿
}

// Agent 1：研究员 —— 负责搜集资料
func researcherAgent(ctx context.Context, topic string, resultCh chan<- ArticleTask) {
    // 调用LLM做研究
    research := callLLM(ctx, fmt.Sprintf("请搜集关于'%s'的最新资料、论文和最佳实践", topic))
    resultCh <- ArticleTask{Topic: topic, Research: research}
}

// Agent 2：撰稿人 —— 根据研究资料写初稿
func writerAgent(ctx context.Context, task ArticleTask, resultCh chan<- ArticleTask) {
    prompt := fmt.Sprintf("根据以下研究资料，撰写关于'%s'的深度技术文章：\n%s", task.Topic, task.Research)
    task.Draft = callLLM(ctx, prompt)
    resultCh <- task
}

// Agent 3：审校 —— 质量把关
func reviewerAgent(ctx context.Context, task ArticleTask, resultCh chan<- ArticleTask) {
    prompt := fmt.Sprintf("审查以下文章的技术准确性、逻辑清晰度和可读性，直接输出修改后的版本：\n%s", task.Draft)
    task.FinalDraft = callLLM(ctx, prompt)
    resultCh <- task
}

// 编排器：串联执行
func orchestrateArticleWriting(ctx context.Context, topic string) *ArticleTask {
    ch1 := make(chan ArticleTask, 1)
    ch2 := make(chan ArticleTask, 1)
    ch3 := make(chan ArticleTask, 1)

    go researcherAgent(ctx, topic, ch1)
    task := <-ch1

    go writerAgent(ctx, task, ch2)
    task = <-ch2

    go reviewerAgent(ctx, task, ch3)
    task = <-ch3

    return &task
}

第1-2周：入门打基础
├── Go基础（不熟的先补）
├── 吴恩达《Building Systems with the ChatGPT API》(免费，Python但概念通用)
├── langchaingo官方示例（GitHub: tmc/langchaingo，三刷法）
├── Eino（字节跳动开源，Go原生AI框架）
└── 实战项目：做一个RAG问答机器人

第3-4周：进阶核心能力
├── Prompt Engineering Guide（免费开源）
├── 向量数据库（ChromaDB上手最快，Milvus适合生产，Go都有SDK）
├── 工作流编排（Go用goroutine+channel / Eino框架）
└── 实战项目：做一个能调工具的智能客服

第5-8周：高阶突破
├── Multi-Agent架构设计
├── Agent工程化实践（可靠性/可观测性/成本/评估）
├── Anthropic《Building effective agents》必读
├── Go+Python混合架构（Go做业务层，Python做Agent推理层）
└── 实战项目：做一个Multi-Agent协作系统（如自动化代码审查）