从知乎热帖出发：Agent 工程师的 Prompt、Skill 与 Tools 工程化实践

1. 从知乎热帖聊起Agent 工程师到底在工程化什么先把结论摆在前面Agent 工程师不是「会写 Prompt 的人」也不是「会调 API 的人」而是能把 Prompt、Skill、Tools 三层拆开、分别治理、再拼回一条可观测链路的人。这个岗位的核心检索词就是 Agent 工程师它要解决的问题是让一个模型在真实业务里稳定地读文件、调工具、记状态、跑长任务而不是每次演示都靠运气。知乎那个热帖下面高赞回答基本都是一张学习路线图Prompt → Skill → Tools → RAG → Memory → 工作流 → 部署 → 多 Agent。路线本身没错但它有个副作用——让人误以为必须按顺序把每一层都学完才能上手。实际工程里不是这样。真实顺序往往是业务先抛出一个具体问题你测出来它在哪一层崩然后只补那一层。我见过最典型的翻车场景是这样的团队花两周打磨 Skill 的脚本和规则结果 Agent 还是选错 Tool、记不住上一轮信息、批量任务跑到一半断掉。回头一看问题根本不在 Skill而在 Tools 的注册粒度和 System Prompt 的边界设定。Skill 写得再漂亮Tools 层没给对能力Agent 就只能瞎猜。所以这篇不写「学习路线」写「工程分层」。我会按三条主线拆Prompt 怎么设计成可维护的模板、Skill 怎么封装成有目录结构的模块、Tools 怎么注册成模型能正确选择的配置。最后用一次本地验证流程把三层串起来并说明多模型调用时怎么用 TaoToken 统一 Key 和 API 通道避免每个模型一套环境变量。适合谁看已经会写 Python、调过至少一个模型 API、想往 Agent 方向转的开发者。不需要你先精通 RAG 或微调那些是后面按需补的。你需要的是一台能跑 Python 的机器、一个可用的模型通道以及愿意「测出来再改」的习惯。下面每一节都给可复制的代码和配置不写「连上后就能怎样」这种空话。踩过的坑我会直接标出来你照着改就行。2. TaoToken 前置把多模型 Key 收进一个通道在写 Prompt 和 Tools 之前先把模型通道理顺。原因很实际Agent 工程里你几乎一定会同时用多个模型——便宜的快模型做意图识别和 Tool 选择贵一点的强模型做复杂推理和代码生成。如果每个模型一套 Key、一套 Base URL、一套环境变量你的.env会迅速失控换模型时改到怀疑人生。TaoToken 在这里的角色是统一入口一个 Key、一个 Base URL通过 model 参数切换不同模型。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置里就写干净的https://taotoken.net/api。你需要准备三件套这三件套在后面每一层都会反复出现Base URLhttps://taotoken.net/apiAPI Key在控制台创建地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteModel ID具体模型名在模型列表或文档里查文档入口 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite创建 Key 的页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 进去点新建复制出来存好只显示一次。如果你只是想先验证模型通不通可以用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 直接试不用写代码。环境变量建议这样组织别把 Key 硬编码进代码export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_MODEL_FAST你的快模型ID export TAOTOKEN_MODEL_STRONG你的强模型ID为什么强调「统一通道」这件事因为 Agent 的调试成本大头不在写代码而在换模型重测。你调 Tool 选择准确率时可能要在三个模型之间来回切如果每次切换都要改代码里的 URL 和 Key你根本没法做对照实验。统一通道之后切换只是改一个环境变量。注意不要把 Key 提交到 Git。用.env加.gitignore或者用系统的密钥管理。团队协作时Key 走各自的本地环境不要共享同一个。这里有个常见误解要澄清统一通道不等于「所有模型行为一致」。不同模型对同一个 Tool schema 的理解、对同一个 Prompt 的遵循度都不一样。统一通道只是让你切换成本变低方便你针对每个模型单独调 Prompt 和 Tool 描述。这一点在第五节排障时会再展开。配好之后先别急着写 Agent用一段最小代码确认通道可用。这段代码后面会复用import os from openai import OpenAI client OpenAI( base_urlos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], ) resp client.chat.completions.create( modelos.environ[TAOTOKEN_MODEL_FAST], messages[{role: user, content: 只回复两个字通了}], ) print(resp.choices[0].message.content)跑出「通了」两个字说明通道没问题可以进入 Prompt 层。如果这里就报错先跳到第五节看 401 和连接类报错的处理别往下硬写。3. Prompt 与 Tools 的可复制配置三层拆开写这一节是全文的技术核心给三份可直接复制的配置Prompt 模板、Skill 目录结构、Tools 注册 JSON。三份配置的路径和字段名保持一致你复制过去改业务字段就能用。3.1 Prompt 模板把 System Prompt 当配置文件Prompt 最容易犯的错是写成一大段自然语言改一处牵动全身。正确做法是拆成固定骨架 可替换槽位。我用的骨架是四段角色、能力边界、工具使用规则、输出格式。# 角色 你是一个面向商家场景的任务型 Agent负责读取指定目录内的订单文件并汇总统计。 # 能力边界 - 你只能读取 /data/orders 目录下的文件禁止访问其他路径。 - 你不能执行删除、写入、网络请求类操作。 - 遇到超出边界的需求直接回复「超出权限范围」不要尝试绕过。 # 工具使用规则 - 需要读取文件时必须调用 read_file 工具参数 path 必须是 /data/orders 下的相对路径。 - 需要统计时先调用 read_file 拿到内容再在回复里做汇总不要臆造数据。 - 一次只调用一个工具拿到结果后再决定下一步。 # 输出格式 - 先给结论再给依据。 - 依据里必须列出实际读取到的文件名。这份模板的关键在于「能力边界」和「工具使用规则」分开写。边界是安全约束规则是行为约束调优时你只动其中一段不会互相污染。商家场景尤其需要边界因为默认的个人助理型 Tools 往往权限过宽。Prompt 里不要写「你是一个乐于助人的助手」这种废话它对行为没有约束力。每一句都要能对应到一个可验证的行为。3.2 Skill 目录结构一个 Skill 一个文件夹Skill 的本质是「可复用的能力包」它应该有自己的目录、入口、依赖和测试。我用的结构如下skills/ order_summary/ SKILL.md # 技能说明给人和 Agent 看 main.py # 入口函数 schema.json # 参数 schema tests/ test_main.py # 最小测试SKILL.md写清楚这个技能做什么、输入输出是什么、有什么限制。schema.json定义参数格式和 Tools 注册保持一致避免两处维护{ name: order_summary, description: 读取 /data/orders 下的订单文件并汇总金额仅支持 csv 和 json, parameters: { type: object, properties: { path: { type: string, description: 相对于 /data/orders 的文件路径例如 2024-06.csv } }, required: [path] } }main.py里做路径校验这是安全边界落地的地方import os import json BASE_DIR /data/orders def order_summary(path: str) - dict: full os.path.realpath(os.path.join(BASE_DIR, path)) if not full.startswith(os.path.realpath(BASE_DIR)): return {error: path out of allowed directory} if not os.path.exists(full): return {error: ffile not found: {path}} with open(full, r, encodingutf-8) as f: data json.load(f) total sum(item.get(amount, 0) for item in data) return {file: path, count: len(data), total: total}注意os.path.realpath这一步它能挡住../这类路径穿越。很多 Skill 翻车就翻在没做这一步Agent 被诱导读到了不该读的文件。3.3 Tools 注册配置让模型能正确选择Tools 注册的核心是 description 和 parameters 的写法。模型选错 Tool八成是 description 写得太模糊。注册配置我统一放在tools/registry.json{ tools: [ { type: function, function: { name: order_summary, description: 汇总 /data/orders 目录下某个订单文件的金额。当用户要求统计订单、汇总金额、查看某月订单时使用。不要用于读取非订单文件。, parameters: { type: object, properties: { path: { type: string, description: 相对于 /data/orders 的文件路径例如 2024-06.json } }, required: [path] } } }, { type: function, function: { name: list_files, description: 列出 /data/orders 目录下的所有文件名。当用户不确定有哪些文件、需要先查看目录时使用。, parameters: { type: object, properties: {}, required: [] } } } ] }description 里我特意加了「不要用于读取非订单文件」这种负向约束。实测下来负向约束对减少误调用有明显帮助尤其是当你有多个功能相近的 Tool 时。把三份配置串起来的调用代码import json from openai import OpenAI client OpenAI( base_urlos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], ) with open(tools/registry.json, r, encodingutf-8) as f: tools json.load(f)[tools] system_prompt open(prompts/order_agent.txt, r, encodingutf-8).read() resp client.chat.completions.create( modelos.environ[TAOTOKEN_MODEL_FAST], messages[ {role: system, content: system_prompt}, {role: user, content: 帮我看看 2024-06.json 的订单总额}, ], toolstools, tool_choiceauto, ) msg resp.choices[0].message print(msg.tool_calls)如果tool_calls里出现order_summary且参数是2024-06.json说明三层配置对齐了。如果模型没调工具而是直接编了个数字回到 Prompt 的「工具使用规则」那段加强约束。4. 本地验证一次完整的请求与结果确认配置写完必须验证而且要验证「工具真的被执行了」不能只看模型回复。这一节给一个完整的本地验证脚本把 Tool 调用、执行、结果回填、二次请求串成闭环。先准备测试数据mkdir -p /data/orders cat /data/orders/2024-06.json EOF [ {id: A001, amount: 120}, {id: A002, amount: 80}, {id: A003, amount: 200} ] EOF然后写验证脚本verify_agent.pyimport os import json from openai import OpenAI client OpenAI( base_urlos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], ) with open(tools/registry.json, r, encodingutf-8) as f: tools json.load(f)[tools] system_prompt open(prompts/order_agent.txt, r, encodingutf-8).read() def dispatch(name, args): if name order_summary: from skills.order_summary.main import order_summary return order_summary(**args) if name list_files: return {files: os.listdir(/data/orders)} return {error: funknown tool: {name}} messages [ {role: system, content: system_prompt}, {role: user, content: 帮我看看 2024-06.json 的订单总额}, ] resp client.chat.completions.create( modelos.environ[TAOTOKEN_MODEL_FAST], messagesmessages, toolstools, tool_choiceauto, ) msg resp.choices[0].message messages.append(msg) if msg.tool_calls: for call in msg.tool_calls: args json.loads(call.function.arguments) result dispatch(call.function.name, args) print(f[tool] {call.function.name} - {result}) messages.append({ role: tool, tool_call_id: call.id, content: json.dumps(result, ensure_asciiFalse), }) final client.chat.completions.create( modelos.environ[TAOTOKEN_MODEL_FAST], messagesmessages, toolstools, ) print([final], final.choices[0].message.content) else: print([no tool call], msg.content)跑起来应该看到类似输出[tool] order_summary - {file: 2024-06.json, count: 3, total: 400} [final] 2024-06.json 共 3 笔订单总额 400。这里有几个验证点必须确认第一[tool]那行说明工具真的被执行了不是模型编的。第二total是 400和测试数据对得上。第三[final]的回复里引用了实际文件名说明结果回填成功。如果你想验证安全边界把用户输入改成「帮我读一下 /etc/passwd」正确行为是模型回复「超出权限范围」或者工具返回path out of allowed directory。如果模型真的去调了工具且工具返回了文件内容说明你的边界没生效回去检查main.py里的 realpath 校验。再验证一次多模型切换。把TAOTOKEN_MODEL_FAST换成TAOTOKEN_MODEL_STRONG重跑观察 Tool 选择是否一致。如果强模型选了不同的 Tool说明你的 description 有歧义需要针对两个模型分别调。这就是统一通道的价值——切换只改环境变量对照实验成本极低。提示验证阶段建议把每次请求的 messages 完整打印出来存成日志。Agent 出问题时日志是你唯一能复现现场的东西。5. 常见报错排查401、连接失败、choices 为空这一节按真实报错来每条给现象、原因、处理。你大概率会碰到其中至少两条。401 Unauthorized / invalid api key现象请求直接返回 401或者 SDK 抛AuthenticationError。原因通常是三种Key 没设进环境变量、Key 复制时带了空格或换行、Key 被撤销了。处理先确认环境变量真的生效echo $TAOTOKEN_API_KEY | head -c 8只打印前 8 位确认不是空。如果为空说明export没在当前 shell 生效重新 source 一下。如果 Key 看起来正常还是 401去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认这个 Key 还在、没被删。注意 Base URL 要写https://taotoken.net/api不要多加/v1之类的后缀路径不对也会报鉴权类错误。local proxy failed / connection refused现象SDK 报连接失败或者提示本地代理不可用。原因你的环境里可能残留了代理配置或者 Base URL 写错了。处理先检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY、ALL_PROXYenv | grep -i proxy如果有清掉再试unset HTTP_PROXY HTTPS_PROXY ALL_PROXY然后确认 Base URL 拼写正确用 curl 直接测curl -s -o /dev/null -w %{http_code}\n https://taotoken.net/api返回 200 或 401 都说明网络通返回 000 说明连不上检查网络和 DNS。reading choices of undefined / choices 为空现象代码里访问resp.choices[0]报 undefined或者choices是空数组。原因请求本身失败了但 SDK 没抛异常返回了一个错误结构。常见于 model ID 写错、参数不合法、或者触发了内容过滤。处理先把完整响应打出来别直接取 choicesresp client.chat.completions.create(...) print(resp.model_dump_json(indent2))看返回里有没有error字段。如果是 model 不存在去文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 核对准确的 Model ID。如果是参数问题检查tools的 JSON 结构是否符合 OpenAI 兼容格式type必须是functionfunction.name不能有空格。OAuth / 认证流程相关报错如果你用的是 Claude Code 这类带 OAuth 的客户端可能会碰到认证过期或回调失败。这类问题的通用处理是先确认客户端版本再重新走一次认证流程把 Base URL 和 Key 按客户端要求填进对应配置文件。Claude Code 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有具体的配置字段。如果你同时用多个客户端比如 Cline、Codex建议把三件套Base URL、Key、Model ID统一记在一个地方避免每个客户端填得不一样导致排查困难。Tool 调用相关模型不调工具 / 调错工具现象模型直接回复文本不触发 tool_calls或者调了错误的 Tool。原因description 太模糊、Prompt 里工具规则不明确、或者tool_choice设成了none。处理先确认tool_choiceauto。然后检查每个 Tool 的 description 是否写清楚了「什么时候用」和「什么时候不用」。如果两个 Tool 功能相近在 description 里互相排除。最后在 System Prompt 的「工具使用规则」里加一句「必须调用工具不要凭记忆回答」。长任务中断现象批量任务跑到一半停了没有报错。原因单次请求超时、上下文超长、或者循环里没处理异常。处理给每次请求加超时和重试循环里捕获异常并记录当前进度。长任务建议拆成小批次每批存一次中间状态中断后能从断点续跑。这部分属于 Memory 和任务管理后面按需补但排查思路是「先定位断在哪一步再决定补哪一层」。6. 多模型通道与长期编码把工程化跑成日常三层配置跑通、报错能自己排之后剩下的就是把它变成日常。这里有两个方向值得投入一是多模型通道的长期管理二是用 Coding Agent 辅助你读源码、写第一版。多模型通道这块TaoToken 的价值在长期使用中才明显。你会有快模型做 Tool 选择、强模型做复杂推理、可能还有专门的代码模型。统一 Key 和 Base URL 之后你的代码里只有一处 client 初始化切换模型只是换 model 参数。团队协作时新人拿到环境变量就能跑不用挨个申请 Key。如果你要长期做 Agent 开发和编码可以看一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合需要持续调用、频繁切换模型的场景比按次调用更省心。具体额度以页面说明为准我不在这里编数字。另一个习惯是「用 Agent 学 Agent」。碰到 Skill 不稳定、Tool 选错、Memory 记不住别急着加规则先用 Coding Agent 去读相关框架的源码看别人怎么处理同类问题。它给的解释当线索不当结论最后回到你的业务里用测试验证。这个循环跑多了你会形成自己的判断问题到底在 Prompt、Skill 还是 Tools。最后给一个实用技巧给你的 Agent 建一个debug/目录每次出问题就把当时的 messages、tool_calls、工具返回、最终回复存成一个 JSON 文件。攒够十几个案例之后你会发现翻车模式高度重复改起来就有针对性了。这比漫无目的地调 Prompt 有效得多。工程化的终点不是「学完所有层」而是「业务出问题时你能快速定位到该改哪一层」。Prompt、Skill、Tools 三层拆开治理统一通道降低切换成本日志和测试保证可复现——这三件事做到你就已经在做 Agent 工程师的日常工作了。