大家好，我是AI淇橦学。
开篇回顾
前两期我们聊清楚了Agent的概念（AI大脑 + 工具 + 自主规划），以及一个完整Agent由哪8个模块组成。说实话，那两期都是理论——这一期开始，我们要真正进入"怎么干"的阶段。
这期学完，你会得到什么？ 一个真正能跑的Python程序——你给它一份报价单模板和客户信息，它能自动填好并生成新的Word文档。这可是整个办公Agent的第一块基石。
接下来的几期实操课，我会在AI编程工具里演示代码生成，然后通过终端展示运行效果。最后我们再统一构建一个可视化界面。
为什么这么做？因为这样你能在学习过程中看代码、理解代码。看得多了，自然就有深刻印象和理解了。虽然一开始有点枯燥，但对学习帮助真的很大。
如果你有编程基础，可以直接跳到构建环节。
一、先建立一个核心认知
在动手之前，我必须说清楚一件事：
⚠️ 核心认知：AI本身并不能直接操作任何东西。它只能处理文字、输出文字。它不能打开你的Word文件，不能往文档里写数据，不能保存任何东西。
那Agent是怎么做到"打开文件、填写内容、保存结果"的？
答案是：它自己做不到，它是"发指令"，让程序去做。
这就是工具调用的本质：AI输出一段特殊格式的指令，说"我需要调用read_file工具"，外部程序读到这段指令，真正去执行，把结果返回给AI，AI再继续处理。
AI从头到尾只是在处理文字。真正动手的是程序，不是AI本身。
二、工具调用的完整流程
用这期的场景走一遍：你有一份销售报价单模板（Word文档），里面有客户名称、联系人、产品型号、报价金额等空白字段，你想让Agent根据客户信息自动填好，另存为一份新文档。
① 你发出指令，程序把工具清单一起给AI
你说：“帮我把这份报价单模板填好，客户是深圳科技有限公司，联系人李总，报价58000元”
同时，程序把可用工具清单发给AI：你有这些工具可以用：read_file（读取文件）、write_content（写入内容）、save_file（保存文件）
② AI理解指令，决定第一步用哪个工具
AI思考：要填写模板，得先知道模板里有哪些字段。第一步应该读取文件内容。
AI输出指令：调用read_file工具，参数：路径 = 报价单模板.docx
③ 程序识别出工具调用指令，真正去执行
程序打开报价单模板.docx，读取所有内容，找到所有空白字段：【客户名称】【联系人】【报价金额】【日期】……
④ 程序把执行结果返回给AI
程序返回：文件读取成功，找到4个待填写字段：【客户名称】【联系人】【报价金额】【报价日期】
⑤ AI拿到结果，继续决定下一步
AI：现在知道有4个字段了。根据你提供的信息，依次调用write_content工具填入每个字段……
⑥ 循环执行，直到完成，调用save_file另存新文件
全部填完，AI调用save_file，另存为"报价单_深圳科技_20250615.docx"，告诉你：已完成，新文件已保存。
✅ 这个循环的本质：AI决策 → 程序执行 → 结果返回AI → AI继续决策。AI负责"想"，程序负责"做"。
三、工具设计的三条原则（动手前必须懂）
理解了流程，在真正写代码之前，还有三条原则必须先知道——这三条决定了你的Agent稳不稳定。
原则一：每个工具只做一件事
不要做一个"读取并写入并保存"的大工具。要做三个独立的工具，每个只负责一件事。
- ❌ 错误做法：
process_file——读取 + 写入 + 保存全做，出错不知道是哪步的问题 - ✅ 正确做法：
read_file（只读）/write_content（只写）/save_file（只保存）
原则二：工具描述必须写清楚
AI靠工具描述来决定"什么时候调用哪个工具、传什么参数"。描述模糊，AI就猜，猜错就出错。
- ❌ 模糊描述：
read_file：读取文件 - ✅ 清晰描述：
read_file：读取本地Word(.docx)文件内容。参数：file_path（文件完整路径）。返回：文件全部文字内容 + 识别到的所有待填写字段列表
原则三：返回结果要让AI看得懂
工具返回的内容是AI下一步的决策依据，返回一堆乱码或复杂嵌套数据，AI会读错。
- ❌ 难以理解：
<w:t>客户名称</w:t><w:t></w:t>……（原始XML） - ✅ 清晰结构化：
找到待填写字段4个：【客户名称】【联系人】【报价金额】【报价日期】
四、实操开始：从零搭建第一个工具
概念讲完了。现在我们真正动手——用Codex创建项目，让AI帮你写出三个工具，然后实际跑一遍，看到报价单被自动填好。
整个实操分5步：
- 安装Codex，创建项目文件夹
- 准备报价单模板文件
- 用Codex生成三个工具的代码
- 运行程序，看到实际效果
- 验证结果是否正确
第一步：安装Codex，创建项目
这里说明一下，任何具备AI功能的编程工具都可以，比如Claude Code、Trae、VS Code等等这些编程工具IDE都可以。
安装Codex：
- 打开浏览器，访问codex
- 点击"Download"，下载对应你电脑系统的版本（Windows或Mac）
- 安装完成后打开Codex，第一次打开会提示登录，注册一个账号即可（有免费额度）
- 需要爬梯（🪜），可以换成国产trae
创建项目文件夹：
- 在你的电脑上新建一个文件夹，命名为
sales-agent（位置随意，比如桌面） - 在文件夹里再新建两个子文件夹：
-
templates——放报价单模板output——放生成的结果文件
- 打开Codex，点击左上角菜单"File"→"Open Folder"，选择你刚创建的
sales-agent文件夹
第二步：准备报价单模板
我们需要一份真实的Word格式报价单模板。你有两个选择：
选项A：用你自己公司的报价单模板（推荐，更贴近真实场景）
把你现有的报价单Word文件复制进templates文件夹，把文件名改为报价单模板.docx。
然后打开这个文件，把需要每次修改的字段替换成占位符格式，例如：
| 原来的内容 | 改成占位符 |
|---|---|
| 深圳科技有限公司 | 【客户名称】 |
| 李总 | 【联系人】 |
| 58,000元 | 【报价金额】 |
| 2025年6月15日 | 【报价日期】 |
选项B：新建一个简单的模板（适合没有现成模板的人）
打开Word，新建文档，输入以下内容，保存为报价单模板.docx放进templates文件夹：
123456789101112131415销售报价单
客户名称：【客户名称】
联系人：【联系人】
联系电话：【联系电话】
报价日期：【报价日期】
产品明细：
产品名称：【产品名称】
规格型号：【产品型号】
报价金额：【报价金额】
备注：【备注】
感谢您的垂询，期待与您合作！
📌 注意：占位符格式用【】括起来，这样程序能准确识别哪些位置需要填写。
前期初学阶段这样是为了让你更加了解占位符，后期熟悉了之后可以直接让codex帮你自行分析占位符。
第三步：用Codex生成工具代码
这是最关键的一步。你不需要自己写代码——你只需要用自然语言告诉Codex你想做什么，它来生成代码。
3.1 打开Codex的AI对话窗口
在Codex界面里，按快捷键Ctrl + L（Windows）或Cmd + L（Mac），右侧会出现一个对话框，这就是你和AI交流的地方。
3.2 创建主程序文件
把下面这段提示词复制粘贴到Codex的AI对话框，然后发送：
📋 发给Codex的提示词（直接复制使用）：
1234567891011121314151617181920212223242526272829303132333435363738394041我要做一个销售报价单自动填写的Agent，请帮我用Python写一个程序，
文件名是agent.py，实现以下功能：
【背景说明】
- 我有一份Word格式的报价单模板，放在templates/报价单模板.docx
- 模板里用【字段名】格式标注了需要填写的位置，例如：【客户名称】【联系人】【报价金额】【报价日期】
- 我想通过运行这个程序，自动把客户信息填入模板，生成一份新的Word文档，保存到output文件夹
【需要实现的三个工具函数】
1. read_file(file_path)
- 读取指定路径的Word(.docx)文件
- 找出文件中所有【xxx】格式的占位符
- 返回：文件的完整文本内容，以及识别到的所有占位符列表
- 打印清晰的提示：找到了哪些占位符
2. write_content(template_path, field_data)
- 参数field_data是一个字典，key是字段名（不含【】），value是要填入的内容
- 例如：{"客户名称": "深圳科技有限公司", "联系人": "李总", "报价金额": "58,000元"}
- 把模板中所有匹配的【字段名】替换成对应的值
- 返回：替换后的文档对象（不直接保存文件，只在内存中操作）
- 打印每个字段的替换结果
3. save_file(doc, output_path)
- 把文档对象保存到指定路径
- 路径必须是output文件夹内的新文件名，不能覆盖原始模板
- 打印保存成功的提示和文件路径
【主程序逻辑】
在程序末尾加一个演示用的main()函数：
- 调用read_file读取模板，打印找到的占位符
- 定义一组测试用的客户数据（客户名称、联系人、联系电话、报价日期、产品名称、产品型号、报价金额、备注）
- 调用write_content填写内容
- 调用save_file保存到output/报价单_测试.docx
- 最后打印"✅ 完成！请查看output文件夹"
【技术要求】
- 使用python-docx库操作Word文件
- 代码要有清晰的中文注释
- 每个函数都要有错误处理（用try/except），出错时打印清晰的错误信息
- 程序运行过程中要有清晰的进度提示，让用户知道每一步在做什么
这是在codex界面
3.3 等待Codex生成代码
Codex会告诉你生成完毕，你打开即可；其他的编程工具则会生成完整的代码并显示在对话框里。代码会自动写入你的agent.py文件。
💡 如果Codex生成的代码和你预期不符，不需要手动修改——直接在对话框里继续说"xxx部分不对，请改成……"，Codex会根据你的反馈修正。
这是在vscode界面中
第四步：安装依赖库，运行程序
4.1 安装python-docx库
程序需要用到一个叫python-docx的工具库来操作Word文件。在Codex底部有一个终端窗口（如果没有，点击菜单"Terminal"→"New Terminal"），在终端里输入：
1pip install python-docx
按回车，等待安装完成（会看到"Successfully installed"字样）。
💡 如果提示没有Python：需要先安装Python。访问python.org，下载最新版本安装即可。安装时记得勾选"Add Python to PATH"选项。
Codex直接也会直接帮你进行安装。
4.2 运行程序
在sales-agent文件夹下，点击右键终端中打开，输入：
1python agent.py
按回车。程序会开始运行，你会看到类似这样的输出：
1234567891011121314151617181920212223242526📂 正在读取模板文件：templates/报价单模板.docx
✅ 文件读取成功
📋 找到待填写字段8个：
- 【客户名称】
- 【联系人】
- 【联系电话】
- 【报价日期】
- 【产品名称】
- 【产品型号】
- 【报价金额】
- 【备注】
✏️ 开始填写字段...
客户名称 → 深圳科技有限公司 ✓
联系人 → 李总 ✓
联系电话 → 138-0000-0000 ✓
报价日期 → 2025年6月15日 ✓
产品名称 → 工业传感器套件 ✓
产品型号 → XS-2000B ✓
报价金额 → 58,000元 ✓
备注 → 含安装调试服务 ✓
💾 正在保存文件...
✅ 完成！文件已保存至：output/报价单_测试.docx
✅ 完成！请查看output文件夹
第五步：验收结果
程序跑完之后，打开output文件夹，找到报价单_测试.docx，用Word打开它。
验收清单：
- 文件成功生成，能正常打开
- 所有【】占位符都被替换成了真实内容
- 内容填写到了正确的位置（客户名称就是客户名称，不是联系人）
- 原始模板文件
templates/报价单模板.docx内容没有任何变化（这条很重要） - output文件夹里是新文件，不是覆盖了原文件
全部通过，说明第3期的核心功能已经完成。
五、遇到问题怎么办
情况一：运行报错"ModuleNotFoundError: No module named ‘docx’"
说明python-docx没装好。在终端重新运行：
1pip install python-docx --upgrade
情况二：运行后output文件夹里没有文件
在Codex对话框里说：“程序运行完了但output文件夹里没有生成文件，请检查save_file函数，确认output文件夹存在，如果不存在就自动创建它”
情况三：生成的文件打开后占位符还在，没有被替换
在Codex对话框里说：“生成的文件里【客户名称】等占位符没有被替换，请检查write_content函数的替换逻辑，确认替换的是段落里的run文本而不只是paragraph文本”
情况四：其他报错
把终端里显示的红色报错信息全部复制，粘贴到Codex对话框里，说：“运行出现了这个报错，请帮我修复”。Codex会直接告诉你怎么改。
💡 处理报错的黄金法则：不要自己猜哪里错了，直接把报错信息交给Codex，它比你更快找到问题。
六、这期做了什么——小结
这期你从零开始，用Codex创建了第一个可以真正运行的工具模块：
read_file：读取Word模板，识别所有占位符write_content：把客户数据填入模板（操作内存副本，不动原文件）save_file：把结果另存为新文件
这三个工具，完成了"读文件 → 填内容 → 保存"的核心闭环。现在的程序还需要你手动在代码里写客户信息——下期我们会给它加上记忆系统和知识库，让它能自动从你的历史客户资料里找到信息，不需要你每次手动输入。
结尾
下期预告： 现在你每次用Agent都需要手动填写客户信息。如果你有几十个老客户的资料，Agent能不能直接从里面找到对应的客户？第4期我们来做这件事：给Agent建一个客户资料知识库，让它能用语义搜索找到"深圳那家做传感器的客户"——即使你记不住公司全名。
思考题： 你在用自己的报价单模板时，遇到了哪些问题？占位符能被正确识别吗？评论告诉我，我会在下期开头统一解答。
关注公众号「AI淇橦学」，和AI一起成长。
有问题或建议？后台留言即可。
