第二章：核心架构与智能体机制

第二章：核心架构与智能体机制

本章要回答的三个问题

1. 一个 Agent 内部由哪些部件组成，消息进来后经历了什么？
2. 内置的 AssistantAgent、UserProxyAgent 到底差在哪，我该用哪个？
3. 对话流是怎么被"驱动"起来的，谁决定下一步轮到谁说？

为什么有这一章

第一章你脑子里有了"几个角色在对话"的画面，但那只是外部视角——你看到的是角色在说话，却不知道一句话从产生到落地经过了什么。要让对话真的发生，得知道框架内部怎么把一条消息从 A 送到 B，怎么调大模型拿回回复，又怎么把函数执行结果重新塞进对话。这一章把黑盒打开，我们重点看三件事：系统分层、Agent 基类和消息流。系统分层让你知道配置、模型、对话三层各自管什么，不至于把模型参数配到对话层；Agent 基类让你明白所有内置类型共享同一套收发机制，差别只在默认行为；消息流让你看清一条消息从 generate_reply 到真正发出去经过了哪几圈钩子。理解内部机制后，你调试群聊死循环、定位消息错乱才有坐标，否则只能盲调参数——很多"我的 Agent 不说话了"的问题，根因都是没看清消息在某个钩子被截断。这一章不要求你读源码，但要求你建立一张"消息旅程图"，后面每章的坑几乎都能在这张图上定位。我们对本章的态度是：宁可慢，不能糊，因为地基之下的地基如果晃，上面六章都站不稳。

读完能解决什么

读完这一章，你能拿到几项底层能力：第一，你能画出一张"消息从发起到落地的旅程图"，标出 register_reply 这个钩子在哪一圈起作用，以后排查"消息没发出去"直接去对应环节看；第二，面对"我想让 Agent 自动执行代码"还是"我想让它只给建议"，你能直接选对 UserProxyAgent 还是 AssistantAgent，不再试错；第三，你能解释 human_input_mode 在 UserProxyAgent 里如何阻塞或放行，从而控制"哪一步需要人拍板"；第四，你能写出带 llm_config 的 AssistantAgent，并说清 model、api_key 该放哪一层，避免配置错位；第五，你能向同事讲清"子类复用父类收消息逻辑"这一句看似简单却决定你对框架理解深度的关系。这种选型与定位能力在真实项目里每天都会用到，是区分"会用"和"懂框架"的分水岭。

各节分工表

先决条件

• 读完了第一章，知道 Agent、Conversation 指什么。
• 愿意看一点类继承关系，不需要深究源码，但要知道"子类复用父类收消息逻辑"。
• 手边有可跑的环境，本章代码片段建议跟着敲一遍。

知识点清单（可考核）

• 能画出 ConversableAgent 到 AssistantAgent / UserProxyAgent 的继承关系。
• 能说清一条消息从 generate_reply 到发出去经过了哪几步。
• 能解释 human_input_mode 在 UserProxyAgent 里如何阻塞或放行。
• 能写出带 llm_config 的 AssistantAgent 并说明 model、api_key 放哪。
• 能区分"自动执行函数"和"只给函数调用建议"两种模式。

一个常被忽略的事实

很多开发者以为 AssistantAgent 和 UserProxyAgent 是两种"能力"，其实它们共享同一套收发消息机制，差别只在默认行为：一个默认接模型、一个默认不接；一个默认不执行、一个可配置执行。这个认知能帮你避开"为什么我的 Assistant 不执行代码"这类经典困惑——因为它本来就只动口。想动手，要么配 UserProxyAgent，要么改默认。

本章常见误区

这一章最容易掉的两个坑都和"以为懂了"有关。误区一：把内置 Agent 当成两种不同能力，于是拼命在 AssistantAgent 上找"执行代码"的开关。其实它们共享同一套收发机制，差别只在默认行为，想动手就去配 UserProxyAgent 或改默认，而不是换类。误区二：跳过消息流直接背 initiate_chat 的签名，结果群聊一出错就不知道消息卡在哪一圈——钩子没理解，调试全靠运气。

与前面章的边界

第二章只打开"单个 Agent 内部"和"一次对话如何被驱动"，不教你怎么造自定义 Agent（第三章）、不碰多个 Agent 如何协作（第四章）、不接任何外部工具（那要等第三章）。如果你在读本章时已经在想"怎么让 Agent 查数据库"，说明你越界了，先把这个 Agent 的收发明白透。

往下走到哪

第三章接着讲"怎么造一个自己的 Agent、怎么给它挂工具"。第二章你学会了 Agent 的内部机制，第三章就把它用起来——详见第三章各节。