第三章：智能体开发与定制

第三章：智能体开发与定制

本章要回答的三个问题

1. 内置 Agent 已经能做什么，什么情况下必须自己造一个？
2. 工具（函数调用）怎么定义、注册、被 Agent 真正执行？
3. 配置项和上下文状态该怎么调，才能让 Agent 既听话又记得住前文？

为什么有这一章

第二章拆了 Agent 的内部构造，这一章把它变成你手里的工具。真实项目里，你很少只靠两个内置 Agent 撑全场——你需要一个会查数据库的 Agent、一个只负责画图的 Agent、一个把自然语言转成 SQL 的 Agent。这些"会干具体活"的 Agent，靠的就是自定义子类加工具注册。我们说对话即编排，工具就是 Agent 伸向现实世界的手：没有工具，Agent 只能在语言里空转；有了工具，它才能查数据、调接口、写文件，把对话变成行动。这一章的代码密度是全册最高的，因为"会干活"全靠动手——光看定义学不会挂工具，必须自己写函数、注册、跑通回环。另一个常被低估的点是配置与状态：同一个 Agent，human_input_mode 设错一档，它可能卡在等人工输入，也可能擅自行动酿成误操作。所以本章不只讲"怎么造"，还讲"怎么调得听话、怎么记得住前文"。我们刻意把工具注册放在中间节，是因为它是连接"语言智能"和"真实系统"的咽喉，也是后面所有高级玩法（群聊协作、外部集成）的前提。把这一章练扎实，第四章的群聊才有真正能干的成员。

读完能解决什么

读完这一章，你能拿到几项"让 Agent 真正干活"的能力：第一，你能给任意 Agent 挂上一个真实可用的 Python 函数，并看懂函数调用回环里每条消息的角色——哪条是模型的调用请求、哪条是执行结果回流；第二，针对一个具体任务，你能判断该用内置 Agent 还是自定义子类，不再对着文档发呆；第三，你能用一个字典描述函数签名并注册到 AssistantAgent，让模型知道何时、如何调用；第四，你能列出 human_input_mode 三档并说明各自适用阶段，从而精确控制"哪一步需要人拍板"；第五，你能说清上下文窗口满了之后框架默认怎么截断，并据此设计长任务的状态保留策略。工具注册是 AutoGen 最常用也最容易写错的能力，本章会把它讲透，让你从"会定义函数"跨到"模型真的会调用它"。

各节分工表

先决条件

• 第二章已读，知道消息怎么在 Agent 间流转。
• 会写普通 Python 函数，理解装饰器和类型标注即可。
• 准备好一个能返回结构数据的本地函数用于练手。

知识点清单（可考核）

• 能写出继承 ConversableAgent 的子类并覆盖 generate_reply。
• 能用一个字典描述函数签名，并注册到 AssistantAgent。
• 能解释函数调用消息里 arguments 与返回值分别出现在哪条消息。
• 能列出 human_input_mode 三档并说明各自适用阶段。
• 能说清上下文窗口满了之后，框架默认怎么截断。

一个关键的工程判断

工具不是越多越好。每多一个工具，模型选错的概率就上升一点，上下文也更长。我们的经验：先只给最必要的两三个工具，跑通后再按需加。另外，工具命名和描述直接决定模型会不会用对——名字叫 get_user_profile 比叫 gup 清楚太多，模型选起来更准。

本章常见误区

这一章写代码时最容易踩两个坑。误区一：工具一股脑挂十几个，觉得"功能全"。每多一个工具，模型选错的概率就上升一点，上下文也更长，反而更常调错。先只给最必要的两三个，跑通再加。误区二：函数命名和描述随手写，叫 gup 而不是 get_user_profile，模型根本不知道该什么时候用。工具名和描述直接决定模型会不会用对，这是性价比最高的优化点。

与前面章的边界

第三章只解决"单个 Agent 怎么造、怎么挂工具、怎么调配置"，不进入多个 Agent 协作（第四章）、不碰生产化加固（第五章）、不接外部数据库或 API 的系统级集成（那是 5.5 和第六章）。如果你在读本章时已经在设计"三个 Agent 怎么轮流改稿"，那是第四章的活，先把单个 Agent 驯服。

往下走到哪

第四章讲"多个 Agent 怎么一起聊"——你在这里造好的单个 Agent，到第四章会被放进 GroupChat 里轮转。详见第四章。