企业官网建设流程全解析

本文收录于专栏《AI Agent原理与实战》2026版—— 专栏系统覆盖 AI Agent 的记忆、工具、插件与实战，点击订阅可跟踪后续更新。

本课定位：第 7 课教会模型"能调用"工具，本课解决"调得好"：ACI（Agent-Computer Interface）工程规范——工具描述即 prompt engineering、命名空间、高信号返回、25K token 截断惯例。这是全课程投入产出比最高的一课：坏工具重构前后行为对比立竿见影。

阶段 2｜单 Agent 核心机制 ｜ 来源：【补 ｜ Anthropic】（与第 7 课连读）

关键字：工具设计、ACI工程、Agent接口设计、工具描述规范、命名空间、高信号返回、Code Agent、token优化

本节目录

• 8.1 ACI：工具描述即 Prompt Engineering
• 8.2 选工具：先决定"不做什么"
• 8.3 命名空间：规模化后的第一道秩序
• 8.4 高信号返回与 token 预算
• 8.5 Code Agent vs Tool-call Agent
• 8.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：

两派不是对立而是光谱：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.9+，pip install openai==3.6.0，setx DEEPSEEK_API_KEY "sk-..."设环境变量后新开终端运行python 08_bad_good_tool.py——脚本无操作系统相关依赖
• Linux（本课实测环境）：Ubuntu 22.04，Python 3.10.12，openai 3.6.0，deepseek-chat，2026-10-01 实测
• 对照实验跑两遍（A 坏工具组、B 好工具组），全程约 1 分钟、花费不到 1 分钱额度
• 换国内模型（GLM/MiniMax/MiMo）：接入参数与实测行为见第 7 课"国内模型适配"节，代码改base_url与model两行

完整代码

# 08_bad_good_tool.py（核心差异段，完整可运行版见 code/ 目录）importos,json,randomfromopenaiimportOpenAI client=OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"],base_url="https://api.deepseek.com/v1")# 模拟数据库：50 条订单，每条 14 个字段（含地址/电话/发票抬头等）random.seed(7)DB=[{"order_id":f"SO-{1000+i}","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_ascii=False)# 50 条全倒出来# ---------- 好工具：过滤 + 分页 + 紧凑格式 ----------defgood_orders_search(status:str="",min_amount:float=0.0,page:int=1,page_size:int=5,response_format:str="concise")->str:rows=[oforoinDBif(notstatusoro["status"]==status)ando["amount"]>=min_amount]total=len(rows)rows=rows[(page-1)*page_size:page*page_size]ifresponse_format=="concise":# 默认只给决策必需字段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":page+1ifpage*page_size<totalelseNone},ensure_ascii=False)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-01，deepseek-chat。

8.7 实测结果

同一问题：“查金额超过 1500 元的待支付订单，列订单号和客户名，最多 5 个”

两个值得注意的行为细节：

1. 坏工具没有立刻失败——模型很强，它自己硬读 2.7 万字符做过滤，答案照样正确。这正是工具设计容易被忽视的原因：坏工具的代价不是"错"，而是贵、慢、且脆弱（数据库涨到 5000 条时，坏工具直接超出上下文，好工具只多翻几页）。
2. 好工具的参数全靠 description 引导。模型没人教过min_amount，它从描述"金额下限（元）"推断出要传 1500——这就是"工具描述即 prompt"的直接证据。

8.8 动手练习

1. 把测试问题换成"统计各状态订单数量"——观察好工具需要response_format=detailed或多次调用，体会"聚合查询该不该做成单独工具"的设计判断。
2. 把数据库从 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_ENDPOINT=https://hf-mirror.com；学术站 arxiv.org 境内多可直连（慢），其余评测/规范站需代理；pip 安装建议加清华镜像-i https://pypi.tuna.tsinghua.edu.cn/simple。详见总纲附录《国内网络访问与国产适配指南》。

• Anthropic《Writing effective tools for agents》（2025-09-11）：https://www.anthropic.com/engineering/writing-tools-for-agents
• Anthropic《Building effective agents》（workflow 模式原文）：https://www.anthropic.com/engineering/building-effective-agents
• smolagents 文档（CodeAgent vs ToolCallingAgent）：https://huggingface.co/docs/smolagents/en/guided_tour
• 论文《Executable Code Actions Elicit Better LLM Agents》（arXiv:2402.01030，代码动作优于 JSON 动作的实证）：https://arxiv.org/abs/2402.01030

我的专栏