1. 为什么想不开要用 C++ 写 AI Agent
先把结论摆在最前面：用 C++ 写 AI Agent，不是因为 C++ 时髦，恰恰相反，是因为它在某些场景下“没得选”。我最初动这个念头，是在做一个需要本地推理、低延迟响应、还要嵌到现有桌面端程序里的智能体项目。当时用 Python 原型跑通了，逻辑没问题，但一上真实环境就露馅——启动慢、内存飘、和宿主程序的 C++ 接口来回折腾，最后打包分发更是一团乱麻。折腾了两周之后，我决定把核心部分用 C++ 重写，这才有了后面这一整套架构和阅读路线的思考。
这篇文章要聊的，就是“从 0 到 1 用 C++ 搭一个 AI Agent”这件事的整体架构和阅读路线。它不是一篇 C++ 语法教程，也不是某个框架的 API 手册，而是一个从业者在真正动手之前，对“该学什么、该按什么顺序学、每一块为什么这么设计”的完整梳理。如果你是有一定 C++ 基础、想往 AI Agent 方向走的开发者，或者你已经在用 Python 做智能体、但被性能或部署问题卡住，那这篇内容应该能帮你少走不少弯路。核心关键词就四个：C++、AI Agent、整体架构、阅读路线，我会围绕它们一层层展开。
需要提前说明的是，AI Agent 这个概念本身很宽。有人说的 Agent 是“能调用工具的大模型循环”，有人说的是一整套带记忆、规划、执行、反思的智能系统。我这里采用的是偏工程化的定义：一个能接收输入、维护状态、调用外部能力（工具/模型/接口）、并根据结果决定下一步动作的循环体。用 C++ 实现它，难点不在“智能”，而在“工程”。
2. 整体架构拆解：一个 C++ AI Agent 到底由哪些部分组成
2.1 先想清楚 Agent 的核心循环长什么样
不管用什么语言写，Agent 的骨架其实就一个循环：感知 → 决策 → 行动 → 观察 → 再决策。用伪代码表示大概是这样：
while (!done) { auto context = memory.recall(input); auto plan = planner.decide(context); auto result = executor.run(plan); memory.store(plan, result); if (result.isFinal()) done = true; }看起来简单，但每一行背后都是一堆工程决策。memory用什么数据结构？planner是本地规则还是调用模型？executor怎么保证工具调用的安全和超时？这些才是 C++ 实现里真正花时间的地方。我一开始低估了这块，以为把 Python 逻辑翻译过来就行，结果发现 Python 里一句json.loads背后是一整套动态类型和异常处理，C++ 里得自己设计解析、校验、错误传播，工作量完全不是一个量级。
所以整体架构的第一步，不是写代码，而是把这个循环里每个环节的数据流和生命周期画清楚。谁拥有数据、谁负责释放、状态存在哪、跨线程怎么同步，这些在 C++ 里必须提前想明白，否则后期全是内存问题。
2.2 分层设计：把“智能”和“工程”分开
我最终采用的是一种分层结构，从上到下大致是四层：
| 层级 | 职责 | 典型内容 |
|---|---|---|
| 交互层 | 接收用户输入、输出结果 | CLI、HTTP 接口、嵌入宿主程序的回调 |
| 编排层 | Agent 主循环、状态机、任务调度 | 循环控制、超时、重试、并发 |
| 能力层 | 模型调用、工具执行、记忆读写 | 推理接口、工具注册表、向量存储 |
| 基础层 | 网络、序列化、日志、线程 | HTTP 客户端、JSON 库、线程池 |
这么分的好处是，智能相关的逻辑集中在编排层和能力层，工程相关的脏活累活在基础层。我见过不少人一上来就把所有东西塞进一个类里，结果模型换一个、工具加一个，整个文件就崩了。分层之后，换模型只动能力层，换交互方式只动交互层，互不影响。
这里有个经验：基础层一定要用成熟库，别自己造轮子。JSON 用 nlohmann/json，HTTP 用 cpp-httplib 或 libcurl，日志用 spdlog，这些库稳定、文档全、社区活跃。我早期手写过一个 JSON 解析器，结果遇到转义字符和嵌套就各种 bug，白白浪费了三天。基础层省下来的时间，全部投到编排层和能力层的设计上，才是划算的。
2.3 为什么不用现成的 C++ Agent 框架
这个问题我被问过很多次。市面上确实有一些 C++ 的推理框架和工具库，但“AI Agent 框架”这个层面的成熟方案，相比 Python 生态还是少很多。Python 那边 LangChain、LlamaIndex 之类的工具已经把工具调用、记忆、链式编排封装得很完整，C++ 这边更多是零散的组件。
我的判断是：如果你的 Agent 逻辑不复杂，用现成组件拼装完全够用；但如果你要做深度定制，比如特殊的调度策略、极致的延迟优化、和现有 C++ 系统的深度集成，那自己搭一套反而更可控。我选的是后者，因为我的场景要求 Agent 能直接调用宿主程序里的 C++ 对象，这种集成度用现成框架很难做到。
不过自己搭不代表什么都自己写。我的原则是：通用能力用库，Agent 特有的编排逻辑自己写。这样既保证了基础质量，又保留了灵活性。
3. 阅读路线：从 C++ 基础到 Agent 实战的学习顺序
3.1 别急着看 Agent，先把 C++ 的“现代部分”补齐
很多人一上来就想学 Agent 架构，结果卡在 C++ 语法上。我的建议是，动手之前先确认你对下面这些内容是否熟悉：
- 智能指针：
std::unique_ptr、std::shared_ptr、std::weak_ptr的使用场景和区别。Agent 里到处是对象的所有权转移，这块不熟会写出大量内存泄漏。 - 移动语义：
std::move、右值引用、完美转发。数据在层与层之间传递时，避免不必要的拷贝是性能关键。 - Lambda 与
std::function：工具注册、回调、异步任务都靠它。 - 并发基础：
std::thread、std::mutex、std::condition_variable、std::atomic。Agent 的循环和工具执行往往在不同线程。 - STL 容器与算法：
vector、unordered_map、string的常见操作，以及std::sort、std::find_if这类算法。
如果你对这些还比较陌生，我建议先花一到两周过一遍。不需要学到专家级别，但要能熟练使用。我当初就是移动语义没吃透，写出来的代码到处是拷贝，性能测试时才发现瓶颈全在数据传递上。
3.2 然后补 AI 与 Agent 的概念基础
C++ 基础过关之后，下一步是理解 Agent 本身。这块不需要你成为算法专家，但几个核心概念必须清楚：
- 大模型推理的基本流程：输入怎么变成 token，模型怎么输出，为什么有上下文长度限制。
- 工具调用（Function Calling）：模型如何决定调用哪个工具、参数怎么传、结果怎么回填。
- 记忆机制：短期记忆（对话历史）和长期记忆（向量检索）的区别与实现思路。
- 规划与反思：ReAct、Plan-and-Execute 这类模式的思路，不需要背名字，但要理解“先想再做”和“边做边想”的差异。
这些概念在 Python 生态里有大量资料，看 Python 的教程完全没问题，重点是理解思想，而不是记 API。我当初就是先看了一堆 Python 的 Agent 教程，把逻辑理清楚，再想怎么用 C++ 表达。
3.3 最后才是架构与实战
概念清楚之后，再回头看架构，就会顺畅很多。这时候你要思考的是：
- 我的 Agent 需要哪些能力？模型调用、工具、记忆，哪些是必须的？
- 这些能力怎么用 C++ 的抽象表达？接口怎么设计？
- 数据怎么流动？状态存在哪？并发怎么处理？
- 怎么测试？怎么调试？怎么保证不出内存问题？
这个顺序很重要。先基础、再概念、后架构，每一步都建立在前一步之上。我见过有人跳过基础直接看架构，结果看懂了图但写不出代码；也见过有人只学语法不学概念，写出来的东西根本不像 Agent。两者都不可取。
4. 核心模块的 C++ 实现要点与踩坑记录
4.1 模型调用模块：网络与序列化的双重考验
模型调用是 Agent 和外部世界交互的第一个关口。在 C++ 里，这件事拆开就是两块：HTTP 通信和JSON 序列化。
HTTP 这块，我推荐用cpp-httplib，单头文件、依赖少、上手快。如果对性能要求更高，可以用 libcurl，但配置起来麻烦一些。我一开始用 libcurl，光是编译链接就折腾了半天，后来换成 cpp-httplib，十分钟就跑通了。当然，如果你的项目已经有网络层，直接复用就行。
JSON 这块，nlohmann/json是首选。它的 API 很直观，和 Python 的字典操作很像：
#include <nlohmann/json.hpp> using json = nlohmann::json; json request; request["model"] = "your-model"; request["messages"] = json::array(); request["messages"].push_back({{"role", "user"}, {"content", "你好"}}); std::string body = request.dump();这里有个坑要注意：大模型的响应可能很大，解析时要注意异常处理。我遇到过模型返回被截断的情况，json::parse直接抛异常，如果没捕获，整个 Agent 就崩了。所以解析一定要包在 try-catch 里，并且对返回结构做校验，不能假设字段一定存在。
另一个坑是超时设置。模型调用可能很慢，尤其是长文本生成。如果不设超时，Agent 会一直卡在那里。我的做法是给 HTTP 请求设一个合理的超时（比如 60 秒），同时在上层加一个重试机制，超时后重试一到两次。
4.2 工具注册与调用：用函数对象做统一抽象
工具调用是 Agent 的核心能力。在 C++ 里，我用的方案是用一个统一的函数签名 + 注册表来管理所有工具。
using ToolFunc = std::function<std::string(const json& args)>; class ToolRegistry { public: void registerTool(const std::string& name, ToolFunc func) { tools_[name] = std::move(func); } std::string call(const std::string& name, const json& args) { auto it = tools_.find(name); if (it == tools_.end()) { return R"({"error": "tool not found"})"; } return it->second(args); } private: std::unordered_map<std::string, ToolFunc> tools_; };这个设计的关键在于统一签名：所有工具都接收 JSON 参数、返回 JSON 字符串。这样模型返回的工具调用请求可以直接解析后转发，不需要为每个工具写适配代码。
注册工具的时候，用 lambda 捕获需要的上下文：
registry.registerTool("get_time", [](const json& args) { auto now = std::chrono::system_clock::now(); auto t = std::chrono::system_clock::to_time_t(now); json result; result["time"] = std::ctime(&t); return result.dump(); });这里有个经验：工具函数一定要做参数校验。模型生成的参数不一定符合预期，可能缺字段、类型不对、甚至注入奇怪的内容。我早期没做校验，结果一个工具收到空参数直接段错误。后来加了校验，缺参数就返回错误信息，Agent 会自己调整重试。
4.3 记忆模块：短期用队列，长期用向量
记忆分两块。短期记忆就是对话历史，用一个有上限的队列就行：
class ShortTermMemory { public: void add(const json& message) { history_.push_back(message); if (history_.size() > max_size_) { history_.pop_front(); } } json getContext() const { return json(history_); } private: std::deque<json> history_; size_t max_size_ = 20; };用std::deque而不是vector，是因为要频繁在头部删除。这个细节很小，但影响性能。
长期记忆就复杂一些，通常涉及向量化和相似度检索。C++ 里做向量检索，可以用 hnswlib 这类库，也可以自己实现简单的余弦相似度。我一开始用的是暴力检索，数据量小的时候没问题，上千条之后明显变慢，后来换成了 hnswlib，速度快了很多。
这里要提醒的是：长期记忆的写入要有策略。不是每句话都值得存，通常只存关键信息或总结。我见过有人把所有对话都塞进向量库，结果检索出来的全是噪音。我的做法是让模型在每轮结束时判断“这轮有没有值得记住的信息”，有才存。
4.4 主循环与状态管理：小心死循环和状态爆炸
主循环是 Agent 的心脏。前面那个伪代码看起来简单，实际写起来要考虑很多：
class Agent { public: std::string run(const std::string& input) { memory_.add({{"role", "user"}, {"content", input}}); int step = 0; while (step < max_steps_) { auto response = model_.chat(memory_.getContext(), tools_.getSchema()); memory_.add(response); if (response.contains("tool_calls")) { for (auto& call : response["tool_calls"]) { auto result = tools_.call(call["name"], call["arguments"]); memory_.add({{"role", "tool"}, {"content", result}}); } } else { return response["content"]; } step++; } return "达到最大步数限制"; } private: ShortTermMemory memory_; ModelClient model_; ToolRegistry tools_; int max_steps_ = 10; };两个关键点：最大步数限制和状态清理。没有步数限制，模型可能陷入死循环，一直调用工具不返回。我踩过这个坑，一个工具返回格式不对，模型反复重试，跑了几十轮才停。加了max_steps_之后，最多十步就强制结束。
状态清理也很重要。每轮对话结束后，短期记忆要不要清空？我的做法是保留最近几轮，但定期做总结压缩，避免上下文无限增长。这个策略要根据实际场景调，没有标准答案。
5. 常见问题排查与避坑速查
5.1 编译与链接问题
C++ 项目最容易卡在编译链接上。几个高频问题：
| 问题现象 | 可能原因 | 解决思路 |
|---|---|---|
| undefined reference | 库没链接或顺序不对 | 检查 CMake 的 target_link_libraries |
| 头文件找不到 | include 路径没配 | 检查 target_include_directories |
| 运行时报缺 DLL | 动态库没打包 | 静态链接或把 DLL 放同目录 |
| 模板报错看不懂 | 实例化失败 | 从第一个错误看起，别被后面的吓到 |
我强烈建议用 CMake 管理项目，别手写 Makefile。CMake 的find_package和target_link_libraries能省掉大量手动配置。另外，Windows 上如果遇到运行库缺失，装一个 Microsoft Visual C++ Redistributable 通常能解决，这是很多桌面程序的常见依赖。
5.2 内存与崩溃问题
C++ 写 Agent，最怕的就是崩溃。几个典型场景：
- 悬空指针：对象已经释放，但还有指针在用。用智能指针能避免大部分。
- 多线程竞争：两个线程同时读写同一个容器。加锁，或者用线程安全的数据结构。
- 迭代器失效：遍历容器时修改了容器。先收集要改的，遍历完再改。
- 栈溢出：递归太深或局部变量太大。Agent 里少见，但解析大 JSON 时可能遇到。
我的经验是：能用值语义就用值语义，能用智能指针就用智能指针，实在需要裸指针的地方，写清楚谁拥有、谁释放。另外，调试时用 AddressSanitizer，能提前发现很多内存问题。
5.3 模型交互的坑
和模型打交道，问题往往不在代码，而在“模型不按预期返回”。常见的有：
- 返回格式不对：模型可能返回 Markdown 包裹的 JSON，解析前要先剥离。
- 工具名拼错：模型可能生成不存在的工具名，注册表要能优雅处理。
- 参数类型错：模型可能把数字写成字符串，工具函数要做兼容。
- 上下文超限：历史太长导致请求失败，要有截断或总结机制。
这些问题没有一劳永逸的解法，只能在使用中不断加固。我的做法是所有和模型交互的地方都加日志，出问题时能快速定位是模型的问题还是代码的问题。
5.4 性能优化的几个方向
如果 Agent 跑得慢，可以从这几个方向查：
- 网络延迟：模型调用是主要耗时，考虑并发或缓存。
- 数据拷贝：检查有没有不必要的大对象拷贝，用移动语义。
- 锁竞争：如果多线程，检查锁的粒度是不是太粗。
- JSON 解析：大 JSON 解析很耗时，考虑用更快的库或减少解析次数。
我实测下来，网络延迟通常占大头，代码层面的优化空间有限。所以如果延迟是瓶颈，优先考虑减少模型调用次数或做结果缓存，而不是死磕 C++ 代码。
6. 后续可以怎么扩展这套架构
这套架构搭起来之后，扩展性其实不错。几个我实际考虑过的方向：
多模型支持：把模型调用抽象成接口，不同模型实现不同后端，切换时只改配置。这个我已经做了，效果很好，测试时可以在本地小模型和远程大模型之间切换。
工具生态：工具注册表可以做成插件式，动态加载。不过 C++ 的动态加载比较麻烦，跨平台更麻烦，我暂时没做，用的是编译期注册。
分布式：如果 Agent 要处理高并发，可以把能力层拆成独立服务，Agent 主循环通过网络调用。这样 C++ 的部分可以专注编排，模型和工具用其他语言实现。
可观测性：加指标采集和链路追踪，方便排查线上问题。这块我还在摸索，C++ 的生态不如其他语言丰富，很多要自己写。
最后分享一个小技巧：先用 Python 把 Agent 逻辑跑通，再逐模块用 C++ 重写。这样你能快速验证想法，又能在关键部分拿到 C++ 的性能。我整个项目就是这么做的，Python 原型跑了两天，C++ 重写花了两周，但方向一直很清晰，没有走弯路。
