本文永久链接 – https://tonybai.com/2025/07/30/six-principles-production-ai-agents

大家好，我是Tony Bai。

随着 AI Agent 技术的兴起，许多开发者都投入到构建智能体的浪潮中，但很快就会发现，让 Agent 稳定、可靠地工作远非想象中容易。它们时而产生幻觉，时而偏离轨道，时而做出一些令人费解的“愚蠢”行为。最近，来自 app.build 的 Arseni Kravchenko 分享了他们在构建生产级 AI Agent 过程中总结出的六大核心工程原则。这些原则摒弃了虚无缥缈的“提示词黑魔法”，回归到坚实的软件工程基础。对于正在或计划使用 Go 构建 AI Agent 的开发者来说，这是一份宝贵的实践指南。

原则一：投资你的系统提示 (System Prompt)

许多人对“提示词工程”持怀疑态度，认为它充满了“我奶奶快不行了，请帮帮我”之类的奇技淫巧。然而，作者指出，现代 LLM 真正需要的是直接、详细、清晰且无矛盾的上下文，而非情感操控。

对于开发者而言，你要做的就是不要耍小聪明，要把系统提示当作给 Agent 的API 文档来写。

当你为 Agent 提供一个通过 os/exec 调用的工具时，不要只告诉它工具的名字。在系统提示中清晰地说明：

• 工具的完整命令是什么。
• 每个参数的含义、类型和格式。
• 预期的输出格式以及如何解析它。
• 前置条件和错误情况。

一个详尽的系统提示是 Agent 可靠行为的基石。

原则二：拆分上下文 (Split the Context)

“上下文工程”是比“提示词工程”更重要的概念。巨大的、单一的上下文不仅成本高、延迟大，还会导致模型出现“注意力衰减”，忽略掉关键信息。

作者建议大家：默认只提供最少必要知识，并通过工具让 Agent 在需要时主动获取更多上下文。

与其在初始提示中塞入整个项目的源代码，不如：

• 提供文件列表：在提示中只给出项目的文件树结构。
• 提供 read_file 工具：让 Agent 在需要时，通过调用这个工具来读取特定文件的内容。
• 上下文压缩：在 Agent 的反馈循环中，主动使用工具（甚至另一个 LLM）来压缩和总结日志、工具输出等动态信息，避免上下文无限膨胀。

如上图所示，将一个庞大的任务分解为多个具有专注上下文的、可编排的子任务，是构建高效 Agent 的关键。

原则三：精心设计你的工具 (Design Tools Carefully)

工具是 AI Agent 的核心。设计给 Agent 用的工具，比设计给人用的 API 更具挑战性，因为 LLM 不会“读心术”，它们会毫不留情地滥用你留下的任何漏洞。

作者建议：把你的 Agent 当成一个聪明但容易分心的初级开发者，为它设计 API：

• 保持粒度一致：工具（函数）应该有相似的抽象层次。不要混用一个 read_byte 和一个 deploy_to_kubernetes。
• 限制数量和参数：一个典型的工程 Agent 通常只有不到 10 个核心工具，每个工具只有 1-3 个严格类型的参数。
• 追求幂等性：尽可能让工具是幂等的，这可以极大地简化 Agent 的状态管理和错误恢复逻辑。
• 清晰、无歧义、无冗余：确保没有两个工具的功能是重叠的，这会让 LLM 感到困惑。

原则四：设计一个反馈循环 (Design a Feedback Loop)

一个没有验证和反馈的 Agent 是不可靠的。优秀的 Agent 系统总是将 LLM 的创造力与传统软件的严格性结合起来，形成一个“演员-评论家”（Actor-Critic）模型：让 LLM Actor 自由创造，让严格的 Critic 程序来验证。

对于开发者来说，这是一个天然的优势领域！

• Actor (LLM)：负责生成代码、配置文件或执行计划。
• Critic：负责执行一系列自动化验证：
  • 代码能否编译通过？
  • 代码能否通过测试？
  • 代码是否符合静态检查规范？
  • 领域特定不变量：例如，如果 Agent 修改了订单系统，是否依然满足“订单总价等于所有商品价格之和”这个业务规则？

这个反馈循环不仅能过滤掉错误的输出，更是 Agent 学习和改进的基础。

原则五：用 LLM 驱动错误分析

当 Agent 失败时，手动排查海量的日志是不现实的。我们可以构建一个“meta Agent”来解决这个问题，即让另一个 LLM 来分析失败 Agent 的日志，找出问题的根源。

流程：

1. 建立一个基线版本的 Agent。
2. 部署多个实例并收集它们的执行轨迹和日志。
3. 将失败的日志喂给一个具有更大上下文窗口（如 Gemini 1.5 Pro）的 LLM进行分析。
4. 根据 LLM 的分析洞察，改进基线 Agent 的系统提示、工具或上下文管理。

