博客选题助手跑了一阵子之后,我遇到一个很小的意外。
那天我说:“参考我写过的东西,给我 5 个还没写过的新选题。”
它开始调工具。read_published_topics 调了一次,read_ideas 调了一次,然后…… save_topics 调了三次。三次的参数只有标题顺序不同,但文件名都一样。最后一次写完之后,前两次的结果就没了。
它给我的回复是:“已为你生成并保存 5 个选题。”
从它的角度看,这句话没说错。但从我的角度看,那天下午我丢了两版选题,而且完全不知道发生过。
更有意思的是另外一件事:data/published-topics.md 明明就在项目里,它也读成功了,可中间有一轮它偏偏去调了 read_ideas,然后拿着一份两年前随手写的东西当“已发布过的内容”做去重。
工具它都会调。问题是:它会挑错工具,会重复做同一件事,做错了还会告诉你成功了。
新手系列第 5 篇里我们给 Agent 加工具时,关心的是“能不能调得起来”。这一讲关心的是另一件事:调错了会怎样,以及有没有得救。
工具一旦真的开始写东西,它就不只是一个功能开关了,它是这整套系统的风险边界。
阅读提示:本文是「Agent 工程进阶」系列的第 3 篇,面向已经给 Agent 加过工具、但开始出现误调用或副作用失控的读者。如果你还没做过第一个 Agent,建议先看新手系列的让 Agent 更像项目:工具、记忆、文件读写和简单界面。如果你想要一张整体地图,可以看第 0 篇从 Demo 到可交付:如何做一个 Agent 项目。
一、粒度:一个工具到底该多大
第一个要回答的问题不是“加什么工具”,而是“这个东西应该做成几个工具”。
粒度没切好,后面所有优化都是在歪地基上刷漆。常见的错有三种。
第一种:太粗。 典型症状是一个工具配一个万能参数:
manage_files(action="read", path="outputs/x.md")
manage_files(action="write", path="outputs/x.md", content="...")
manage_files(action="delete", path="outputs/x.md")
这种设计对写代码的人很省事,对模型却很糟糕。它必须先想清楚 action 该填什么,再想清楚不同 action 下哪些参数有效——而这两件事在工具描述里通常是说不清的。更要命的是:删除和读取共用一个入口,意味着模型犯错的成本从“返回空”变成了“删了文件”。
第二种:太碎。 按实现步骤拆,而不是按意图拆:
list_output_files -> read_output_file -> count_output_files -> filter_topics_by_tag
模型要完成“看看以前写过哪些选题”这件小事,得连着调四个工具,中间任何一次猜错参数就得重来。每一步都在消耗上下文,每一步都是一次采样错误的机会。
Anthropic 在那篇讲怎么写工具的工程博客里给了个很实用的说法:工具内部要把计算做掉,而不是把计算甩到上下文里。 四个工具串起来做的事,如果永远是一起被调用的,那它应该是一个工具。
第三种:以底层 API 为界,而不是以用户意图为界。 你的存储是三个表,不代表模型要面对三个工具。模型不该知道你有几张表。
一个可用的判断标准
我用这两条:
能不能一句话说清「什么时候该调它、什么时候不该」? 它是完成一件用户能复述的小事,还是完成半个步骤?
两句话合起来,可以推出两条很机械的收敛规则:
- 如果两个工具总是一起被调用(日志里 80% 的情况成对出现),合并。
- 如果一个工具经常要连调多次才能干完一件事,拆开。
用选题助手走一遍,新手篇那四个工具的粒度其实都有问题:
| 原来的样子 | 问题 | 改法 |
|---|---|---|
read_published_topics() 无参数 | 太粗:只要想读就只能读全部。文件涨到 300 条时全进上下文 | 加 limit 和 filter_tag,返回摘要 + 指针 |
read_ideas() 与 read_published_topics() 各读各的 | 模型分不清“已发布”和“随手记”,是误调用高发区 | 合成 list_topics(source=published|notes|all),用枚举而不是两个名字相近的工具 |
save_result(content) | 参数只有一个大字符串,模型自己拼文件名 | 结构化为 title / angle / outline / tags,文件名由代码按 slug 生成 |
record_adoption(topic_title) | 靠标题字符串匹配,标题稍变就匹配不上 | 用工具生成并返回的 id |
注意最后一条:不要让模型去编 ID、路径、日期格式这类东西。 让工具返回一个不透明的 id,模型照抄。这比让它自己拼路径可靠一个数量级。
参数设计的三条硬规则
规则一:不要 action 这类万能参数。 一个动词一个工具。名字用动词开头,read_、list_、search_、save_、update_ 分开,模型看名字就能判断副作用。
规则二:能枚举的不要自由文本。 source 用 enum: [published, notes, all],比“请填 published 或 notes”有效十倍,因为前者是 schema 约束,后者是愿望。
规则三:必填参数越少越好。 其余给默认值,并在描述里写清楚默认是什么。每多一个必填项,就多一次“模型编了个值”的机会。
返回值:给结论和指针,不给全文
这一条是第 1 篇「压」和「隔」在工具层的落实。
差的做法:把 300 行已发布选题全文返回,占 4000 tokens
好的做法:返回 20 条摘要(标题 + 日期 + 标签),并说明"共 300 条,已按相关性返回前 20 条,可调 limit 或 filter_tag 精确查询"
关键在那个说明。模型知道结果被截断了、知道还剩多少、知道怎么继续——它就不需要靠猜。
二、工具太多:选择困难是怎么发生的
工具数量是我在 Agent 项目里见过的、最被低估的稳定性变量。
现象是这样的:三个工具时它精准得像老员工;加到十五个,它开始挑错。不是随机挑错,是挑名字看起来最像的那个——“参考我写过的东西”这句里有“写过”,它就选了 read_notes(我记东西的地方),而不是 read_published(我发文章的地方)。
这不是模型蠢。回到第 1 篇说的上下文干扰:每个工具的定义都在占上下文,工具越多,每个工具得到的注意力越少,名字相近的越容易混淆。而且这个退化是渐进的——加第七个工具的时候你不会察觉,加到第十五个回头看才发现不对。
我的经验区间是:单个 Agent 常开工具控制在 5~12 个。超过这个范围,先别想换模型,先想怎么减。
三招把数量压下来
第一招:分层装载。 工具分成两层:
| 层级 | 包含 | 什么时候进上下文 |
|---|---|---|
| 基础层 | 只读工具、list_* | 常开 |
| 写入层 | save_*、update_*、外部副作用 | 进入写模式后才注入,或每次调用前经人确认 |
写工具类工具平时根本不该出现在它的选项里。你在描述想法的那一轮,它不需要「保存」这个选项。
第二招:合并同类。 三个 read_* 合成一个带 source 枚举的工具,既省上下文又消掉了“挑哪个”的问题。注意这和上一条不是矛盾的:先按需装载,装进来的那批里再做合并。
第三招:命名空间。 工具来自不同来源时,用前缀把它们隔开:asana_search、drive_search。Anthropic 那篇博客里专门测了命名方案对工具选择准确率的影响,结论是命名空间的选择对效果有实打实的影响,而且不同模型偏好不同,要用你自己的评测去选。别在这一步凭审美拍板。
描述怎么写:这是性价比最高的一处改动
工具描述是直接写进上下文、直接影响模型判断的一段文本,但很多人写得像 API 文档的边角料。
看一个反例和一个正例:
{
"name": "read_published_topics",
"description": "读取已发布选题",
"inputSchema": { "type": "object", "properties": {} }
}
{
"name": "list_topics",
"description": "按来源列出历史选题,返回标题 / 日期 / 标签摘要,不含正文。"
"用于生成新选题前检查是否与已有内容重复。"
"如果你要找的是今天刚生成的候选,用 suggest_topics 而不是这个。"
"如果用户没说要参考历史,不要主动调用。",
"inputSchema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": ["published", "notes", "all"],
"description": "published=已发布文章;notes=随手记的想法;all=两者,默认 published"
},
"limit": {
"type": "integer",
"description": "返回条数,默认 20,最大 50"
}
},
"required": []
}
}
正例里多了四样东西,每一样都对应一类失败:
| 加的东西 | 消灭的失败 |
|---|---|
| 做什么、返回什么 | 模型不知道会拿到什么格式,调完还得再解析一遍 |
| 什么时候用 | 该用的时候不用 |
| 什么时候不要用 | 不该用的时候乱用(这一条比「什么时候用」更有效) |
| 相近工具的区分 | 名字相近导致误选 |
「什么时候别用」这一句特别值得写。描述里只写正面用法,等于假设模型会自己克制——它不会。而每个字段都写 description 这件事,看起来琐碎,实际上是给模型做参数选择时的上下文。
最后一个小技巧:给工具本身编号或分组标注,比如描述开头带 [写] [读] [外部]。模型对这种显式标记非常敏感,比你把“请勿随意使用”写在系统提示词里有效得多。
三、错误语义:报错不是报错,是给模型的下一步指令
这一节是整篇我认为最值钱的部分。
大多数人的工具失败时是这样的:
def save_topics(path, content):
with open(path, "w", encoding="utf-8") as f: # 文件不存在 -> 抛异常
f.write(content)
然后框架把一段 Python 异常栈塞进上下文:
Traceback (most recent call last):
File "src/tools.py", line 47, in save_topics
with open(path, "w", encoding="utf-8") as f:
FileNotFoundError: [Errno 2] No such file or directory: 'output/2026-10-06.md'
这段东西对模型意味着什么?意味着:有一堆它读不懂的噪音,里面藏着一个路径 output/2026-10-06.md(注意,还写错了目录名,正确的是 outputs/)。
模型最可能的反应是:**再试一次,换一个它猜的目录。**于是错误开始繁殖。
问题不在异常本身,在于我们把给程序员看的错误信息,交给了模型。程序员看到 FileNotFoundError 知道去查路径为什么不存在;模型看到它,只知道“失败了”,然后靠猜。
正确做法是:工具不抛异常,返回结构化的失败结果。 而这个结果要回答的是——下一步怎么办。
三类错误,三种下一步
| 类型 | 含义 | 模型的下一步 | 例子 |
|---|---|---|---|
retryable | 临时故障,同样的参数再试一次可能成功 | 重试(限定次数) | 超时、限流、网络抖动 |
invalid_argument | 参数不对,重试一百次也一样 | 换参数 | 缺必填字段、值不在枚举里、路径越界、日期格式错 |
unavailable | 这条路走不通,重来也是浪费 | 换方案、降级、或向用户说明 | 文件不存在且不可创建、权限不足、外部服务不可用 |
分类的价值在于:它直接决定了 Agent 下一步该做什么。 一个未分类的错误会让模型在“要不要重试”这件事上反复摇摆,这是很多死循环的来源。
来看一个统一的返回信封:
# src/tools/envelope.py
from dataclasses import dataclass, field
@dataclass
class Result:
ok: bool
data: dict = field(default_factory=dict)
error: dict | None = None
@staticmethod
def success(**data):
return Result(ok=True, data=data)
@staticmethod
def fail(kind: str, message: str, *, hint: str = "", **extra):
"""
kind: retryable / invalid_argument / unavailable
hint: 明确告诉模型下一步该做什么,这是整个设计里最重要的字段
"""
return Result(ok=False, error={
"kind": kind,
"message": message,
"hint": hint,
**extra,
})
def to_model(self):
"""给模型看的:短、结构化、带下一步"""
if self.ok:
return {"ok": True, **self.data}
return {"ok": False, **self.error}
用它改写那个读文件的工具:
# src/tools/topics.py
from pathlib import Path
from tools.envelope import Result
ROOT = Path(__file__).resolve().parents[2] # 项目根目录
DATA = ROOT / "data"
def list_topics(source: str = "published", limit: int = 20):
files = {
"published": [DATA / "published-topics.md"],
"notes": [DATA / "notes" / "ideas.md"],
"all": [DATA / "published-topics.md", DATA / "notes" / "ideas.md"],
}
if source not in files:
return Result.fail(
"invalid_argument",
f"source 只能是 published / notes / all,收到的是 {source!r}",
hint="请从这三个值里重新选一个再调用",
allowed=["published", "notes", "all"], # 直接把可用值给它
)
limit = max(1, min(int(limit or 20), 50))
missing = [str(p.relative_to(ROOT)) for p in files[source] if not p.exists()]
if missing and source != "all":
return Result.fail(
"unavailable",
f"还没找到 {missing[0]}",
hint="这个文件需要用户先创建,或改用 source='all' 读取其它来源",
)
items = parse_topics([p for p in files[source] if p.exists()]) # 内部解析
return Result.success(
items=[{"id": t.id, "title": t.title, "date": t.date, "tags": t.tags}
for t in items[:limit]],
total=len(items),
truncated=len(items) > limit,
note=f"共 {len(items)} 条,已返回前 {limit} 条,可用 filter_tag 精确查询",
)
三个细节,对应三种常见的糟糕失败:
allowed=[...]:不要在错误里只说“值不对”,要把可用值直接列出来。 把候选值摆到它眼前,比让它回忆提示词里的枚举可靠得多。hint写的是下一步动作,不是错误定位。“没有找到文件”是定位,“改用 source=‘all’”才是下一步。truncated+note:告诉它被截断了、还剩多少、怎么继续。
错误信息也会污染上下文
有一件事很容易忽略:错误信息会留在上下文里,而且权重很高。
一次调用失败 → 错误信息进上下文 → 模型看到失败 → 再试 → 再失败。三轮之后,上下文里会有三段高度相似的失败记录,模型会更加确信“这条路走不通”(哪怕第一次只是参数写错了),或者干脆被它们占去注意力。
所以有两个配套动作:
- 同一失败原因最多重试一次。 第二次要么换参数,要么换方案,不要原地重试第三次。
- 错误信息要短,且同一类错误只保留最后一次。 这个可以在写入上下文时做去重——已经在那儿的一段错误堆栈,别再堆第二份。
最后补一条和第 2 篇的连接:工具报错是 lesson 最主要的来源。 同一类错误(比如 invalid_argument)在同一个会话里被触发两次以上,就该由代码写一条教训——“调用 list_topics 时不要自由发挥 source 的值,只允许 published / notes / all”。这样一来,工具层的错误就不只是被处理掉,还会沉淀成下一次不再犯同一个错的依据。
四、幂等:因为重试一定会发生
写这一节是因为开头那个事故的根因就是它。
save_topics 被调用了三次,产生了什么?如果它每次都真写一遍,三次调用 = 三次副作用。对这种按文件名覆盖的写,后果只是丢内容;如果工具是“追加一条记录”“发一条消息”“扣一次钱”,后果就是三倍。
而重试这件事,你不需要写重试逻辑,它也会发生:
- 模型看错误觉得该重试,自己重来一遍;
- 网络超时,客户端断开,但服务端其实已经写完了——超时不等于失败,这是最经典的坑;
- 你的编排层加了自动重试,而工具是非幂等的。
所以问题的出发点不是“要不要支持重试”,而是:这个工具被调用两次,会发生什么?
四类工具,四种命运
| 类型 | 调用多次的结果 | 例子 | 怎么对待 |
|---|---|---|---|
| 天然幂等 | 完全一样,无副作用累积 | list_topics、read_* | 放心重试 |
| 伪幂等 | 结果一样,但中间状态会闪 | 按固定文件名覆盖写 | 要注意原子性(下面说) |
| 天生非幂等 | 每次都多一份 | append 记录、计数 +1、发消息、下单 | 必须加唯一键或人类确认 |
| 不可逆 | 做了就回不来 | 删除、覆盖发布、转账 | 必须确认 + 可回滚(第 7 篇讲) |
大部分人的工具停在第二类浑然不觉,第三类出事了才知道。
三个立刻能用的做法
做法一:写操作自带唯一键。
不要让模型决定“写到哪”,让它传内容,工具算唯一的 slug。同一个 slug 被写两次,第二次应该是更新而不是新增。
# src/tools/save.py
import hashlib
import os
from datetime import date
from pathlib import Path
from tools.envelope import Result
OUT = Path(__file__).resolve().parents[2] / "outputs"
def slugify(title: str) -> str:
"""同样标题 -> 同样 slug,这是幂等的地基"""
h = hashlib.sha1(title.encode("utf-8")).hexdigest()[:8]
return f"{date.today().isoformat()}-{h}"
def atomic_write(path: Path, text: str):
"""先写临时文件再替换:写到一半崩了也不会留下半个文件"""
path.parent.mkdir(parents=True, exist_ok=True)
tmp = path.with_suffix(".tmp")
tmp.write_text(text, encoding="utf-8")
os.replace(tmp, path) # 原子替换
def save_topics(*, title: str, angle: str, outline: list[str], tags: list[str]):
if not title.strip():
return Result.fail("invalid_argument", "缺少 title",
hint="请先给这组选题起一个标题再调用")
slug = slugify(title)
path = OUT / f"{slug}.md"
existed = path.exists()
atomic_write(path, render_md(title, angle, outline, tags))
return Result.success(
id=slug,
path=str(path.relative_to(OUT.parent)),
action="updated" if existed else "created",
note="这是同标题的更新,不是新文件" if existed else "已新建文件",
)
最后那个 action 字段别省。它让模型(和你)知道这次到底做了什么。开头那次事故如果返回了 action="updated",模型大概率不会再写第三次,我也立刻就能发现。
做法二:把 append 改成 upsert + 去重。
追加是最常见的非幂等操作。历史记录、采纳记录这种东西,不要往文件末尾追加一行,改成带唯一键的写入:
def record_adoption(*, topic_id: str, outcome: str):
"""
topic_id 来自 list_topics / suggest_topics 的返回,模型照抄即可
同 id 再写一次 = 更新,而不是多一行
"""
rows = load_jsonl(DATA / "adoptions.jsonl")
existing = next((r for r in rows if r["topic_id"] == topic_id), None)
if existing:
existing.update(outcome=outcome, updated_at=now())
else:
rows.append({"topic_id": topic_id, "outcome": outcome, "created_at": now()})
write_jsonl(DATA / "adoptions.jsonl", rows)
return Result.success(topic_id=topic_id, action="updated" if existing else "created")
做法三:遵循三条硬规则。
写前可读: 写之前能不能先查到目标当前是什么? 写后可验: 写完之后有没有办法再读一次确认结果? 失败可恢复: 写到一半崩了,系统状态是“没写”还是“写坏了”?
atomic_write 就是把“写坏了”变成“没写”。这三个问题的答案决定了你的 Agent 在出错的时候有没有得救。
还有一条边界要说清楚:非幂等且不可逆的工具,不该由模型自己决定是否执行。 那是第 7 篇「人机边界」要解决的问题,这里只留一句——在没做确认机制之前,别在你的工具列表里放 delete_*。
五、动手改一遍:把第 5 篇那四个工具翻新
现在把新手第 5 篇的工具层整体重构一遍。
改之前
# src/tools.py —— 原来的样子
def read_published_topics():
with open("data/published-topics.md", encoding="utf-8") as f:
return f.read() # 全文返回,文件多大就占多少上下文
def read_ideas():
with open("notes/ideas.md", encoding="utf-8") as f:
return f.read() # 文件名相近,模型经常选错
def save_result(content):
name = f"outputs/{datetime.now():%Y%m%d}.md"
with open(name, "w", encoding="utf-8") as f:
f.write(content) # 同一天写两次 = 第二次干掉第一次
return "已保存"
def record_adoption(title):
history = json.load(open("data/history.json", encoding="utf-8"))
history.append({"title": title, "date": today()}) # 标题一变就匹配不上
json.dump(history, open("data/history.json", "w", encoding="utf-8"))
七行代码,七个坑:路径硬编码且大小写写错也没有任何反馈;异常直接往上抛;全文返回没有上限;同一天保存两次会互相覆盖;靠标题字符串匹配;写入非原子;没有任何东西告诉模型“这次是新建还是覆盖”。
改成这样:
blog-topic-agent/
src/
main.py
memory/
store.py # 第 2 篇改造的记忆层
extract.py
recall.py
tools/
envelope.py # 统一返回结构 Result.ok / Result.fail
topics.py # list_topics 读
suggest.py # suggest_topics 生成候选
save.py # save_topics 写(幂等 + 原子)
adopt.py # record_adoption(upsert)
registry.py # 工具字典 + 分层装载 + 工具激活清单
data/
published-topics.md
notes/ideas.md
adoptions.jsonl # 第 2 篇里从 history.json 拆出来的
memory.jsonl
outputs/
第一步:统一出口
所有工具都返回 Result,由一层包装负责翻译给模型:
# src/tools/registry.py
from tools import topics, suggest, save, adopt
from tools.envelope import Result
READ_ONLY = {
"list_topics": (topics.list_topics, "列出历史选题,用于查重"),
"suggest_topics": (suggest.suggest_topics, "生成候选选题,不写文件"),
}
WRITE = {
"save_topics": (save.save_topics, "把选定选题写入 outputs/"),
"record_adoption": (adopt.record_adoption, "记录采纳结果"),
}
def active_tools(mode: str = "read"):
"""mode=read 时,写工具根本不在候选列表里"""
tools = dict(READ_ONLY)
if mode == "write":
tools.update(WRITE)
return to_schemas(tools) # 转成各家 API 的 tools=[...] 格式
def call(name, args, *, mode="read"):
table = {**READ_ONLY, **WRITE}
if name not in table:
return Result.fail("invalid_argument", f"没有名为 {name} 的工具",
hint="可用工具:" + "、".join(sorted(table)),
allowed=sorted(table))
if name in WRITE and mode != "write":
return Result.fail("unavailable", f"{name} 需要先进入写模式",
hint="请先向用户确认要保存,再申请进入写模式")
try:
return table[name][0](**args)
except TypeError as e: # 参数不对,别甩栈给模型
return Result.fail("invalid_argument", f"参数不匹配:{e}",
hint=f"请检查 {name} 的必填参数后重试")
except Exception as e: # 兜底,但必须结构化
return Result.fail("retryable", f"内部错误:{type(e).__name__}",
hint="可以原样重试一次;再失败请换方式或告知用户")
这段里有三件事同时落地:分层装载、错误语义、调用前的参数护栏。
注意那个 TypeError 分支——模型把参数写错了,这本不该由工具自己发现,而是编排层该拦下来的。拦住它,模型看到的就是“参数不对,检查一下必填项”,而不是一段栈。
第二步:给工具加上使用前说明
前面讲过的描述规范,集中到一个文件里统一维护,别散落在各个工具函数旁边:
TOOL_DOCS = {
"list_topics": {
"description": "按来源列出历史选题的摘要(标题/日期/标签)。"
"用于生成新选题前检查重复。"
"只要用户明确说要参考以前写过的内容才使用。",
"params": {"source": "published=已发布,notes=随手记,all=全部,默认 published",
"limit": "1-50,默认 20"},
},
"save_topics": {
"description": "[写] 把一组选题写入 outputs/ 下的 md 文件。"
"同标题重复保存会更新原文件而不是新建。"
"只在用户明确要保存时使用,不要主动调用。",
"params": {"title": "必填,这组选题的标题",
"angle": "切入角度", "outline": "大纲条目列表", "tags": "标签列表"},
},
}
「不要主动调用」这几个字,是我给所有写工具的默认配置。
第三步:改完之后的对比
| 改造前 | 改造后 | |
|---|---|---|
| 工具数量(上下文里可见) | 4 个全开 | 读模式 2 个,写模式 4 个 |
| 失败信息 | Python 异常栈 | 结构化:kind + message + hint + allowed |
| 同样的错重试 | 模型自己猜,可能无限重试 | kind=retryable 才重试,且最多一次 |
同参数重复调用 save_topics | 后一次覆盖前一次,悄无声息 | 返回 action="updated",明确告知是更新 |
| 写入中断 | 留下半个文件 | atomic_write,没写就是没写 |
| 靠标题匹配 | 标题一改就失效 | 工具返回 id,模型照抄 |
| 返回体大小 | 文件多大占多少上下文 | 默认 20 条摘要,truncated 说明还可怎么查 |
改造前后都没有“变得更聪明”,它的能力甚至少了一半(读模式下看不见写工具)。它只是变成了一个不会悄悄毁掉东西的系统。
六、MCP:把设计好的工具按统一协议露出去
新手第 5 篇讲 MCP 时,我给的建议是“知道它是什么就够了”。那是对的,因为那个时候最要紧的是把工具写出来。
现在你可以回头看它了,但要先说清楚它的位置:
MCP 是包装层,不是替代品。 它提供不了任何一个你现在写不出来的能力。它解决的是“同一套工具怎么被不同客户端、不同复用方发现和调用”。
这句话有个直接推论,值得当成铁律:如果你的工具粒度、描述、错误语义没设计好,接入 MCP 只会把混乱标准化。 一个带 action 万能参数、失败就抛异常栈的工具,接进 MCP 之后依然是个烂工具,只不过现在它挂着别人的进程、更难调试了。
三个概念
MCP 服务端对外提供三类东西:
| 概念 | 是什么 | 谁来主导调用 |
|---|---|---|
| tools | 模型可以调用的动作,有名字、JSON Schema 输入、结构化返回 | 模型决定 |
| resources | 只读的资源,可以被列举和读取的数据(文件、记录等) | 客户端 / 应用逻辑决定何时注入 |
| prompts | 预置的提示词模板 | 用户或应用层选用 |
这三个区分很重要,尤其前两个。很多人把所有东西都做成 tools,结果模型面前摆了一堆 get_*。能做成 resource 的就不要做成 tool——resource 由客户端决定怎么加载,不占模型的工具选择空间,天然避开了第二节说的选择困难。
什么时候真的需要它
给我自己定的三条:
- 同一套工具要在多个客户端里用。 你在 CLI 里写完的工具,明天想在另一个支持 MCP 的客户端里用,不想复制一遍代码——这就是 MCP 的主场。
- 要接别人已经写好的服务端。 用一个现成的数据源连接器,比自己写一套 API 封装划算。
- 工具开始需要跨进程隔离。 比如一组工具有一定危险度,你希望它们跑在另一个进程里、带独立的权限和凭据,输出只能通过协议回来。这时候进程边界本身就是安全措施。
什么时候别碰
也有三条,其中第三条是新手篇没说过的:
- 项目还是单个脚本。
- 工具都是你自己写的、不会在别处复用。
- 你的工具还没跑稳。 进程内函数调用是最容易被调试的形态——断点、单步、日志全在一起。一旦拆成跨进程协议,你要同时看两边的日志,还要处理传输和序列化问题。先把工具在本进程内调通、测过,再考虑搬家。 顺序反了,你会在还没验证工具对不对的时候,先背上联调的成本。
一个最小示例
概念性的写法(各家 SDK 细节有差异,重点看字段语义):
# server.py —— 把博客选题助手的工具包成一个 MCP server
from mcp.server import Server
from tools import topics, save
srv = Server("blog-topic")
@srv.tool(
name="list_topics",
description="列出历史选题摘要,用于生成新选题前查重。不要用作读取今日生成的候选。",
annotations={"readonly": True, "idempotent": True}, # 只读 + 幂等
)
def list_topics(source: str = "published", limit: int = 20):
r = topics.list_topics(source=source, limit=limit)
return r.to_model()
@srv.tool(
name="save_topics",
description="[写] 把选题写入 outputs/。同标题重复调用会更新而非新建。须经用户确认。",
annotations={"readonly": False, "destructive": False, "idempotent": True},
)
def save_topics(title: str, angle: str, outline: list[str], tags: list[str]):
r = save.save_topics(title=title, angle=angle, outline=outline, tags=tags)
return r.to_model()
@srv.resource("blog://published")
def published_topics():
"""作为资源暴露:客户端决定何时读取,不占用模型的工具选择空间"""
return topics.list_topics(source="published", limit=200).to_model()
注意两个地方都做了什么:annotations 里明确声明了「只读 / 幂等 / 是否有副作用」,这是给客户端做权限判断用的;而返回值依然是第三节那套信封,严丝合缝地接上了。
协议换了,工具设计的原则一条都没变。
MCP 的三个真实成本
用之前也要知道代价:
第一,权限边界被放大。 一个本地函数调用的权限,取决于你的进程;一个 MCP 服务端的权限,取决于它带着什么凭据、能被谁连接。尤其远程服务端——你在“接一个工具”,实际是“给一段外部代码开了你系统的门”。第 7 篇会细讲权限分级,这里只要记住:越靠近真实资产,越不能靠一句提示词约束。
第二,工具列表会污染上下文。 连上五个服务端,每个暴露二十个工具,你的上下文里就躺了一百个工具定义。第二节的选择困难和第 1 篇的上下文干扰会一起找上门。解决办法不是挑服务端,而是按需加载、默认关闭,只在当前任务需要时才把某一组工具放进这一轮的工具列表。
第三,调试链路变长。 以前一个断点到底,现在要跨进程追。这一条和第 0 篇里说的“搭一条可观测链路”直接相关:没有 trace 的 Agent 不要接入 MCP,否则出问题的时候你连是哪一边的错都不知道。
七、一份可以直接照着自查的清单
改完工具层之后,对着过一遍:
- 每个工具能不能一句话说清「什么时候用、什么时候别用」?(说不出来的那个,多半该拆或该并)
- 有没有带
action这种万能参数的工具? - 模型有没有在被迫拼写 ID、路径、日期格式?(有就应该改成由工具返回不透明 id,让模型照抄)
- 工具失败时返回的是结构化结果,还是异常栈?里面有「下一步怎么办」吗?
retryable/invalid_argument/unavailable三类错误有没有分开?- 写工具被调用两次会怎样?有没有唯一键?失败时会留下半写状态吗?
- 可用工具的总数是多少?有副作用的工具是不是默认不可见?
- 上一次「工具被调用但结果不符合预期」,你是什么时候发现的、怎么发现的?
最后一条最容易被答不上来,也最重要。工具层的可观测性,决定了你能不能发现它出过问题。
常见误区
误区一:先接 MCP 生态,工具以后再优化。 顺序反了。工具设计是地基,协议是包装。地基没打好,包装得越标准,迁移成本越高。
误区二:错误信息越详细越好。 对程序员是,对模型不是。详细的错误栈会占上下文、干扰注意力,还会引诱它去猜容易猜错的东西。要短、要分类、要给下一步。
误区三:工具描述写得像 API 文档。 描述要划出的不是“能做什么”,而是“只能在这种情况下做、其他情况别碰”。
误区四:重试是免费的。 对非幂等工具,每一次重试都是一次真实副作用。先想清楚重复调用的后果,再考虑要不要加重试。
工具在整套系统里的位置
工具层是 Agent 唯一和真实世界发生接触的地方,所以后面几节讲的很多东西,最终都落在这里:
- 编排与多 Agent(第 4 篇):多 Agent 本质上是把工具划分给不同的角色,让每个角色的工具列表变小。粒度没切好的工具,拆成几个 Agent 只会把问题复制几份。
- 评估体系(第 5 篇):工具层的评估指标很好定——选对了吗、参数对了吗、有没有多调、该放弃时放弃了吗。
- 可靠性与成本(第 6 篇):重试、降级、预算控制,很大一部分是对工具失败的处理策略。
- 人机边界(第 7 篇):不可逆工具必须有确认、权限、审计和回滚。
回到开头那次事故。改造之后,同样的场景是这样:
它第一次调 save_topics,得到 {"ok": true, "id": "2026-10-06-a1b2c3d4", "action": "created"}。如果它再调一次,拿到的是 action: "updated" 和一句“这是同标题的更新,不是新文件”。如果它手滑传错参数,拿到的是 invalid_argument 加一句“必填参数是 title/angle/outline”。
它依然只是在调用工具。但现在每一次调用都有据可查,做错了说得出为什么,要做危险的事得先过你这一关。
工具从来不是“给模型开的权限”,工具是你替它画好的、可以放心跑的范围。
本系列目录
这是「Agent 工程进阶」系列的第 3 篇。
- 第 0 篇(地图):从 Demo 到可交付:如何做一个 Agent 项目
- 第 1 篇:上下文工程:为什么你的 Agent 越聊越笨
- 第 2 篇:记忆系统:Agent 怎么记住该记的,忘掉该忘的
- 第 3 篇:工具设计深水区:粒度、错误语义、幂等与 MCP(当前篇)
- 第 4 篇:编排与多 Agent:什么时候该拆,什么时候千万别拆
- 第 5 篇:评估体系:怎么知道你的 Agent 变差了
- 第 6 篇:可靠性与成本:什么时候该重试,什么时候该放弃
- 第 7 篇:人机边界:什么时候该问人,什么时候该放心让它做
新手系列入口(偏入门,建议先跑通第一个 Agent):先听懂:AI、LLM、Prompt、Agent、RAG、Tool、Memory 到底是什么
