🏠 项目地址： 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 的蜕变。每一阶段都包含可运行的代码示例。
目标：拨开 SDK 的迷雾，直视大模型调用的本质。
- 协议本质：掌握
chat/completions接口的最小化请求和响应结构 - 流式输出解析：深入了解 SSE（Server-Sent Events）协议，实现"打字机"效果
- 工程实践：对比 Raw HTTP 和 OpenAI Go SDK 的使用方式
- LLM 原理（可选）：Transformer、训练过程、Token 机制、生成原理
目标：让 LLM 从"只会聊天"升级为"能动手做事"的 Agent。
- Function Calling 协议：如何向模型声明工具、如何解析工具调用
- Agent Loop：工具调用 → 反馈 → 再推理的闭环流程
- ReAct/Tool-Loop 原理：Reason + Act 的思维-行动交替模式
- 本地工具封装：读取文件、写入文件、编辑文件、执行 shell 命令
- Chat Template（可选）：从 API 到模型输入的转换机制
目标：可视化展示推理与工具调用过程，兼容推理模型。
- 推理字段兼容：解析流式响应中的
reasoning_content字段 - TUI 可视化：使用 Bubble Tea 实现轻量的可视化输出
- 流式输出与 UI 协程：通过 channel 将增量消息传递给 UI
- 推理模型 vs 非推理模型（可选）：Chat Template 差异、Token 消耗特点
目标：接入 MCP（Model Context Protocol）工具生态，扩展 Agent 能力。
- MCP 原理：Client/Server/Tool 三类角色，解决"模型 × 工具"爆炸组合问题
- 协议交互流程（可选）：JSON-RPC 2.0、初始化、工具发现、工具调用
- 工具管理：本地工具与 MCP 工具的无缝共存
- 命名空间化：避免工具冲突的命名策略
目标：实现完整的上下文管理策略，在有限窗口内高效运行。
- 上下文窗口问题：理解多轮对话后的窗口限制、成本增加、性能下降
- 截断策略（Truncation）：安全删除旧消息，保留最近关键对话
- 卸载策略（Offloading）：将长消息存储到外部，保留恢复提示
- 摘要策略（Summarization）：使用 LLM 对历史对话进行压缩
- 策略模式设计：可扩展、可组合的策略接口
- 策略事件系统：在 TUI 中实时展示策略执行状态
- Token 计数：使用 tiktoken-go 实时计算上下文 token 数量
目标：让 Agent 具备长期记忆能力，跨越会话保持上下文连贯性。
- 两层记忆架构：Global Memory（跨会话）、Workspace Memory（项目级）
- Memory 接口设计：可插拔的记忆抽象接口
- LLM 驱动的记忆更新：使用 LLM 自动提取和更新记忆内容
- 持久化存储机制：将 Global 和 Workspace 记忆持久化到文件系统
- 记忆事件系统：在 TUI 中实时展示记忆更新状态
- System Prompt 集成：将记忆注入到 System Prompt 中供 LLM 使用
目标：让 Agent 能够自主决策检索时机、查询内容和数量，实现真正的 Agentic RAG。
- Agentic RAG 概念：理解 Agent 如何自主决定何时检索、检索什么、检索多少
- 代码索引（Embedding）：使用 Embedding 模型将代码片段向量化
- 向量存储：使用 pgvector 存储和检索向量，支持增量更新和去重
- 文档切片策略：LineChunker 和 ParagraphChunker 两种切分方式
- 召回（Recall）：基于向量相似度的语义检索
- 重排序（Rerank）：使用 Rerank 模型对召回结果重新排序
- 搜索工具实现：Semantic Search Tool 的完整实现
目标：为 Agent 设计安全防护，防止 AI 执行危险操作。
- Docker 沙盒隔离：在容器中运行 bash 命令，自动检测 Docker 并优雅降级
- 人工确认（Human-in-the-loop）：在执行危险命令前请求用户确认
- 确认状态管理：Allow/Reject/Always Allow 三种确认选项
- Context 取消机制：用户按 ESC 提前终止 Agent Loop
目标：让 Agent 学会在不同场景下使用工具的最佳实践。
- 技能即提示：技能是描述性文字，指导模型如何使用工具
- 渐进式加载：元数据注入 system prompt，完整内容按需加载
- Markdown 技能文件：使用 YAML front matter + Markdown 正文定义技能
- 技能管理器：自动发现和加载技能元数据
- load_skill 工具：LLM 按需加载完整技能内容
目标：将 CLI 核心逻辑剥离，搬运到服务端运行。
- HTTP API 封装：设计 RESTful API 接口
- Server-Sent Events：像 ChatGPT 一样向前端推送流式响应
- 并发管理：处理多用户同时请求
- 中间件设计：认证、限流、日志等
目标：突破单机运行的局限，管理多用户的对话 Session。
- Session 管理：设计会话存储与恢复机制
- 历史上下文持久化：将对话历史存储到数据库
- 多租户隔离：确保不同用户的数据隔离
- 状态同步：处理分布式环境下的状态一致性问题
目标：摒弃"靠肉眼看效果"的黑盒测试，构建自动化评测流水线。
- Mock LLM 接口：测试核心调度逻辑，避免真实 API 调用
- 评测数据集：构建标准测试用例
- 自动化评测指标：响应时间、Token 消耗、准确率等
- Prompt 优化量化：对比不同 Prompt 版本的实际收益
目标：讲清楚把 Agent 推向生产时需要补齐的可观测性与工程化能力
- 分布式追踪（Trace）：监控 Agent 复杂的推理和工具调用链路
- 结构化日志（Log）：记录关键事件，便于问题排查
- 性能指标（Metrics）：监控请求量、延迟、错误率等
- 告警机制：及时发现"幻觉"和性能瓶颈
以上标注 🚧 的章节为规划中内容，正在持续更新中。敬请期待！
- 安装 Go: 确保本地已安装 Go 1.24 或更高版本。
- 获取 API Key: 你需要一个 LLM 供应商的 API Key（如 OpenAI, 或国内的 DeepSeek/GLM）。
- 配置文件:
cp .env.example .env # 编辑 .env 文件，填入你的 API_KEY
- 语法简单: 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/ # 🚧 第十一章：服务端状态管理（规划中）
├── ch12/ # 🚧 第十二章：Agent 评测与自动化测试（规划中）
├── ch13/ # 🚧 第十三章：生产环境保障（规划中）
├── 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
# 第八章：完整 Agent（含 Docker 沙盒和工具确认）
go run ./ch08/main
# 第九章：技能系统
go run ./ch09/main第七章是独立的索引和工具实现，可参考 ch07/README.md 中的使用示例。
- 循序渐进：按章节顺序学习，每章建立在前一章的基础上
- 动手实践：运行每个章节的示例代码，观察实际效果
- 可选内容：标记"（可选阅读/可选阅读）"的小节是进阶内容，初学可跳过
- 原理理解：理解 Chat Template、Token 机制、MCP 协议等底层原理有助于排查问题
我们非常欢迎社区贡献！如果你有更好的 Agent 设计模式或有趣的工具实现，请随时提交 PR。
本项目采用 Apache License 2.0 协议。