本文收录于专栏《AI Agent原理与实战》2026版—— 专栏系统覆盖 AI Agent 的记忆、工具、插件与实战点击订阅可跟踪后续更新。本课定位第 7 课教会模型能调用工具本课解决调得好ACIAgent-Computer Interface工程规范——工具描述即 prompt engineering、命名空间、高信号返回、25K token 截断惯例。这是全课程投入产出比最高的一课坏工具重构前后行为对比立竿见影。阶段 2单 Agent 核心机制 来源【补 Anthropic】与第 7 课连读关键字工具设计、ACI工程、Agent接口设计、工具描述规范、命名空间、高信号返回、Code Agent、token优化本节目录8.1 ACI工具描述即 Prompt Engineering8.2 选工具先决定不做什么8.3 命名空间规模化后的第一道秩序8.4 高信号返回与 token 预算8.5 Code Agent vs Tool-call Agent8.6 微软第 4 课的补充视角可信的工具设计8.7 实测结果8.8 动手练习概念讲解8.1 ACI工具描述即 Prompt Engineering传统 API 的调用方是确定性代码文档写错开发者会踩坑但调用本身永远精确。Agent 是非确定性调用方——它靠读 Schema 里的自然语言描述来理解工具偶尔还会产生幻觉。所以工具定义的每一行 description实质上都是 prompt engineering# 坏模型只能靠猜description:查询数据# 好模型知道何时用、怎么传、返回什么description:按条件搜索订单。返回匹配订单号、状态、金额、客户名支持分页。先按状态/金额过滤再翻页。这不是代码风格的洁癖。Anthropic 报告过一个标志性案例Claude Sonnet 3.5 在 SWE-bench Verified 上拿到当时最佳成绩靠的关键动作之一就是精修工具描述——不动模型权重只改工具的说明书错误率显著下降、任务完成率上升。工具描述是 Agent 系统里性价比最高的优化点。8.2 选工具先决定不做什么ACI 设计的第一步是决定不实现哪些工具。原则不包薄壳。一个 REST 端点包一个工具的一比一镜像是反模式——工具数量膨胀后模型选择准确率下降Anthropic 工具检索文档给出的量化口径超过 30-50 个可用工具后Claude 挑对工具的能力开始劣化官方建议超过 10 个工具或工具定义超过 1 万 token 时启用工具搜索按需加载检索日 2026-10-01。面向工作流组合。把真实业务动作“查客户 建跟进任务”做成一个工具好过让模型自己编排两个底层 API。宁少勿多重。两个功能重叠的工具会让模型在分岔口犹豫。Anthropic 的建议是重叠的工具宁可合并成一个带action参数的。8.3 命名空间规模化后的第一道秩序工具超过一打命名就要按域分组orders_search/orders_get/logistics_track/refund_create。模型看到前缀就能缩小选择面人也容易审计权限第 25 课的权限分级直接建立在命名空间上。8.4 高信号返回与 token 预算Agent 工具的返回值是写给模型的下一步输入设计目标只有一个用最少的 token 传递决策所需的信息。四个具体手段1. 面向下一步裁剪字段。返回模型回答问题所需的字段不要把数据库整行倒出来。地址、发票抬头、优惠券明细这些字段在绝大多数查询里都是噪声。2. 分页 / 过滤 / 截断。列表类工具必须支持过滤参数和分页默认页要小5-10 条。Anthropic 的经验数字Claude Code 默认把单次工具输出限制在约25,000 token——超过就截断。这是上下文预算的工程化体现第 13 课展开。3. response_format 开关。给返回值加一个concise/detailed枚举参数默认 concise 只给核心字段模型明确需要时才请求 detailed。Anthropic 用这招把 Slack 线程类工具的响应从约 206 token 压到约 72 token缩小近 3 倍。4. 错误信息写给模型看。第 7 课的错误四分法在这里升级错误消息要说清哪里错、怎么改比如status 字段取值必须是四选一你传了 paid——模型下一轮就能自纠错而不是把异常堆栈原样扔回去。8.5 Code Agent vs Tool-call Agent工具调用还有另一种范式模型不输出 JSON 调用意向而是直接写一段 Python 代码来表达动作。HuggingFace smolagents 把这两派分别叫 CodeAgent 与 ToolCallingAgent维度Tool-call AgentJSON 动作Code Agent代码动作动作表示{name: search, arguments: {...}}result search(query...)表达力单次一个组调用无逻辑循环、条件、中间变量、组合调用可靠性Schema 严格校验参数可控语法错/安全风险需沙箱执行生态OpenAI 兼容 API 事实标准smolagents 默认约千行代码的轻量实现两派不是对立而是光谱JSON 动作胜在可控与互操作代码动作胜在组合表达力一次生成查→过滤→汇总三步逻辑。smolagents 的立场“不确定就用 CodeAgent”代表了轻量派的选择而生产系统更常见的是 JSON 动作为骨架、把代码执行本身作为一个工具挂进去第 16 课实战对比。8.6 微软第 4 课的补充视角可信的工具设计微软第 4 课在工具设计的安全侧给了成体系的建议本课主体来自 Anthropic 的 ACI这一节收微软的口径两家用语不同但互补数据访问默认只读。原课以动态生成 SQL 为例LLM 生成的 SQL 有注入与恶意操作删库、篡改风险但通过正确配置数据库访问权限可以有效避免——对大多数数据库这意味着只读配置PostgreSQL、Azure SQL 等数据库服务应给应用分配只读SELECT角色。这正是第 7 课失败四分法里模型滥用的预防面与其事后熔断不如让危险操作在权限层就不可能发生。企业数据的只读仓库模式。数据从操作系统抽取转换到只读数据仓库并采用对 Agent 友好的 Schema——安全性、性能、可访问性一次优化应用权限仅限只读。友好的 Schema与 ACI 的精神一致接口设计面向非确定性的调用方。在安全环境中运行。工具执行环境本身要隔离第 27 课沙箱展开与只读权限形成纵深防御。一句话归纳两家的分工Anthropic 管工具怎么写得好用描述、返回、token微软管工具怎么用得安全权限、只读、环境——生产系统两套都要。案例实战坏工具重构对照实验目标同一个数据库、同一个模型、同一个问题只换工具设计量化对比调用行为与 token 消耗。坏工具query_data()无参数、无描述、返回 50 条订单全量 JSON含地址/发票/优惠券等 14 个字段好工具orders_search()状态过滤 金额下限 分页 concise/detailed 开关默认只返回 4 个决策字段测试问题“查金额超过 1500 元的待支付订单列订单号和客户名最多 5 个”环境Windows推荐Windows 10/11 Python 3.9pip install openai3.6.0setx DEEPSEEK_API_KEY sk-...设环境变量后新开终端运行python 08_bad_good_tool.py——脚本无操作系统相关依赖Linux本课实测环境Ubuntu 22.04Python 3.10.12openai 3.6.0deepseek-chat2026-10-01 实测对照实验跑两遍A 坏工具组、B 好工具组全程约 1 分钟、花费不到 1 分钱额度换国内模型GLM/MiniMax/MiMo接入参数与实测行为见第 7 课国内模型适配节代码改base_url与model两行完整代码# 08_bad_good_tool.py核心差异段完整可运行版见 code/ 目录importos,json,randomfromopenaiimportOpenAI clientOpenAI(api_keyos.environ[DEEPSEEK_API_KEY],base_urlhttps://api.deepseek.com/v1)# 模拟数据库50 条订单每条 14 个字段含地址/电话/发票抬头等random.seed(7)DB[{order_id:fSO-{1000i},status:random.choice([pending_payment,shipped,delivered,refunding]),amount:round(random.uniform(50,2000),2),customer_name:f顾客{i:02d}号,address:f某省某市…{random.randint(1,99)}号院…,# 全量字段见 code/items:[...],created_at:...,...}foriinrange(1,51)]# ---------- 坏工具无参数全量转储 ----------defbad_query_data()-str:returnjson.dumps(DB,ensure_asciiFalse)# 50 条全倒出来# ---------- 好工具过滤 分页 紧凑格式 ----------defgood_orders_search(status:str,min_amount:float0.0,page:int1,page_size:int5,response_format:strconcise)-str:rows[oforoinDBif(notstatusoro[status]status)ando[amount]min_amount]totallen(rows)rowsrows[(page-1)*page_size:page*page_size]ifresponse_formatconcise:# 默认只给决策必需字段rows[{order_id:o[order_id],status:o[status],amount:o[amount],customer_name:o[customer_name]}foroinrows]returnjson.dumps({total:total,page:page,page_size:page_size,orders:rows,next_page:page1ifpage*page_sizetotalelseNone},ensure_asciiFalse)BAD_TOOLS[{type:function,function:{name:query_data,description:查询数据,# ← 模型只能靠猜parameters:{type:object,properties:{}}}}]GOOD_TOOLS[{type:function,function:{name:orders_search,description:按条件搜索订单。返回匹配订单号、状态、金额、客户名支持分页。先按状态/金额过滤再翻页。,parameters:{type:object,properties:{status:{type:string,enum:[pending_payment,shipped,delivered,refunding],description:订单状态过滤空串表示不过滤},min_amount:{type:number,description:金额下限元默认 0},page:{type:integer,description:页码从 1 开始默认 1},page_size:{type:integer,description:每页条数默认 5最大 20},response_format:{type:string,enum:[concise,detailed],description:concise 只返回订单号/状态/金额/客户名detailed 返回全字段仅在明确需要时用}},required:[]}}}]Agent loop 与第 7 课相同完整代码见code/08_bad_good_tool.py额外统计每轮resp.usage里的 prompt/completion token。【已实测】2026-10-01deepseek-chat。8.7 实测结果同一问题“查金额超过 1500 元的待支付订单列订单号和客户名最多 5 个”指标A. 坏工具 query_dataB. 好工具 orders_search差异模型第 1 轮调用query_data({})空参orders_search(statuspending_payment, min_amount1500, page1, page_size5)B 一次构造出正确过滤条件工具输出体积27,741 字符全库转储561 字符1 页 5 条缩小约 50 倍prompt tokens2 轮合计12,8201,290降低约 90%completion tokens380245模型少做了人肉过滤回答正确性正确6 笔中列 5 笔正确6 笔中列 5 笔持平两个值得注意的行为细节坏工具没有立刻失败——模型很强它自己硬读 2.7 万字符做过滤答案照样正确。这正是工具设计容易被忽视的原因坏工具的代价不是错而是贵、慢、且脆弱数据库涨到 5000 条时坏工具直接超出上下文好工具只多翻几页。好工具的参数全靠 description 引导。模型没人教过min_amount它从描述金额下限元推断出要传 1500——这就是工具描述即 prompt的直接证据。8.8 动手练习把测试问题换成统计各状态订单数量——观察好工具需要response_formatdetailed或多次调用体会聚合查询该不该做成单独工具的设计判断。把数据库从 50 条加到 2000 条再跑 A 组看坏工具在第几轮爆掉上下文。小结ACI 是面向非确定性调用方的接口设计工具描述即 prompt engineering返回值即下一步的上下文。四个高信号返回手段裁剪字段、分页/过滤/截断25K token 惯例、response_format 开关、可自纠错的错误消息。选工具三原则不包薄壳、面向工作流组合、宁少勿重叠规模化靠命名空间分组。Code Agent 与 Tool-call Agent 是动作表示的光谱两端JSON 可控互操作代码组合表达力强。微软第 4 课的安全侧补充数据访问默认只读SELECT 角色、企业数据只读仓库 Agent 友好 Schema、安全环境运行——Anthropic 管好用微软管安全生产系统两套都要。工具手有了返回值预算粮定了下一课回到 Agent 自身怎么把这些能力组织成可靠的运行模式参见第 9 课《Agent 设计模式总论》。token 预算的全局视角在第 13 课《上下文工程》展开。扩展阅读 网络提示anthropic.com 需代理核心结论已摘进本课正文huggingface.co 走镜像export HF_ENDPOINThttps://hf-mirror.com学术站 arxiv.org 境内多可直连慢其余评测/规范站需代理pip 安装建议加清华镜像-i https://pypi.tuna.tsinghua.edu.cn/simple。详见总纲附录《国内网络访问与国产适配指南》。Anthropic《Writing effective tools for agents》2025-09-11https://www.anthropic.com/engineering/writing-tools-for-agentsAnthropic《Building effective agents》workflow 模式原文https://www.anthropic.com/engineering/building-effective-agentssmolagents 文档CodeAgent vs ToolCallingAgenthttps://huggingface.co/docs/smolagents/en/guided_tour论文《Executable Code Actions Elicit Better LLM Agents》arXiv:2402.01030代码动作优于 JSON 动作的实证https://arxiv.org/abs/2402.01030我的专栏蛋白 / 抗体 / 多肽 / 核酸分子模拟 / 动力学 / 对接药物 / 设计 / 案例AI / Agent / 大模型开源蛋白结构预测分子模拟基础小分子药物设计案例AI Agent系列开源蛋白生成方法实践分子动力学模拟-Amber蛋白药物设计案例化学大模型开源多肽设计模型分子动力学模拟-Gromacs多肽药物设计案例《AI Agent原理与实战》开源多肽性质预测分子动力学模拟-OpenMM开源小分子生成设计CADD中的机器学习模型DNA/RNA药物设计結合自由能高效计算配置《MCP 入门实战》siRNA药物设计模型UCSF DOCK系列我胡师兄说药《AI入门实战2026》ASO药物设计模型rDock系列 LeDock系列 gnina系列《经典机器学习实战》