知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# Agent 工具调用体系设计 > 导读:本文从"Agent 明明该调 A 工具却调了 B、参数还传错、返回结果一大就烧掉半本预算"这三个高频故障出发,把工具三要素与描述写法、工具数量取舍、执行 Pipeline、并行调度、错误分类与降级链、结果裁剪、审计可解释性逐项讲透,最后给出工程实践与踩坑。适合正在做 Agent 工具层、或准备 Agent 系统设计面试的同学。 ## 一、先建立全局认知 ### Q:工具在 Agent 体系里的定位是什么? A:结论先行——工具是 Agent 与外部世界交互的**唯一通道**,所以工具设计的好坏直接决定 **Agent 的能力边界和可靠性**。 这句话可以拆成两个方向理解: - **能力边界**:Agent 能做什么,完全由"你给了它哪些工具"决定。没有工具,再强的模型也只能输出文字。 - **可靠性**:Agent 出错的高频形态不是"模型不会推理",而是"**选错工具、传错参数、误读结果**"——这三件事都属于工具层的设计问题。 所以工具调用体系的核心目标是:**让 Agent 准确选择工具、安全执行工具、优雅处理失败**。 ### Q:工具越多,Agent 能力越强吗? A:结论先行——不是。**工具越多,LLM 的选择负担越大、越容易选错**。 ```text 经验法则: - 3-10 个工具 → LLM 选择准确率最高 - 10-20 个工具 → 准确率下降(需更细致的描述) - 20+ 个工具 → 建议分组或动态注册(按场景只注入相关工具) ``` 这里的取舍有两层代价容易被忽略: 1. **准确率代价**:候选工具一多,相似工具的边界就模糊(`search_news` 和 `search_web` 到底该用哪个?),模型容易选错; 2. **token 代价**:工具定义是**每步都要带进上下文**的固定开销。如果每个工具定义 200~1000 token,20 个工具就是 4000~20000 token——**这既是钱,也是上下文窗口**(具体 token 数取决于描述长度与所用模型的 tokenizer,需实测确认)。 ## 二、工具的定义与注册 ### Q:一个工具需要向 LLM 交代哪三件事? A:结论先行——**name(叫什么)、description(什么时候用它、返回什么)、parameters(每个参数是什么)**。 ```json { "name": "search_financial_report", "description": "搜索上市公司财报数据。用于查询指定公司、指定季度的营收、利润、现金流等财务指标。当用户询问财报相关问题时使用此工具。", "parameters": { "type": "object", "properties": { "company": { "type": "string", "description": "公司名称或股票代码,如 Apple 或 AAPL" }, "quarter": { "type": "string", "enum": ["Q1", "Q2", "Q3", "Q4"], "description": "财报季度" }, "year": { "type": "integer", "description": "财年,如 2024" }, "metrics": { "type": "array", "items": {"type": "string"}, "description": "需要的财务指标列表,可选:revenue, net_profit, gross_margin, operating_cash_flow。默认为全部" } }, "required": ["company", "quarter", "year"] } } ``` 关键点解读:这个 schema 里有三个值得学习的设计手法: 1. **`enum` 约束枚举值**(quarter 只能取 Q1~Q4)——把"不能瞎填"变成 schema 层面的硬约束,比在描述里写"请输入 Q1 到 Q4"可靠得多; 2. **`metrics` 用数组 + 默认值**——给了模型"要么精确指定、要么全都要"两种选择,减少无意义的来回; 3. **`required` 只列真正的必填项**——`metrics` 不在 required 里,这是一个明确的信号:"这个参数可以不给"。 ### Q:description 怎么写才算合格? A:结论先行——**面向 LLM 的理解力写,不面向开发者写**:告诉模型**能力**(能做什么)和**场景**(什么情况下用),而不是**实现**(调什么 API)。 ```text 好的描述: ✅ "搜索指定公司的季度财报数据,返回营收、利润、现金流等指标" → 明确说了"什么时候用"(用户问财报)、"返回什么"(营收/利润/现金流) 不好的描述: ❌ "用于搜索财务信息" → 太模糊,Agent 不知道什么时候该调它 ❌ "调用 /api/v1/search,接收 query、page、size 参数" → 技术细节暴露,LLM 不需要知道 API 路径 ``` 关键点解读:**描述太模糊 → Agent 不会调;描述太宽泛 → Agent 乱调**。所以"合格描述"有一个可检验的标准:**如果两个工具的描述互换后模型仍然分不清该用哪个,那这两个描述都不合格**。这也是"工具粒度"问题(后文反模式)的根因——很多工具区分不开,不是模型笨,而是描述没写出边界。  *图:工具注册质量* ### Q:注册中心应该管哪些元数据? A:结论先行——除"暴露给 LLM 的三要素"外,还要管**安全与行为标记**:是否有副作用、是否需要审批、重试次数、超时、结果缓存 TTL。 ```python @dataclass class ToolDefinition: """工具的元数据定义(暴露给 LLM)""" name: str description: str parameters_schema: dict # 安全与行为标记 is_side_effect: bool = False # 是否有副作用(写操作) requires_approval: bool = False # 是否需要人类审批 max_retries: int = 0 # 失败重试次数 timeout_seconds: int = 30 # 超时时间 cache_ttl_seconds: int = 0 # 结果缓存时间(0=不缓存) class BaseTool(ABC): def __init__(self, definition: ToolDefinition): self.definition = definition @abstractmethod async def execute(self, **kwargs) -> dict: ... def get_openai_schema(self) -> dict: """转换为 OpenAI function calling 的 schema 格式""" return { "type": "function", "function": { "name": self.definition.name, "description": self.definition.description, "parameters": self.definition.parameters_schema, }, } class ToolRegistry: def __init__(self): self._tools: dict[str, BaseTool] = {} def register(self, tool: BaseTool): self._tools[tool.definition.name] = tool def get_all_schemas(self) -> list[dict]: """获取所有工具的 schema,注入给 LLM""" return [t.get_openai_schema() for t in self._tools.values()] def get_tool(self, name: str) -> BaseTool: if name not in self._tools: raise ValueError(f"未知工具: {name}") return self._tools[name] def filter_tools(self, permission_level: str) -> list[dict]: """按权限级别过滤工具(某些工具只对管理员开放)""" ... ``` 关键点解读:把 `is_side_effect` / `requires_approval` / `timeout_seconds` / `cache_ttl_seconds` **放在定义里而不是散落在执行逻辑里**,是"声明式"的关键——执行器扫一遍元数据就知道该怎么调,新增工具时不会漏任何一环。 ### Q:工具太多时怎么办? A:结论先行——三条优化策略:**按场景动态注入、工具嵌套(合并同族)、分层工具(先分类再细化)**。 ```text 优化策略: 1. 按场景动态注入:用户问财报 → 只给财务相关工具(而不是注入全部 50 个) 2. 工具嵌套:search(query, source="financial|news|academic") 而非 search_financial / search_news / search_academic 三个独立工具 3. 分层工具:先进"分类器"工具,再给具体工具 用户先选"我想查资料" → Agent 调 classify_intent() → 返回 domain="finance" → 再注入财务工具 ``` 关键点解读:第 2 条(嵌套)与第 3 条(分层)是两种不同的思路,取舍也不同: - **嵌套**用"参数枚举"替代"工具数量",代价是**单个工具内部逻辑变复杂**(要根据 source 分支),好处是模型只需记住一个工具; - **分层的代价是多一次往返**(先调分类器,再调具体工具),好处是**第一步的候选空间极小、准确率高**。 选哪条取决于业务:来源少且语义统一用嵌套,领域差异大且必须精准路由用分层。 ## 三、工具执行流程 ### Q:标准的执行 Pipeline 有几步? A:结论先行——**7 步**:LLM 生成 tool_call → 参数校验 → 安全检查 → 幂等检查 → 执行 → 结果后处理 → 返回给 LLM。  *图:工具调用处理流水线:校验、安全、幂等、执行、后处理与回填* ```text 1. LLM 生成 tool_call(name + arguments) │ ▼ 2. 参数校验(schema validation) │ 失败 → 返回错误给 LLM,不执行工具 ▼ 3. 安全检查(权限校验、审批流程) │ 未通过 → 拒绝执行或等待人工审批 ▼ 4. 幂等检查(是否为重复调用) │ 是 → 返回缓存结果,跳过执行 ▼ 5. 执行工具 │ ├── 成功 → 6. 结果后处理 │ └── 异常 ──┬── 超时 → 重试 or 返回超时错误 │ ├── 工具错误 → 重试 or 返回错误 │ └── 结果无效 → 返回错误(触发 Agent 换工具) ▼ 6. 结果后处理:裁剪、格式化、缓存 │ ▼ 7. 返回结果给 LLM,继续下一步推理 ``` 关键点解读:**第 2 步(参数校验)的位置非常关键**——它在"安全检查"和"执行"之前。这意味着**参数不合法时根本不会碰到外部系统**,既避免了无效调用,也把一部分注入风险挡在门外(例如 `path` 参数里的路径遍历,在 schema 层就能约束格式)。  *图:工具执行流程* ### Q:参数校验失败后,为什么要"把错误返回给 LLM"而不是直接抛异常? A:结论先行——因为**错误的参数是 Agent 能自己修的问题**;返回结构化错误 + 正确格式,模型下一轮就能自我修正。 ```python async def execute(self, tool_call: dict) -> dict: name = tool_call["name"] arguments = json.loads(tool_call["arguments"]) call_id = tool_call.get("id", generate_id()) tool = self.registry.get_tool(name) start_time = time.time() # Step 1: 参数校验 try: validated_args = validate_arguments(arguments, tool.definition.parameters_schema) except ValidationError as e: return { "tool_call_id": call_id, "error": f"参数校验失败: {e}", "suggestion": f"请检查参数并重试。正确的格式: {tool.definition.parameters_schema}", } # Step 2: 安全检查 if not await self._security_check(tool, validated_args): return {"tool_call_id": call_id, "error": "工具调用被安全策略拒绝"} # Step 3: 幂等检查 if self.cache and tool.definition.cache_ttl_seconds > 0: cached = await self.cache.get(call_id) if cached: return cached # Step 4: 执行(带重试) result = await self._execute_with_retry(tool, validated_args, call_id) # Step 5: 结果后处理 result = self._post_process(tool, result) # Step 6: 指标记录 self.metrics.record(call_id, name, time.time() - start_time, "error" not in result) # Step 7: 缓存 if self.cache and tool.definition.cache_ttl_seconds > 0: await self.cache.set(call_id, result, ttl=tool.definition.cache_ttl_seconds) return {"tool_call_id": call_id, **result} ``` 关键点解读:`suggestion` 字段是这个设计里最值钱的部分——**它把"错在哪"和"该怎么改"一起给了模型**。只返回 `error`,模型往往原地重试同一个错误参数;带上期望格式,重试成功率会显著提升。 ### Q:重试应该怎么设计? A:结论先行——**按工具声明的 `max_retries` 重试,并强制每次执行带 `timeout_seconds` 超时**;重试耗尽后返回错误摘要 + 重试次数。 ```python async def _execute_with_retry(self, tool, args, call_id) -> dict: max_retries = tool.definition.max_retries last_error = None for attempt in range(max_retries + 1): try: result = await asyncio.wait_for( tool.execute(**args), timeout=tool.definition.timeout_seconds, ) return result except asyncio.TimeoutError: last_error = f"工具 {tool.definition.name} 执行超时(>{tool.definition.timeout_seconds}s)" except Exception as e: last_error = f"工具执行异常: {type(e).__name__}: {e}" return {"error": last_error, "retries": max_retries} ``` 关键点解读:两个细节值得注意: 1. **超时封装在重试循环内部**——这样"超时"就变成了一种可重试的错误,而不是让整个 Agent Run 挂住;如果超时在循环外,一次工具卡死就等于整个 Run 卡死; 2. **默认 `max_retries = 0`**——不是所有工具都该重试(写操作重试可能造成重复副作用),所以默认不重试、由工具自己声明,是更安全的默认值。 ## 四、并行工具调用 ### Q:为什么必须支持并行? A:结论先行——因为 Agent 经常要调用多个**互不依赖**的工具,串行会白白累加延迟。  *图:串行两次等待共 4s,并行同时发出仅 2s* ```text 串行(浪费时间): search("营收") → 等待 2s → 拿到结果 → search("利润") → 等待 2s → 拿到结果 → 总耗时 4s 并行(推荐): search("营收") ─┐ ├── 同时发出 → 等待 2s → 拿到两个结果 → 总耗时 2s search("利润") ─┘ ``` 关键点解读:这是"**延迟从 ΣT 变成 max(T)**"的经典优化(与多 Agent 并行分发同源)。但它的前提是**没有依赖**——如果"利润"的查询参数需要"营收"的结果,那就必须串行。 ### Q:怎么判断哪些调用可以并行? A:结论先行——**显式声明依赖最可靠**:让 LLM 在生成 tool_call 时同时输出 `depends_on: [call_id]`;退一步才用"是否引用前一个 call_id"这种启发式推断。 ```python class ParallelToolScheduler: async def execute_batch(self, tool_calls: list[dict]) -> list[dict]: """ 无依赖的调用并行执行;有依赖的调用串行执行 """ groups = self._detect_dependency_groups(tool_calls) all_results = [] for group in groups: # 同一组内无依赖,并行执行 tasks = [self.executor.execute(call) for call in group] results = await asyncio.gather(*tasks, return_exceptions=True) all_results.extend(results) # 下一组可能需要本组的结果作为输入,做结果注入 self._bind_results_to_next_group(group, results, groups) return all_results def _detect_dependency_groups(self, tool_calls: list) -> list[list]: """ 简单策略:如果 tool_call 的参数引用了前一个调用的 call_id,则为依赖 复杂策略(生产推荐):让 LLM 生成 tool_call 时同时输出 depends_on: [call_id] """ # 简化实现:同一个 LLM 响应中的多个 tool_calls 默认无依赖 return [tool_calls] # 全并行 ``` 关键点解读:示例里"同一个 LLM 响应中的多个 tool_calls 默认无依赖"是**一个有风险的默认值**——它假设模型一次吐出的多个调用一定互相独立。但模型完全可能在同一批里同时输出"查数据"和"基于该数据算指标"两个调用(后者依赖前者)。**当模型无法表达依赖时,宁可按串行分批,也不要默认全并行**——因为并行执行顺序不确定,依赖错乱导致的错误比慢一点严重得多。  *图:工具依赖决定串行与并行* ## 五、错误处理与降级 ### Q:工具错误应该怎么分类?为什么分类重要? A:结论先行——分五类:**瞬时错误、参数错误、业务错误、权限错误、工具不可用**;分类的意义在于**告诉 Agent 该怎么回应**,而不是让它盲目重试。 | 错误类型 | 示例 | 是否可重试 | Agent 行为 | |---|---|---|---| | 瞬时错误 | 网络超时、服务限流 | 是 | 等待重试 1-3 次 | | 参数错误 | JSON 格式不正确、枚举值越界 | 否 | 将错误信息返回 LLM,LLM 修正参数后重试 | | 业务错误 | 搜索无结果、文件不存在 | 否 | 将"空结果"返回 LLM,LLM 决定换工具或告知用户 | | 权限错误 | 无权限调用、超出配额 | 否 | 终止该工具调用路径,告知用户 | | 工具不可用 | 服务宕机、API 密钥失效 | 否 | 触发降级策略 | 关键点解读:**"业务错误"这一类的处理方式最容易被做错**。搜索"某个冷门公司财报"返回空结果是**正常业务结果**,不是异常——如果把它当异常抛出,Agent 会陷入"重试 → 还是空 → 再重试"的循环。正确做法是把空结果如实返回,让模型自己决定"换个关键词"或"告诉用户查不到"。 ### Q:降级链怎么设计? A:结论先行——为关键工具配置**按优先级排列的替代工具链**(如 `search_web → search_cache → search_local_kb`),依次尝试直到成功,并在结果里标记降级来源。 ```python class ToolDegradation: """工具降级管理器""" def __init__(self): self.fallback_map = { "search_web": ["search_cache", "search_local_kb"], # 搜索工具不可用 → 先查缓存 → 再查本地知识库 "query_database": ["query_snapshot", "return_cached_report"], # 数据库不可用 → 查只读快照 → 返回最新缓存报告 } def get_fallback_tools(self, failed_tool_name: str) -> list[str]: return self.fallback_map.get(failed_tool_name, []) async def execute_with_fallback(self, tool_call: dict, executor) -> dict: result = await executor.execute(tool_call) if "error" not in result: return result for fallback_name in self.get_fallback_tools(tool_call["name"]): fallback_call = {**tool_call, "name": fallback_name} result = await executor.execute(fallback_call) if "error" not in result: result["_degraded_from"] = tool_call["name"] result["_degraded_to"] = fallback_name return result return result # 全部降级失败,返回原始错误 ``` 关键点解读:**`_degraded_from` / `_degraded_to` 这两个标记必须回传**,有两个原因: 1. **给 Agent 看**:模型知道"我拿到的是缓存而不是实时数据",可以在最终回答里说明数据时效性; 2. **给可观测性看**:降级率是"能力退化"的先行指标(详见可观测性设计),不标记就无法统计。  *图:工具错误降级* ### Q:工具返回超大数据怎么办? A:结论先行——**按工具类型裁剪 + Token 上限截断**;否则会同时踩两个坑:**成本爆炸**和**信息过载导致 LLM 忽略关键信息**。 ```python class ToolResultProcessor: MAX_RESULT_TOKENS = 4000 def process(self, result: dict, tool_name: str) -> dict: # 1. 按工具类型裁剪 if tool_name.startswith("search_"): result = self._trim_search_results(result) elif tool_name.startswith("db_"): result = self._trim_db_results(result) # 2. Token 限制 result_str = json.dumps(result, ensure_ascii=False) if token_count(result_str) > self.MAX_RESULT_TOKENS: result = self._truncate_with_summary(result, self.MAX_RESULT_TOKENS) return result def _trim_search_results(self, result: dict, top_k: int = 5) -> dict: """搜索结果只保留 top-k,并精简每条结果的字段""" if "results" in result: result["results"] = [ {"title": r["title"], "snippet": r.get("snippet", "")[:300], "url": r.get("url", "")} for r in result["results"][:top_k] ] result["_trimmed"] = True result["_total_count"] = len(result.get("_raw_results", [])) return result def _truncate_with_summary(self, result: dict, max_tokens: int) -> dict: """超长结果做摘要压缩""" result_str = json.dumps(result, ensure_ascii=False) if token_count(result_str) > max_tokens: return {"summary": self._summarize(result_str), "_full_result_truncated": True} return result ``` 关键点解读:三个字段的设计意图很清楚—— - `top_k=5` + `snippet[:300]`:**限制条数与单条长度**,这是最主要的降本手段(搜索引擎返回 10 页结果对 Agent 毫无价值); - `_trimmed = True` + `_total_count`:**告诉模型"我被裁剪过"**,避免它误以为"总共就 5 条"; - `_full_result_truncated = True`:**明确标记截断**,让模型在回答里可以声明"完整数据已截断"。**静默截断是最危险的**——模型会基于残缺数据给出看起来完整的结论。 ## 六、可解释性与审计 ### Q:为什么工具调用必须留审计记录? A:结论先行——因为生产排查需要回答"**Agent 在什么时候、为什么、调了什么工具、结果如何**",而工具的完整返回通常太大不能留存,所以要存**摘要 + 推理 + 性能指标**。 ```python @dataclass class ToolCallRecord: run_id: str step: int call_id: str tool_name: str arguments: dict result_summary: str # 结果摘要(不存完整结果,太大) status: str # success / error / timeout / degraded reasoning: str # LLM 给出此调用的 Thought(为什么调这个工具) latency_ms: int token_count: int timestamp: datetime class ToolAuditLogger: def log(self, record: ToolCallRecord): db.insert("tool_call_logs", asdict(record)) if record.status == "error": self.alert(f"工具 {record.tool_name} 在第 {record.step} 步失败: {record.result_summary}") ``` 关键点解读:**`reasoning` 字段(LLM 为什么调这个工具)是这份记录里最有价值、也最容易被省掉的一项**。有了它,才能区分两类完全不同的故障: - "模型想对了但工具错了" → 工具实现问题; - "模型想错了所以调错了" → 工具描述或 prompt 问题。 没有 `reasoning`,这两类故障在日志里长得一模一样。 ## 七、工具层与周边子系统的协作边界 ### Q:工具层和 HITL、安全、Checkpoint、流式分别怎么协作? A:结论先行——**工具层是这些能力的落点**:审批发生在工具执行前、安全校验落在参数上、幂等靠 `tool_call_id`、流式靠 `tool.call` / `tool.result` 事件。 | 协作方 | 挂载点 | 具体形式 | |---|---|---| | HITL 审批 | 工具元数据 `requires_approval` | 审批点固定落在"参数校验通过后、执行之前";拒绝则跳过该工具并带原因回灌给模型 | | 安全护栏 | 工具安全配置 | 路径白/黑名单、域名黑名单(SSRF)、限流、参数长度上限;`is_side_effect` 决定重试策略 | | Checkpoint | `tool_call_id` | 有副作用工具必须用全局唯一 id 做幂等;恢复时先查工具中心的结果,而不是重发 | | 流式交互 | `tool.call` / `tool.result` | 工具执行是体验的"空窗期",必须发 `tool.call` + 计时器 + 周期 progress 占位 | | 可观测性 | 审计记录 + 指标 | `tool_call_logs` 审计表;`success_rate` / `latency_p50` / `fallback_rate` 指标 | 关键点解读:这张表反映了一个重要的架构原则——**工具层不要自己实现审批、安全、幂等、埋点,而是把这些能力挂到工具元数据和固定管道位置上**。因为一旦这些逻辑散落在每个工具的 `execute` 里,新增工具时必然会漏(这正是"安全检查和业务逻辑耦合"被列为反模式的原因)。 另外注意"审批点固定落在参数校验之后"这个顺序:**先校验参数格式、再走审批**。反过来的话,一个人可能被叫去审批一个参数都不合法的调用,纯属浪费人的时间。 ### Q:如果工具来自外部(例如第三方 MCP Server),有什么额外要求? A:结论先行——**外部工具的"描述"和"返回值"都不可信**:描述要当不可信输入审查,返回值要当不可信数据包裹。 1. **描述当不可信输入**:工具描述会进入 prompt,因此它本身就是一个注入面。需要审查描述的来源与内容,并确认工具的元信息(描述、schema)不会以"高优先级指令"的形式出现在用户可见的 prompt 位置上(这与安全设计中"确认 MCP Server 的工具描述不会在用户 prompt 中暴露"的检查项一致); 2. **返回值当不可信数据**:第三方工具返回的网页、文档、邮件正文里可能藏着间接注入,必须经过"外部内容包裹 + 危险模式检查"才能进上下文; 3. **超时与失败行为不可控**:第三方服务可能比你配置的超时更慢、可能返回非约定格式,所以**超时和降级必须由自己一侧强制施加**,不能依赖对方守约。 具体协议字段与能力协商细节需结合 MCP 协议版本确认。核心结论是:**把外部工具当成"不可信边界"对待,而不是当成"我们自己的函数"**。 ### Q:为什么说"工具是 Agent 的 API 契约"?这个视角带来什么好处? A:结论先行——把工具当契约看,就会自然关注三件事:**入参约束、返回结构稳定、错误语义明确**;这三件事恰好也是 Agent 可靠性的三个来源。 - **入参约束(schema)**:约束越明确,模型越不会瞎填;`enum`、类型、必填项都是在替模型排除错误选项; - **返回结构稳定**:模型的"结果解析逻辑"是隐式写在 prompt 和示例里的,一旦结构变了,模型会继续按旧结构理解新数据,最后表现为"总结乱说"; - **错误语义明确**:错误码要能让模型区分"该重试"(瞬时错误)和"该换路"(业务错误),否则它会一直重试一个注定失败的操作。 反过来看一个很典型的线上故障:某个工具今天返回 `{"results": [...]}`,明天改成了 `{"data": [...]}`——**接口方觉得这是个小改动,但对 Agent 来说等于换了一个工具**,因为它此前的理解方式全部失效。所以工具返回结构的变更,应该和"接口不兼容变更"一样走严格流程。这也是"返回结构化结果 + 可读描述"这条建议的深层原因:**契约越自解释,模型越不容易误读。** ## 八、工程实践与踩坑 ### Q:工具设计有哪些反模式? A:结论先行——六条,核心都是"**粒度不对、描述不清、返回值没为 LLM 优化**"。 | 反模式 | 问题 | 改进 | |---|---|---| | 工具粒度太细 | `get_user_name`、`get_user_age`、`get_user_email` 各一个工具 | 合并为 `get_user_profile(fields=["name","age","email"])` | | 工具粒度太粗 | `do_everything(task)` | 拆分为独立功能,LLM 才能做选择 | | 描述缺少"何时用" | "查询数据" | "当用户询问公司营收、利润等财报数据时使用" | | 参数没有默认值 | 所有参数都是 required | 合理设置 optional + default,减少 LLM 瞎填参数 | | 返回裸数据 | `{"rows": [[1,2,3],[4,5,6]]}` | 返回结构化结果 + 可读描述:`{"data": [...], "summary": "共2条记录,营收合计…"}` | | 工具逻辑太重 | 一个工具里做了 5 件事 | Agent 的价值就是组合工具,工具本身应该原子化 | 关键点解读:**"粒度太细"和"粒度太粗"是一对镜像反模式**,判断标准可以这样记—— - 如果两个工具**永远会被一起调用**,说明该合并(太细); - 如果模型调用某个工具时**总是只用到其中一个子功能**,说明该拆分(太粗)。 而"返回裸数据"这条经常被后端同学忽略:**工具的消费者是 LLM,不是程序**。`{"rows": [[1,2,3],[4,5,6]]}` 对程序没问题,但模型要额外做一次"列含义推断";加上 `summary` 字段等于替模型把这步做了,既省 token 又降错误率。 ### Q:落地检查清单有哪些? A:结论先行——十条,覆盖**描述质量、参数完整性、按需注入、超时、幂等、错误分类、降级、结果裁剪、审计**。 ```text 1. ✅ 每个工具有清晰的 name + description + 场景说明 2. ✅ 参数 schema 完整,有类型 + 枚举值 + 描述 + 默认值 3. ✅ 按场景动态注册工具,不用把所有工具都注入给 LLM 4. ✅ 工具执行有超时控制(timeout_seconds) 5. ✅ 副作用工具标记 is_side_effect=true,审批流程不会遗漏 6. ✅ 每次工具调用分配全局唯一 tool_call_id,支持幂等 7. ✅ 工具异常有分类(瞬时/参数/业务/权限),Agent 知道该怎么回应 8. ✅ 关键工具有降级链(A 挂了走 B) 9. ✅ 工具结果有裁剪/摘要,杜绝塞巨量数据给 LLM 10. ✅ 每次工具调用有审计日志(谁、什么时候、什么结果) ``` ### Q:除了这份清单,还有哪些实战经验值得补? A:结论先行——四条补充:**工具描述要做"对抗测试"、超时要按工具分级、缓存要按工具区分、以及副作用工具的重试要格外小心**。 1. **描述要做对抗测试。** 把所有工具描述摆在一起,用"最容易混淆的几个场景"测一遍模型是否选对;如果选错,先改描述而不是改 prompt。 2. **超时按工具分级。** 搜索类 10~30 秒合理,本地计算 1~5 秒合理;如果全局统一 30 秒,一个卡死的本地计算会白等 30 秒。 3. **缓存要按工具区分。** 只对"幂等且结果时效性要求不高"的查询类工具开缓存(`cache_ttl_seconds > 0`);写操作绝不能靠缓存"省事",它本身就是幂等风险的来源。 4. **副作用工具的重试要格外小心。** 这类工具应该遵循"**要么不重试,要么靠 `tool_call_id` 幂等**"的原则——否则一次超时重试可能变成两次扣款。 ### Q:这套工具体系里,哪三个设计最体现"取舍"? A:结论先行——**工具数量(准确率 vs 能力)、并行调度(延迟 vs 依赖正确性)、结果裁剪(成本 vs 信息完整)**。 - **工具数量**:多给工具能扩展能力,但会降低选择准确率、增加每步 token 开销;解法是动态注入 + 嵌套 + 分层,代价是架构复杂度; - **并行调度**:并行能把延迟从 ΣT 降到 max(T),但在依赖关系无法被模型准确表达时会引入顺序错误;解法是**优先显式声明依赖,无法声明时保守串行**; - **结果裁剪**:裁剪能控制成本与信息噪声,但会丢失信息;解法是"裁剪 + 显式标记被裁剪"(`_trimmed` / `_total_count` / `_full_result_truncated`),把"信息不完整"这件事告诉模型而不是瞒着它。 ## 小结 - 工具是 Agent 与外部世界交互的唯一通道,**工具设计直接决定能力边界与可靠性**; - 工具三要素是 name / description / parameters,其中 **description 要面向 LLM 写"能力 + 场景",而不是写实现细节**; - 工具不是越多越好:**3~10 个选择准确率最高**,20+ 需要动态注册、嵌套或分层; - 注册元数据要包含副作用标记、审批要求、重试次数、超时、缓存 TTL——**声明式优于散落式**; - 执行走 7 步 Pipeline,其中**参数校验在安全检查和执行之前**,失败时返回错误 + 期望格式(`suggestion`)让模型自我修正; - 无依赖的调用应并行(延迟从 ΣT → max(T)),但**依赖判断要以显式声明为准,不确定时保守串行**; - 错误分五类(瞬时/参数/业务/权限/工具不可用),其中"业务错误"应如实返回而非重试;关键工具配降级链并标记 `_degraded_from/to`; - 大结果要**裁剪 + 标记**(top_k、snippet 截断、token 上限、`_trimmed`、`_total_count`),静默截断最危险; - 审计记录里 **`reasoning`(为什么调这个工具)** 是定位"想错 vs 调错"的关键字段。 ## 思考题 1. 你有 3 个工具:`search_financial`、`search_news`、`search_academic`。你会合并成一个 `search(source=...)` 还是保留三个?请从"选择准确率"和"工具实现复杂度"两个角度论证,并说明边界情况(例如三个来源的返回结构完全不同)该怎么处理。 2. 示例里"同一批 tool_calls 默认无依赖、全并行"是个有风险的默认值。你会怎么在不增加模型输出负担的前提下,降低依赖错乱的概率? 3. 一个写型工具(如 `create_order`)被配置了 `max_retries=2`,执行超时后重试,结果用户看到两笔订单。除了"改配置为不重试",你还会在工具层加什么防护? 4. `MAX_RESULT_TOKENS = 4000` 是全局值,但"搜索摘要"和"数据库行"的合理上限显然不同。你会怎么设计一个既能按工具差异化、又不让配置爆炸的方案? 5. 如果产品要求"工具调用必须可解释给终端用户看"(例如展示"我调用了搜索工具,因为需要最新数据"),`reasoning` 字段会带来哪些新的工程要求(提示:与安全、隐私、流式提示的关系)?
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入