构建 AI Agent 实战总结：分布式系统思维落地

大约一年前，我从纯后端和分布式系统工作转向在生产环境中构建真正的 AI Agent 系统。在那一年中的某个时刻，我也开始注意到一个奇怪的现象。我身边有几位真正优秀的工程师，他们可以毫不费力地设计出真正的分布式系统，却连一个基本的 AI Agent 都难以实现。原因并不是他们不熟悉底层的系统概念，而是因为大多数教程教的是框架，而不是工程思维。

这个差距就是这个系列存在的原因。

我实际构建的东西

我在工作中做的事情不属于我公开发布的范畴，而且也不应该发布。所以我在业余时间从零开始构建了一个平行版本，施加了比大多数真实团队更严格的约束：真正的零预算，而不是打了折的预算。没有团队，没有生产流量，没有基础设施预算，也没有 Claude Code 或 Codex。整个项目运行在 Antigravity 和 Gemini API 免费套餐上。如果某个方案在这些限制下不工作，我的任务就是理解为什么，而不是投入更多算力直到它工作。

这是一个基于多 Agent、RAG 的知识系统，它从小处起步。解析文档、分块、嵌入、搜索。这在一百个教程里都见过。这套系统不像教程的地方是在几个阶段之后——一旦系统需要在多个专业 Agent 之间路由、在会话之间保持记忆、通过真实的协议服务器暴露工具，并且能够经受住那些只有在你不默认信任模型输出时才会出现的故障模式。

我希望存在的系列

在我开始构建 sentinel-agent 之前，我查找了现有的内容，希望能帮助我在不需要被研究论文或机器学习理论淹没的情况下建立扎实的企业级理解。大多数试图教授这些内容的资料都落在三个桶里。要么是周末 demo 打扮成生产系统，要么是有理论但没有可运行的代码，要么是偶尔真正好的内容但定价像 bootcamp。这些都不能教你真正重要的东西，而那些昂贵的资料和免费的资料有着相同的核心缺陷：它们给你的是一个成品实现，而不是产生这个实现的推理过程。

这种推理在这里比平时更重要，因为地面不断在移动。你这个月依赖的库在明年真正有可能被弃用或重新设计。我在这个项目里已经不止一次目睹过这种情况发生。学习如何连接一个特定的 Agent 框架，教你的是那个框架。它不会教你当它在你脚下发生变化时该怎么做，而在这一行，它会的。

这一直是一个系统问题

剥掉模型和月度框架，一个 AI Agent 系统底下实际坐着的是一个分布式系统。它需要扩展、保持安全、随着需求变化保持可扩展性，并且优雅地降级，而不是在第一次出问题时就崩溃。任何真正花了多年时间构建和运维分布式系统的人，都已经携带了对这些约束的确切直觉。通常缺少的不是思维，而是把那种思维映射到一个恰好在内部放置了一个语言模型而不是数据库的领域。

这也是为什么我认为拥有几年生产经验伤痕的资深工程师往往比人们预期的更快适应这个领域。AI Agent 在概念上并不比以前的东西更高级。在真实约束下进行推理——财务的、基础设施的、复杂度的——它本身就是一项技能，而且它通常是通过亲身经历真实系统而不是阅读它们来建立的。

在这些之前，搜索引擎已经存在了几十年。任何人都可以往搜索框里输入内容。真正的技能从来不在于知道如何搜索，而在于知道搜索什么。这几乎正是随着 ChatGPT 和 Claude 这样的工具出现而改变和没有改变的东西。作为工程师的那些年，我已经教会了我需要解决什么问题——就是我上面提到的同样的几个属性。我真正需要学习的是如何从围绕 LLM 而不是 REST 端点构建的系统中获得这些相同的属性。

这就是这个系列真正是什么。不是关于一个一年后需要重写的框架的教程。是一份将我认为可以信任任何生产系统的相同工程 discipline 应用到这个系统上的记录，并对一路上所有它崩溃的地方保持诚实。有些东西在这里崩溃了，我之前没有预料到。一个并发库悄悄忽略了我确信已经正确设置的速率限制，只有在真实数据量冲击它时才发现。一个硬编码的数字 3，静默地截断了用户的记忆，没有任何错误，这种 bug 只有当你去找应该存在但不存在的东西时才会发现。一个清理例程在一个仍在流式传输的响应下面关闭了网络连接，因为代码中没有任何东西再持有对它的引用了。

这些都不是什么稀奇古怪的。它们是你在任何分布式系统中都会发现的那一类 bug：竞态条件、静默失败、在工作完成前被清理的资源。唯一改变的是它们发生的层次。

这个系列你可以期待什么

这不会是直接从第一步走到最后一个里程碑的直线walkthrough。有些文章会用我希望有人向具有系统背景而不是机器学习背景的工程师解释概念的方式来解释一个概念。其他文章会更接近于事故报告：这里是哪里坏了、我是如何发现的、这里什么是真正修复了的、以及为什么明显的修复方法不会有效。

我写这个不是为了给你一个可以去拷贝的技术栈。一年后流行的东西将与今天在这个仓库里的不同，这没关系，那从来都不是重点。如果你来自真正的工程领域，想构建那种能在框架迁移中存活下来的判断力，而不仅仅是一个可行的 demo，这就是为你写的。

完整的项目，包括代码，位于 GitHub上。链接在下面，我会随着系列进展保持更新。

armanavasthi / sentinel-agent

Production-grade agentic RAG system built from scratch. LangGraph multi-agent orchestration, MCP, enterprise middleware, and RAGAS evaluation, with real production bugs diagnosed and fixed along the way.

Welcome to a comprehensive, hands-on applied AI tutorial and repository. We are building enterprise-grade agentic AI systems, not toy demos. If you've searched for a LangGraph tutorial, a Model Context Protocol (MCP) walkthrough, a multi-agent orchestration example, or a production RAG pipeline in Python, this repo builds all of it, from a single-file RAG script up to a distributed, secured, multi-tenant agent platform.

Built with: LangGraph · ChromaDB · Model Context Protocol (MCP) · Langfuse · RAGAS · Gemini API

Learning Path & Roadmap

Study Guides, Glossaries & Notes

Exercises, Quizzes, and Runbooks

Contributions Welcome

What You Will Build (Projects)

Instead of just reading theory, you build a complete, production-grade knowledge base…