BabyAgent - 后端工程师的 AI Agent 教学项目 (Go 语言版)
🏠 项目地址： https://github.com/baby-llm/baby-agent
🚀 从后端视角出发，用 Go 语言手写一遍 Agent 框架的关键原理。
本项目专为没有 LLM 背景但具备基础 Golang 经验的后端工程师设计。我们将跳过复杂的数学推导，优先从工程实现理解核心概念：你会看到每一步为什么这么设计、替代方案是什么、以及它们在真实系统里会遇到哪些坑。
重要说明（请先读）
- 本项目是教学仓库：目标是用可运行的代码把 Agent、Tool Calling、Agent Loop、MCP、Memory、RAG 等机制讲清楚。
- 本项目不是“开箱即用的生产框架”，也不建议直接用于生产环境的二次开发。
- 如果你希望落地到真实业务：这里更适合作为原理参考 + 原型验证的起点，你需要根据自己的场景补齐工程化能力与安全边界。
🏗 核心技术栈
- Language: Go 1.24+
- LLM Concepts: Chat Completions API, SSE 流式传输, Function Calling, ReAct Agent Loop
- Advanced AI: 上下文工程, Memory 系统, Agentic RAG, 技能系统（Skills）
- System Design: MCP 协议, Guardrails 安全防护, Web 服务化
- Engineering: LLM 评测, 可观测性（Trace/Metrics/Log）
🗺 学习路径图 (按知识循序渐进)
我们将按照"从基础调用到复杂 Agent"的顺序逐步深入，带你完成从零到复杂 Agent 的蜕变。每一阶段都包含可运行的代码示例。
第一章：初识 LLM（Raw HTTP 与 OpenAI SDK）
目标：拨开 SDK 的迷雾，直视大模型调用的本质。
- 协议本质：掌握
chat/completions 接口的最小化请求和响应结构
- 流式输出解析：深入了解 SSE（Server-Sent Events）协议，实现"打字机"效果
- 工程实践：对比 Raw HTTP 和 OpenAI Go SDK 的使用方式
- LLM 原理（可选）：Transformer、训练过程、Token 机制、生成原理
第二章：赋予 AI "手脚"（Tool Calling 和 Agent）
目标：让 LLM 从"只会聊天"升级为"能动手做事"的 Agent。
- Function Calling 协议：如何向模型声明工具、如何解析工具调用
- Agent Loop：工具调用 → 反馈 → 再推理的闭环流程
- ReAct/Tool-Loop 原理：Reason + Act 的思维-行动交替模式
- 本地工具封装：读取文件、写入文件、编辑文件、执行 shell 命令
- Chat Template（可选）：从 API 到模型输入的转换机制
第三章：让 Agent "更能看见"（Reasoning 展示、TUI）
目标：可视化展示推理与工具调用过程，兼容推理模型。
- 推理字段兼容：解析流式响应中的
reasoning_content 字段
- TUI 可视化：使用 Bubble Tea 实现轻量的可视化输出
- 流式输出与 UI 协程：通过 channel 将增量消息传递给 UI
- 推理模型 vs 非推理模型（可选）：Chat Template 差异、Token 消耗特点
第四章：让 Agent 接入 MCP 生态
目标：接入 MCP（Model Context Protocol）工具生态，扩展 Agent 能力。
- MCP 原理：Client/Server/Tool 三类角色，解决"模型 × 工具"爆炸组合问题
- 协议交互流程（可选）：JSON-RPC 2.0、初始化、工具发现、工具调用
- 工具管理：本地工具与 MCP 工具的无缝共存
- 命名空间化：避免工具冲突的命名策略
第五章：上下文工程（Context Engineering）
目标：实现完整的上下文管理策略，在有限窗口内高效运行。
- 上下文窗口问题：理解多轮对话后的窗口限制、成本增加、性能下降
- 截断策略（Truncation）：安全删除旧消息，保留最近关键对话
- 卸载策略（Offloading）：将长消息存储到外部，保留恢复提示
- 摘要策略（Summarization）：使用 LLM 对历史对话进行压缩
- 策略模式设计：可扩展、可组合的策略接口
- 策略事件系统：在 TUI 中实时展示策略执行状态
- Token 计数：使用 tiktoken-go 实时计算上下文 token 数量
第六章：记忆机制（Memory System）
目标：让 Agent 具备长期记忆能力，跨越会话保持上下文连贯性。
- 两层记忆架构：Global Memory（跨会话）、Workspace Memory（项目级）
- Memory 接口设计：可插拔的记忆抽象接口
- LLM 驱动的记忆更新：使用 LLM 自动提取和更新记忆内容
- 持久化存储机制：将 Global 和 Workspace 记忆持久化到文件系统
- 记忆事件系统：在 TUI 中实时展示记忆更新状态
- System Prompt 集成：将记忆注入到 System Prompt 中供 LLM 使用
第七章：Agentic RAG（检索增强生成）
目标：让 Agent 能够自主决策检索时机、查询内容和数量，实现真正的 Agentic RAG。
- Agentic RAG 概念：理解 Agent 如何自主决定何时检索、检索什么、检索多少
- 代码索引（Embedding）：使用 Embedding 模型将代码片段向量化
- 向量存储：使用 pgvector 存储和检索向量，支持增量更新和去重
- 文档切片策略：LineChunker 和 ParagraphChunker 两种切分方式
- 召回（Recall）：基于向量相似度的语义检索
- 重排序（Rerank）：使用 Rerank 模型对召回结果重新排序
- 搜索工具实现：Semantic Search Tool 的完整实现
第八章：沙盒与安全防御（Guardrails）
目标：为 Agent 设计安全防护，防止 AI 执行危险操作。
- Docker 沙盒隔离：在容器中运行 bash 命令，自动检测 Docker 并优雅降级
- 人工确认（Human-in-the-loop）：在执行危险命令前请求用户确认
- 确认状态管理：Allow/Reject/Always Allow 三种确认选项
- Context 取消机制：用户按 ESC 提前终止 Agent Loop
第九章：Agent 技能插件（Skills）
目标：让 Agent 学会在不同场景下使用工具的最佳实践。
- 技能即提示：技能是描述性文字，指导模型如何使用工具
- 渐进式加载：元数据注入 system prompt，完整内容按需加载
- Markdown 技能文件：使用 YAML front matter + Markdown 正文定义技能
- 技能管理器：自动发现和加载技能元数据
- load_skill 工具：LLM 按需加载完整技能内容
第十章：Web 服务化与 SSE 流式传输
目标：将 CLI Agent 剥离 TUI，封装成 HTTP 服务，让浏览器也能像 ChatGPT 一样与 Agent 流式对话。
- Agent 与传输层解耦：Agent 内部用
StreamEvent channel 输出事件，不感知任何 HTTP 概念；HTTP 层负责把事件转成 SSE 格式推给客户端
- SSE 流式传输：Server-Sent Events 服务端实现，Goroutine + Channel 的并发架构
- 会话与消息持久化：SQLite 存储 Conversation / ChatMessage，
Rounds 字段序列化完整 LLM 消息
- 树形对话历史：每条消息记录
parent_message_id，buildHistory 沿祖先链追溯重建 LLM context
第十一章：Agent 可观测性（Observability）🚧
目标：让 Agent 的每次执行都透明、可追溯，从「能用」走向「可运维」。
- Trace/Span 模型：一次 Query = 一条 Trace，一次 Tool Call = 一个 Span，构建完整的执行调用树
- Agent 专属指标：First Token Time（首 Token 延迟）、Tokens Per Minute（生成速度）、Token Usage（消耗统计）
- Span 属性设计：为 LLM 调用、工具执行等操作设计有意义的可查询属性
- 可观测性后端：OpenTelemetry + Jaeger/Tempo + Prometheus + Grafana 完整链路
第十二章：Agent 评测与自动化测试（LLM Eval）🚧
目标：摒弃"靠肉眼看效果"的黑盒测试，构建自动化评测流水线。
- Mock LLM 接口：测试核心调度逻辑，避免真实 API 调用
- 评测数据集：构建标准测试用例
- 自动化评测指标：响应时间、Token 消耗、准确率等
- Prompt 优化量化：对比不同 Prompt 版本的实际收益
🚧 进行中与规划中
以上标注 🚧 的章节为规划中内容，正在持续更新中。敬请期待！
🛠 开发环境准备
- 安装 Go: 确保本地已安装 Go 1.24 或更高版本。
- 获取 API Key: 你需要一个 LLM 供应商的 API Key（如 OpenAI, 或国内的 DeepSeek/GLM）。
- 配置文件:
bash
cp .env.example .env
# 编辑 .env 文件，填入你的 API_KEY
🎯 为什么选择 Go 开发 Agent？
- 语法简单: Go 简单的语法和直观的代码流程，能清晰描述这个教学项目的原理与实现。
- 类型安全: 在处理复杂的 Tool 定义和 JSON 解析时，Go 的强类型能减少 80% 的运行时错误。
- 并发优势: Agent 往往需要并行调用多个工具或检索源，Go 的 Goroutine 是天然的利器。
- 部署简单: 无需复杂的 Python/Node.js 依赖环境，单个二进制文件即可上线。
📂 项目结构说明
baby-agent/
├── ch01/ # ✅ 第一章：初识 LLM（Raw HTTP 与 SDK）
├── ch02/ # ✅ 第二章：Function Calling 与 Agent Loop
├── ch03/ # ✅ 第三章：推理展示与 TUI 可视化
├── ch04/ # ✅ 第四章：MCP 生态接入
├── ch05/ # ✅ 第五章：上下文工程
├── ch06/ # ✅ 第六章：记忆机制
├── ch07/ # ✅ 第七章：Agentic RAG
├── ch08/ # ✅ 第八章：沙盒与安全防御
├── ch09/ # ✅ 第九章：Agent 技能插件
├── ch10/ # ✅ 第十章：Web 服务化与 SSE 流式传输
├── ch11/ # 🚧 第十一章：Agent 可观测性（规划中）
├── ch12/ # 🚧 第十二章：Agent 评测与自动化测试（规划中）
├── shared/ # 共享代码（配置、MCP 等）
├── .env # 环境变量配置
└── README.md # 本文件
🚀 快速开始
各章节均可独立运行，按需学习：
# 第一章：体验流式输出
go run ./ch01/main --stream -q "用 Go 语言写一个 Hello World"
# 第二章：工具调用示例
go run ./ch02/main -q "请读取 README.md 并总结项目目标"
# 第三章：TUI 可视化
go run ./ch03/main
# 第四章：MCP 工具调用
go run ./ch04/main
# 第五章：上下文管理
go run ./ch05/main
# 第六章：记忆系统
go run ./ch06/main
# 第八章：安全防御
go run ./ch08/main
# 第九章：技能插件
go run ./ch09/main
# 第十章：Web 服务（监听 :8080）
go run ./ch10/main
第七章是独立的索引和工具实现，可参考 ch07/README.md 中的使用示例。
📚 学习建议
- 循序渐进：按章节顺序学习，每章建立在前一章的基础上
- 动手实践：运行每个章节的示例代码，观察实际效果
- 可选内容：标记"（可选阅读/可选阅读）"的小节是进阶内容，初学可跳过
- 原理理解：理解 Chat Template、Token 机制、MCP 协议等底层原理有助于排查问题
🤝 参与贡献
我们非常欢迎社区贡献！如果你有更好的 Agent 设计模式或有趣的工具实现，请随时提交 PR。
📄 开源协议
本项目采用 Apache License 2.0 协议。