3.1 理解与使用内置智能体

3.1 理解与使用内置智能体

内置 Agent 解决 80% 的场景，所以我们先把它用熟，再谈自定义。这一节把三个内置类的典型用法和组合套路讲实，不给虚的。

三件套的常规组合

最常见的搭配：一个 AssistantAgent 当"脑"（出主意、出函数调用），一个 UserProxyAgent 当"手"（执行、必要时问人）。这种组合在文档问答、代码生成里反复出现。

from autogen import AssistantAgent, UserProxyAgent
import os
cfg = {"model": "gpt-4o-mini", "api_key": os.environ.get("OPENAI_API_KEY")}

brain = AssistantAgent("brain", llm_config=cfg,
                       system_message="你分析需求并给出可执行步骤。")
hand = UserProxyAgent("hand", human_input_mode="NEVER",
                      code_execution_config={"use_docker": False})

chat = brain.initiate_chat(hand, message="列出当前目录的 py 文件。", max_turns=2)
print(chat.summary)
​

预期 hand 收到请求后执行对应代码，把文件列表回写，brain 再总结。这就是"脑手分离"的基本盘。

什么时候用纯 ConversableAgent

当你不需要模型，只想做一个转发或记录的中介时用它。比如一个"日志 Agent"，收到任何消息都只打印不回复，靠 register_reply 实现。

from autogen import ConversableAgent
cfg = {"model": "gpt-4o-mini", "api_key": os.environ.get("OPENAI_API_KEY")}
logger = ConversableAgent("logger", llm_config=None, system_message="你只记录。")

def record(recipient, messages, sender, config):
    print("[log]", str(messages[-1].get("content",""))[:50])
    return True, "已记录"   # 直接回复，不再调模型
logger.register_reply(trigger=ConversableAgent, reply_func=record, position=0)
​

多 Assistant 协作

两个 AssistantAgent 也能直接对话，适合"互审"结构：一个写、一个审，都不碰执行。

from autogen import AssistantAgent
cfg = {"model": "gpt-4o-mini", "api_key": os.environ.get("OPENAI_API_KEY")}
dev = AssistantAgent("dev", llm_config=cfg, system_message="你写 Python。")
rev = AssistantAgent("rev", llm_config=cfg, system_message="你只挑代码毛病。")
chat = dev.initiate_chat(rev, message="写个快排。", max_turns=4)
​

选型的工程判断

• 要执行 → 必带 UserProxyAgent。
• 只产出文本/建议 → AssistantAgent 足够，更安全。
• 要插自定义逻辑又不接模型 → ConversableAgent 配钩子。

我们主张：默认从最小组合起步（一个 brain + 一个 hand），不够再加角色，别一上来堆五六个 Agent——协作开销随角色数平方涨。

一个完整的脑手分离示例

下面把"脑出主意、手执行"跑通一个真实小任务：让 brain 生成读文件的代码，hand 真正执行并回写结果。注意 hand 用 NEVER 自动执行，所以代码会被真跑——测试环境请用无害代码。

from autogen import AssistantAgent, UserProxyAgent
import os
cfg = {"model": "gpt-4o-mini", "api_key": os.environ.get("OPENAI_API_KEY")}

brain = AssistantAgent("brain", llm_config=cfg,
                       system_message="你生成统计 py 文件数的代码。")
hand = UserProxyAgent("hand", human_input_mode="NEVER",
                      code_execution_config={"use_docker": False})

chat = brain.initiate_chat(hand, message="统计当前目录的 py 文件。", max_turns=2)
print(chat.summary)
# 你会看到 brain 给代码，hand 执行并把文件数列回，brain 总结
​

什么时候不该用内置

如果你的"Agent"其实不需要模型、只是个规则转发，用 ConversableAgent 配钩子比 AssistantAgent 省一次推理。我们见过有人给纯路由 Agent 也配强模型，每轮白烧 token。判断标准：这个角色需不需要"理解自然语言再生成新内容"，不需要就别接模型。

一个选型小结

回到开头：内置 Agent 覆盖大多数场景，先把它用熟。判断"要不要自定义"的标准很简单——当现成 Agent 的默认行为挡了你的需求（比如必须不调模型、必须改回复机制），才上子类或钩子。别为了"显得高级"提前定制，那只会引入不必要复杂度。

本节要点回顾

• 脑手分离：AssistantAgent 出主意，UserProxyAgent 落地。
• 纯转发/记录用不接模型的 ConversableAgent。
• 互审结构用两个 AssistantAgent 即可。

⚠️ 角色不是越多越好，每增加一个 Agent 就多一份协调和出错面，先小后大。

💡 内置 Agent 是"对话即编排"的预制件，先用预制件跑通，再考虑定制件。