这个元循环能高效地发现我们自己可能忽略的系统性问题。

原则六：令人沮丧的行为是系统问题的信号

当 Agent 做出一些“愚蠢”的行为，比如忽略你的明确指令，或者用一种奇怪的方式绕过问题时，我们的第一反应通常是“这个模型真笨”。

但作者建议：先调试你自己的系统，再怪罪模型。

作者分享了一个亲身经历：他明确要求 Agent 使用一个集成工具来获取数据，但 Agent 却固执地使用模拟的随机数据。在愤怒地检查日志后，他发现自己忘了给 Agent 配置正确的 API 密钥。Agent 尝试调用工具，连续失败，最后只能选择一个它能走的通的、但却是错误的路径。

因此，当你的 Agent 行为异常时，请检查一下：

• 工具是否缺失？ 它是否需要一个 write_file 的能力而你没有提供？
• 提示是否模糊？ 你是否清晰地解释了工具的用法和边界？
• 上下文是否充分？ 它是否因为缺少必要信息（比如一个 API 密钥或文件权限）而无法执行任务？

小结

构建有效的 AI Agent，关键不在于寻找一个能解决所有问题的“银弹”提示或高级框架。它回归到了系统设计和严谨的软件工程。

作为开发者，我们应该聚焦于：

• 清晰的指令（通过系统提示）
• 精简的上下文管理（通过工具和压缩）
• 健壮的工具接口（简单、幂等、无歧义）
• 自动化的验证循环（编译、测试、静态检查）

当你被 Agent 的行为所困扰时，记住，问题很可能出在缺失的工具、模糊的提示或不足的上下文，而不是模型本身的局限性。将错误分析视为开发过程中的一等公民，我们的目标不是构建一个从不犯错的完美 Agent，而是构建一个可靠的、可恢复的、能够优雅地失败并被我们迭代改进的Agent。

资料链接：https://www.app.build/blog/six-principles-production-ai-agents

你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？

• 想写出更地道、更健壮的Go代码，却总在细节上踩坑？
• 渴望提升软件设计能力，驾驭复杂Go项目却缺乏章法？
• 想打造生产级的Go服务，却在工程化实践中屡屡受挫？

继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！

我的全新极客时间专栏 《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。

目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！ 现在就加入，让你的Go技能再上一个新台阶！

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。

本文永久链接 – https://tonybai.com/2025/07/29/slog-multihandler

大家好，我是Tony Bai。

自 log/slog 在 Go 1.21 中引入以来，一个常见的需求始终困扰着开发者：如何将日志同时发送到多个目的地，并为每个目的地设置不同的日志级别？尽管社区已涌现出 samber/slog-multi 等优秀的三方库，但关于“标准库是否应原生支持”的讨论从未停止。最近，一项编号为#65954 的提案，建议在 log/slog 中加入 MultiHandler，获得了 Go 官方的 [likely accept] 评级。本文将带您回顾该提案从被质疑到被接受的全过程，深入探讨其背后的设计权衡。

背景：一个普遍而又棘手的需求

在实际生产环境中，日志往往需要被送往多个地方：
* 控制台（stdout）：用于开发和调试，通常需要 DEBUG 级别的详细信息。
* 本地文件：用于归档和追溯，可能需要 INFO 级别以上的日志。
* 远端日志服务（如 ELK, Loki,VictoriaLogs等）：用于聚合和告警，可能只关心 ERROR 级别的日志。

然而，log/slog 的核心设计是一个 Logger 对应一个 Handler。虽然 io.MultiWriter 可以将相同格式、相同级别的日志写入多个 io.Writer，但它无法满足不同目的地、不同级别这一核心需求。

这导致许多开发者不得不自行实现 slog.Handler 来“扇出”（fan-out）日志，或者引入第三方依赖。正如提案者 lxl-renren 和多位评论者所指出的，这是一个非常普遍的场景。

从“不需要”到“值得拥有”的转变

提案初期，Go 团队成员 jba (Jonathan Amsterdam) 和 seankhliao 对其必要性提出了质疑，核心论点是：
1. 社区已有解决方案：像 samber/slog-multi 这样的库已经很好地解决了问题。
2. 实现相对简单：开发者可以自己编写一个 multiHandler 来实现。
3. 避免增加标准库维护负担：Go 团队对向标准库添加新 API 持非常谨慎的态度。

然而，随着讨论的深入，社区的声音和更多场景的出现，逐渐改变了 Go 团队的看法。

• OpenTelemetry 集成：有开发者指出，当应用需要同时将日志发送到 stdout 和 OpenTelemetry Collector 时，MultiHandler 几乎成了“刚需”。
• 依赖问题：还有开发者认为，仅仅为了一个功能而引入一个带有额外依赖（有时甚至是不必要的测试依赖）的第三方库，违背了 Go 崇尚简约的哲学。
• 实现的微妙之处：甚至有开发者反驳了“实现简单”的观点，认为 slog.Handler 的正确实现存在许多“坑”（footguns），普通开发者未必能一次写对，尤其是在处理 WithAttrs 和 WithGroup 的状态传递时。
• 先例与惯例：社区成员指出，标准库中已经存在 io.MultiReader 和 io.MultiWriter 这样的先例，为 slog 提供一个 MultiHandler 符合语言的内在一致性。

Filippo Valsorda 的“三复制代码”

在讨论中，Go 安全负责人、核心开发者 Filippo Valsorda (@FiloSottile) 的评论成为了一个重要的转折点。他分享了自己在三个不同项目中都复制粘贴了的 multiHandler 实现，并直言：“代码量太少，不值得为此增加一个依赖。”

这段代码堪称 slog.Handler 实现的典范，简洁而完整：

type multiHandler []slog.Handler

func MultiHandler(handlers ...slog.Handler) slog.Handler {
    return multiHandler(handlers)
}

func (h multiHandler) Enabled(ctx context.Context, l slog.Level) bool {
    for i := range h {
        if h[i].Enabled(ctx, l) {
            return true // 只要有一个 handler 需要，就启用
        }
    }
    return false
}

func (h multiHandler) Handle(ctx context.Context, r slog.Record) error {
    var errs []error
    for i := range h {
        // 在 Handle 内部再次检查 Enabled，确保日志只发给需要的 handler
        if h[i].Enabled(ctx, r.Level) {
            // 克隆 Record 以防 handler 修改，影响后续 handler
            if err := h[i].Handle(ctx, r.Clone()); err != nil {
                errs = append(errs, err)
            }
        }
    }
    return errors.Join(errs...) // 合并所有 handler 的错误
}

func (h multiHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
    handlers := make([]slog.Handler, 0, len(h))
    for i := range h {
        handlers = append(handlers, h[i].WithAttrs(attrs))
    }
    return multiHandler(handlers)
}

func (h multiHandler) WithGroup(name string) slog.Handler {
    handlers := make([]slog.Handler, 0, len(h))
    for i := range h {
        handlers = append(handlers, h[i].WithGroup(name))
    }
    return multiHandler(handlers)
}

Filippo 的分享有力地证明了：这确实是一个普遍存在、实现固定、但自己写又有点麻烦的“最佳实践”代码片段。将其标准化，可以避免社区无数次地“重复造轮子”。

最终提案：一个简单、顺序、可预测的 MultiHandler

最终，在充分吸取了社区的意见后，jba 转变了看法，并亲自提出了最终的 API 提案，该提案目前已被标记为 [likely accept]：

// MultiHandler returns a handler that invokes all the given Handlers.
// Its Enable method reports whether any of the handlers' Enabled methods return true.
// Its Handle, WithAttr and WithGroup methods call the corresponding method on each of the enabled handlers.
func MultiHandler(handlers ...Handler) Handler

在讨论中，团队还明确了几个重要的行为特性：

• 顺序执行：MultiHandler 将依次、同步地调用每一个 handler，类似于 io.MultiWriter。
• 错误处理：与 io.MultiWriter 在遇到第一个错误时就停止不同，MultiHandler 将会继续执行所有的 handler，并最终通过 errors.Join 返回所有遇到的错误。这对于日志场景更为合理，因为一个 handler（如远程服务）的失败不应阻止日志被写入另一个更可靠的 handler（如 stderr）。
• 不处理并发：标准库版本将不会内置复杂的异步、批处理或超时逻辑。这些高级功能被认为设计自由度太大，更适合由社区的第三方库来实现和探索。

小结

slog.MultiHandler 的提案演进过程，是 Go 标准库发展哲学的一次完美体现。它始于一个看似“社区可以自己解决”的问题，但通过社区的广泛反馈和真实场景的展示，最终证明了将其标准化的价值：为最普遍的需求提供一个简单、可靠、零依赖的解决方案，同时为更复杂的需求留出空间，让社区生态去创新。

对于广大的 Go 开发者而言，这无疑是个好消息。在不久的将来，我们或许就能告别为多目标日志而编写的那些重复代码或引入的微小依赖，享受到标准库带来的便利和统一。这正是 Go 语言持续改进、不断提升开发者体验的魅力所在。

资料链接：https://github.com/golang/go/issues/65954

你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？

• 想写出更地道、更健壮的Go代码，却总在细节上踩坑？
• 渴望提升软件设计能力，驾驭复杂Go项目却缺乏章法？
• 想打造生产级的Go服务，却在工程化实践中屡屡受挫？

继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！

我的全新极客时间专栏 《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。

目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！ 现在就加入，让你的Go技能再上一个新台阶！

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。