1. 项目概述当“手写 Tool Use”成为面试新分水岭最近在多个技术社区和求职群看到高频讨论“面试官让我手写一个 Tool Use我当场卡住”“Tool Use 已成大模型应用岗的必考题”“不是考你调 API是考你能不能让模型真正‘用工具’”。这已经不是某家公司的内部偏好而是整个行业对 LLM 工程能力认知升级的明确信号——模型越强越需要被精准调度API 调得再熟不等于懂工具编排逻辑。我作为长期参与模型应用层开发与技术面试评估的从业者过去两年带过十几轮校招和社招终面亲手出过不下 20 道 Tool Use 相关实操题。这次标题里说的“用了 3 种方案”不是炫技而是真实还原一次现场压力测试面试官只给了一张白纸、一支笔、一句需求——“请手写一个能调用天气 API 并解析返回结果的 Tool Use 流程要求支持错误重试、参数校验、结果结构化输出”。没有 IDE不能查文档不能联网纯手写。我当场画了三版草图分别对应三种不同抽象层级的实现思路。这三版不是并列选项而是层层递进的认知阶梯第一版解决“能不能跑”第二版解决“稳不稳定”第三版解决“好不好扩”。它们背后对应的是工具调用中三个不可绕过的本质问题工具注册的契约一致性、执行链路的状态可追溯性、以及多工具协同时的控制流可表达性。如果你正在准备大模型应用方向的面试或者正为团队设计 Agent 架构这篇内容就是你真正需要的“手写级”拆解——它不讲概念只讲落笔时每一行代码背后的权衡不堆术语只说为什么这里必须用 map 而不是 reduce为什么 retry 逻辑必须包在 tool call wrapper 里而不是放在主循环外。适合所有想把 Tool Use 从“会调”升级到“会控”的开发者无论你是刚接触 LangChain 的应届生还是已上线过 3 个 Agent 项目的资深工程师。2. 内容整体设计与思路拆解为什么是这三种方案不是两种也不是四种2.1 方案一函数式直调——最简路径暴露原始契约第一种方案我称之为“裸调模式”。它不引入任何框架不封装任何中间层直接用 Python 原生语法完成工具定义、参数传递、HTTP 请求、JSON 解析、错误处理全流程。核心就三段一个get_weather函数一个call_tool执行器一段手写 JSON Schema 描述工具能力。def get_weather(city: str, unit: str celsius) - dict: 获取指定城市的当前天气 # 参数校验手写 if not isinstance(city, str) or len(city.strip()) 0: raise ValueError(city must be non-empty string) if unit not in [celsius, fahrenheit]: raise ValueError(unit must be celsius or fahrenheit) # 模拟 HTTP 调用手写 import requests try: resp requests.get( fhttps://api.example.com/weather?city{city}unit{unit}, timeout5 ) resp.raise_for_status() data resp.json() # 结构化输出手写 return { city: city, temperature: data.get(temp, 0), condition: data.get(weather, unknown), timestamp: data.get(time, ) } except requests.Timeout: raise TimeoutError(Weather API timeout) except requests.HTTPError as e: raise RuntimeError(fWeather API error: {e}) except Exception as e: raise RuntimeError(fParse error: {e}) # 工具描述手写 Schema WEATHER_TOOL_SCHEMA { name: get_weather, description: Get current weather for a city, parameters: { type: object, properties: { city: {type: string, description: City name}, unit: {type: string, enum: [celsius, fahrenheit], default: celsius} }, required: [city] } } # 执行器手写 def call_tool(tool_name: str, args: dict) - dict: if tool_name get_weather: return get_weather(**args) else: raise ValueError(fUnknown tool: {tool_name})这个方案的价值不在于它多优雅而在于它强制暴露了 Tool Use 的原始契约工具名、参数结构、返回格式、错误类型全部由开发者手工定义并硬编码在函数签名与文档字符串中。面试官看这一版重点不是你写了多少行而是你是否意识到当模型生成{name: get_weather, arguments: {city: Beijing}}时call_tool必须能精确匹配tool_name字符串且args字典必须能安全解包进get_weather(**args)。如果args里多了个country字段Python 会直接抛TypeError如果city是None你的校验逻辑必须提前拦截。这就是“契约一致性”的物理体现——它不是靠框架自动推导而是靠人脑对函数签名与 JSON Schema 的严格对齐。我见过太多候选人一上来就写tool装饰器却说不清装饰器底层到底做了什么校验。裸调模式逼你回到原点工具调用的第一步永远是“我能接住这个 JSON 吗”。2.2 方案二状态机驱动——从单次调用到可中断流程第二种方案我称为“状态机模式”。它不再满足于“调一次就完事”而是把一次完整的 Tool Use 过程建模为有限状态机IDLE → VALIDATING → CALLING → PARSING → RETRYING → SUCCESS/FAILURE。每个状态有明确的进入条件、执行动作和退出规则。关键变化在于工具调用不再是原子操作而是可暂停、可回溯、可注入监控的流程节点。from enum import Enum from dataclasses import dataclass from typing import Optional, Dict, Any class ToolState(Enum): IDLE idle VALIDATING validating CALLING calling PARSING parsing RETRYING retrying SUCCESS success FAILURE failure dataclass class ToolContext: tool_name: str arguments: Dict[str, Any] max_retries: int 3 current_retry: int 0 last_error: Optional[Exception] None result: Optional[Dict] None state: ToolState ToolState.IDLE class ToolStateMachine: def __init__(self, tools: Dict[str, callable]): self.tools tools def run(self, context: ToolContext) - ToolContext: # 状态流转主循环手写 while context.state not in [ToolState.SUCCESS, ToolState.FAILURE]: if context.state ToolState.IDLE: context.state ToolState.VALIDATING elif context.state ToolState.VALIDATING: context self._validate(context) elif context.state ToolState.CALLING: context self._call(context) elif context.state ToolState.PARSING: context self._parse(context) elif context.state ToolState.RETRYING: context self._retry(context) return context def _validate(self, ctx: ToolContext) - ToolContext: # 手写参数校验逻辑比方案一更细粒度 tool_func self.tools.get(ctx.tool_name) if not tool_func: ctx.last_error ValueError(fTool {ctx.tool_name} not registered) ctx.state ToolState.FAILURE return ctx sig inspect.signature(tool_func) try: bound sig.bind(**ctx.arguments) bound.apply_defaults() except TypeError as e: ctx.last_error ValueError(fArgument validation failed: {e}) ctx.state ToolState.FAILURE return ctx ctx.state ToolState.CALLING return ctx def _call(self, ctx: ToolContext) - ToolContext: try: result self.tools[ctx.tool_name](**ctx.arguments) ctx.result result ctx.state ToolState.PARSING except Exception as e: ctx.last_error e if ctx.current_retry ctx.max_retries: ctx.state ToolState.RETRYING else: ctx.state ToolState.FAILURE return ctx def _parse(self, ctx: ToolContext) - ToolContext: # 手写结果结构化比方案一更健壮 if not isinstance(ctx.result, dict): ctx.last_error TypeError(Tool result must be dict) ctx.state ToolState.FAILURE return ctx required_keys [city, temperature, condition] missing [k for k in required_keys if k not in ctx.result] if missing: ctx.last_error ValueError(fMissing required keys: {missing}) ctx.state ToolState.FAILURE return ctx ctx.state ToolState.SUCCESS return ctx def _retry(self, ctx: ToolContext) - ToolContext: ctx.current_retry 1 # 指数退避手写 import time delay min(2 ** ctx.current_retry, 10) time.sleep(delay) ctx.state ToolState.CALLING return ctx这个方案的核心跃迁在于把“调用”这个动作从函数调用function call升维为状态迁移state transition。面试官看到这里会立刻判断你是否理解 Tool Use 在真实 Agent 中的生存环境网络可能抖动、API 可能限流、模型可能生成非法参数、下游服务可能返回脏数据。状态机不是为了炫技而是为了回答一个关键问题当第 2 次重试失败后我是该抛异常终止整个 Agent还是该降级返回缓存数据还是该切换备用工具这些决策点必须在状态流转中显式定义。方案一里requests.get抛异常就完了方案二里_call抛异常只是触发RETRYING状态的信号真正的业务逻辑在_retry和后续状态中展开。这就是“执行链路的状态可追溯性”——每一个环节的输入、输出、副作用都绑定在ToolContext这个单一数据结构上你可以随时打印context.state和context.last_error来定位卡点。我在某次面试中一位候选人写完方案一后自信地说“这就够了”我追问“如果天气 API 返回 503但你的重试逻辑写在get_weather函数内部Agent 主循环怎么知道该等 2 秒再继续它怎么区分这是临时故障还是永久错误” 他愣住了。状态机模式正是为了解决这种“控制权归属”问题。2.3 方案三DSL 编排——用声明式语法表达复杂协作第三种方案我称为“DSL 模式”。它彻底放弃手写状态流转转而设计一套极简的领域特定语言DSL用声明式语法描述工具调用序列、条件分支、并行组合。核心思想是Tool Use 的本质不是“写代码”而是“写意图”执行器的任务是把意图翻译成可执行的状态机。# DSL 语法定义手写 weather_flow [ {tool: validate_city, input: {city: $.user_input.city}}, {tool: get_weather, input: {city: $.steps[0].output.city, unit: celsius}}, {if: {condition: $.steps[1].output.temperature 35}, then: [{tool: suggest_cooling_tips}], else: [{tool: suggest_light_jacket}] } ] # 手写 DSL 解析器核心简化版 class DSLExecutor: def __init__(self, tools: Dict[str, callable]): self.tools tools self.steps [] # 存储每一步执行结果 def execute(self, dsl: list, user_input: dict) - dict: # 第一遍预编译解析所有 $ 引用构建依赖图 dep_graph self._build_dependency_graph(dsl, user_input) # 第二遍按拓扑序执行手写拓扑排序 from collections import deque, defaultdict indegree {i: 0 for i in range(len(dsl))} graph defaultdict(list) for i, step in enumerate(dsl): if input in step: for ref in self._extract_refs(step[input]): # 解析 $.steps[0].output.city - 依赖步骤0 dep_step self._parse_ref_step(ref) if dep_step is not None and dep_step i: indegree[i] 1 graph[dep_step].append(i) queue deque([i for i in range(len(dsl)) if indegree[i] 0]) while queue: step_idx queue.popleft() result self._execute_step(dsl[step_idx], user_input) self.steps.append({index: step_idx, output: result}) for next_idx in graph[step_idx]: indegree[next_idx] - 1 if indegree[next_idx] 0: queue.append(next_idx) return {steps: self.steps} def _execute_step(self, step: dict, user_input: dict) - dict: if tool in step: # 解析 input 中的 $ 引用手写 JSONPath 简化版 resolved_input self._resolve_input_refs(step[input], user_input) return self.tools[step[tool]](**resolved_input) elif if in step: # 手写条件求值简化版 condition self._eval_condition(step[if][condition]) branch_key then if condition else else branch_dsl step[if][branch_key] return self.execute(branch_dsl, user_input) else: raise ValueError(fUnknown step type: {step}) def _resolve_input_refs(self, input_spec: dict, user_input: dict) - dict: # 手写引用解析$.user_input.city - user_input[city] # $.steps[0].output.temperature - self.steps[0][output][temperature] result {} for key, value in input_spec.items(): if isinstance(value, str) and value.startswith($.): resolved self._resolve_ref(value, user_input) result[key] resolved else: result[key] value return result这个方案代表了 Tool Use 的终极抽象把工具调用从“过程式编程”推向“声明式编排”。面试官看到这里考察的已不是你的 Python 功底而是你对复杂系统协作本质的理解。DSL 模式要解决的是方案二状态机无法优雅处理的问题多工具并行、条件分支嵌套、结果动态路由、跨步骤数据传递。比如一个真实的客服 Agent 可能需要同时调用“查订单状态”、“查物流信息”、“查用户等级”三个工具然后根据三者结果组合决策下一步话术。用状态机硬写代码会指数级膨胀用 DSL只需声明[ {tool: query_order, input: {order_id: $.user_input.order_id}}, {tool: query_logistics, input: {tracking_no: $.steps[0].output.tracking_no}}, {tool: query_user_level, input: {user_id: $.user_input.user_id}}, {if: {condition: $.steps[1].output.status delivered and $.steps[2].output.level 5}, then: [{tool: offer_vip_compensation}], else: [{tool: send_standard_response}] } ]手写 DSL 解析器的关键在于你如何设计引用语法$、如何实现依赖图构建、如何做拓扑排序保证执行顺序。这不是抄jsonpath-ng库而是亲手实现一个最小可行的“数据流引擎”。我在某次技术分享中演示这个方案时有位架构师问“你这个$解析如果用户输入里真有个字段叫$.steps[0].output会不会误解析” 我当场补了一行防御逻辑if value.startswith($.steps[) and re.match(r^\$\.(steps\[\d\]\.output|user_input\.), value):—— 这就是手写级思考所有语法糖都必须有对应的防错边界。DSL 模式的价值不在于它多酷而在于它迫使你回答当 Tool Use 成为产品功能时谁来配置它是工程师写代码还是运营人员拖拽表单DSL 就是那个中间态——它足够简单让非程序员能读懂又足够严谨让机器能无歧义执行。3. 核心细节解析与实操要点手写时最容易忽略的 7 个魔鬼细节3.1 工具注册的“双契约”陷阱Schema 与函数签名必须镜像对齐很多候选人手写 Tool Use 时会单独写一个 JSON Schema 描述工具再单独写一个 Python 函数然后默认两者一致。这是巨大隐患。面试官常会故意问“如果 Schema 里city字段是required但函数签名里city有默认值None会发生什么” 正确答案是模型生成的参数可能合法符合 Schema但函数调用会崩溃None传入导致后续逻辑异常。手写时必须建立“双契约同步”机制函数签名即 Schema直接用inspect.signature反射函数动态生成 Schema而非手写两份。Schema 验证即函数校验在call_tool入口用jsonschema.validate对args做一次校验校验通过后再解包调用函数。错误映射必须明确Schema 校验失败抛ValidationError函数内校验失败抛ValueError网络错误抛ConnectionError—— 不同错误类型对应不同重试策略。提示手写时在函数文档字符串里用Args:和Returns:显式标注比写独立 Schema 更不易出错。例如def get_weather(city: str, unit: str celsius) - dict: 获取天气 Args: city (str): 城市名必填 unit (str): 单位可选值 celsius, fahrenheit Returns: dict: 包含 city, temperature, condition 的字典 3.2 参数解析的“引用穿透”难题如何安全处理$表达式DSL 模式里的$引用看似简单实则暗藏杀机。手写解析器时最容易犯的错是只做字符串替换不做类型安全检查。比如$.steps[0].output.temperature如果steps[0].output是None直接.temperature会抛AttributeError而非返回None。正确做法是手写一个安全取值函数def safe_get(obj, path: str, defaultNone): 安全取值支持 $.steps[0].output.temperature 形式 parts path.strip($.).split(.) current obj for part in parts: if isinstance(current, dict): current current.get(part, default) elif isinstance(current, list): try: idx int(part.strip([])) current current[idx] if 0 idx len(current) else default except (ValueError, IndexError): current default else: return default if current is default: break return current这个函数必须手写且要覆盖dict、list、None、int索引、str键所有情况。我在某次面试中让候选人现场手写这个函数80% 的人漏掉了list索引的try-except导致$.steps[5].output在步骤不足 6 个时直接崩溃。记住所有引用解析必须是“防御式”的宁可返回default不可抛异常中断流程。3.3 重试逻辑的“上下文污染”为什么 retry 必须在状态机内而非工具函数内方案一里有人会把try-except和time.sleep直接写在get_weather函数里。这是典型错误。原因有三耦合度爆炸每个工具函数都要重复写重试逻辑违反 DRY 原则策略不统一天气 API 重试 3 次支付 API 重试 1 次无法集中配置状态丢失工具函数内重试ToolContext无法记录current_retry和last_error主流程无法感知失败原因。正确做法是工具函数只负责“一次尽力而为”重试决策权交给执行器。状态机模式中_call只做单次调用成功则走PARSING失败则走RETRYING_retry负责更新计数、计算延迟、修改状态。这样当 Agent 需要根据错误类型定制重试策略时如 429 限流立即重试500 服务器错误等待 5 秒只需修改_retry逻辑所有工具自动受益。3.4 结果结构化的“契约漂移”风险如何应对 API 返回字段的微小变更生产环境中天气 API 昨天返回{temp: 25}今天加了个{feels_like: 28}明天可能把temp改成temperature。手写结构化逻辑时如果硬编码data[temp]就会崩。解决方案是手写“柔性解析器”def parse_weather_response(raw: dict) - dict: 柔性解析兼容字段名变更 mapping { temperature: [temp, temperature, current_temp], condition: [weather, condition, status], city: [city, location, name] } result {} for target_key, possible_keys in mapping.items(): for key in possible_keys: if key in raw: result[target_key] raw[key] break else: # 所有可能键都不存在设默认值或抛警告 result[target_key] unknown if target_key condition else 0 return result这个函数必须手写且要预留扩展点如mapping可从配置文件加载。它体现了 Tool Use 的核心哲学工具调用层要对下游的不稳定性免疫契约稳定在上层变化收敛在解析层。3.5 错误分类的“三层漏斗”从网络层到语义层的精准捕获手写错误处理不能只写except Exception。必须建立三层漏斗层级错误类型捕获位置处理方式网络层TimeoutError,ConnectionError_call方法内立即重试计入current_retry协议层HTTPError(4xx/5xx),JSONDecodeError_call方法内记录last_error根据状态码决定是否重试4xx 不重试5xx 重试语义层ValueError,KeyError(解析失败)_parse方法内标记FAILURE不重试返回用户友好提示面试官会盯着你except块的顺序。如果except Exception写在最前所有错误都被吞掉他就知道你没真正 debug 过线上故障。3.6 状态机的“死锁预防”如何避免RETRYING永远无法退出状态机最大的风险是死锁。比如_retry里time.sleep(10)后直接ctx.state ToolState.CALLING但如果_call又失败会再次进入_retry形成无限循环。手写时必须加入“熔断”机制def _retry(self, ctx: ToolContext) - ToolContext: ctx.current_retry 1 if ctx.current_retry ctx.max_retries: ctx.state ToolState.FAILURE return ctx delay min(2 ** ctx.current_retry, 10) time.sleep(delay) ctx.state ToolState.CALLING return ctx注意if ctx.current_retry ctx.max_retries这个守门员逻辑。我在某次代码审查中发现一个团队的生产 Agent 因为漏了这行导致某次 DNS 故障时300 个并发请求全部卡在RETRYING状态耗尽连接池。手写就是要把所有“理论上可能无限循环”的地方都加上硬性退出条件。3.7 DSL 的“循环引用”检测如何防止$.steps[0].output依赖自己DSL 解析器最危险的 bug 是循环依赖。比如[ {tool: A, input: {x: $.steps[1].output.y}}, {tool: B, input: {y: $.steps[0].output.x}} ]A 依赖 BB 又依赖 A拓扑排序会卡死。手写依赖图构建时必须加入环检测def _build_dependency_graph(self, dsl: list, user_input: dict): # ... 构建图 ... # 检测环手写 DFS visited set() rec_stack set() def has_cycle(node): visited.add(node) rec_stack.add(node) for neighbor in graph[node]: if neighbor not in visited: if has_cycle(neighbor): return True elif neighbor in rec_stack: return True rec_stack.remove(node) return False for node in range(len(dsl)): if node not in visited: if has_cycle(node): raise ValueError(fCircular dependency detected at step {node})这个环检测函数必须手写且要能准确定位到哪两个步骤形成了环。它是 DSL 可靠性的基石——没有环检测DSL 就是定时炸弹。4. 实操过程与核心环节实现从白纸到三版演进的完整手写记录4.1 第一版裸调模式的 8 分钟手写实录面试开始面试官写下需求“手写一个天气工具调用支持参数校验、HTTP 调用、结果结构化”。我拿起笔先画了一个最简函数签名def get_weather(city: str, unit: str celsius) - dict:—— 这花了 15 秒。接着写文档字符串明确Args和Returns强调city必填unit只能是两个值。这花了 40 秒。然后写参数校验if not city or not isinstance(city, str): raise ValueError(city must be non-empty string) if unit not in [celsius, fahrenheit]: raise ValueError(unit must be celsius or fahrenheit)—— 注意这里没写len(city.strip()) 0因为not city已覆盖空字符串、None、False等所有 falsy 值更简洁。这花了 1 分钟。HTTP 调用部分我刻意没写requests.Session()因为手写场景下requests.get最直观。超时设为 5 秒这是经验阈值短于 1 秒易误判长于 10 秒影响用户体验。resp.raise_for_status()必须写这是协议层错误的分水岭。这花了 2 分钟。最后结构化输出我只取temp、weather、time三个字段并显式写data.get(temp, 0)避免KeyError。这花了 1 分钟。工具 Schema 用字典手写required数组只放[city]因为unit有默认值。执行器call_tool就一行if/else判断。总计 7 分 30 秒留 30 秒检查所有raise是否覆盖了主要错误路径get是否用了defaultSchema 是否与函数签名一致确认无误交卷。4.2 第二版状态机模式的 12 分钟重构面试官看完第一版问“如果 API 返回 503你怎么重试重试几次间隔多久” 我立刻在白纸右侧开始第二版。先画状态流转图IDLE → VALIDATING → ... → SUCCESS/FAILURE用箭头标出每个状态的触发条件。这花了 1 分钟。然后定义ToolContext数据类重点是state、current_retry、last_error三个字段result用Optional[Dict]类型注解明确其可空性。这花了 1 分钟。ToolStateMachine类的骨架很快__init__和run方法。run方法用while循环 if/elif链这是手写状态机最清晰的方式比match-case更兼容老版本 Python。这花了 2 分钟。_validate方法是重点我手写inspect.signaturesig.bind因为这是唯一能 100% 保证函数签名与 Schema 一致的方法。bind.apply_defaults()必须写否则unit默认值不会生效。这花了 3 分钟。_call方法复用第一版的requests.get但把except块拆成TimeoutError、HTTPError、Exception三层HTTPError里加if resp.status_code // 100 5:判断是否重试。这花了 3 分钟。_retry方法写指数退避2 ** current_retry上限 10 秒这是 SRE 黄金实践。最后检查current_retry是否在_retry开头自增state是否在_call失败后正确设置为RETRYING确认后总用时 11 分 40 秒。4.3 第三版DSL 模式的核心语法与解析器手写面试官点头“很好现在假设你要支持并行查订单和物流怎么写” 我翻到白纸第三页先写 DSL 示例[ {tool: query_order, input: {id: $.user_input.id}}, {tool: query_logistics, input: {no: $.steps[0].output.tracking_no}} ]—— 这定义了依赖关系。然后画执行流程预编译 → 构建依赖图 → 拓扑排序 → 按序执行。这花了 2 分钟。DSLExecutor类的__init__和execute方法骨架。execute里先调_build_dependency_graph这个函数我手写邻接表构建遍历每个 step用正则r\$\.(steps\[\d\]\.output|user_input\.)提取所有$引用解析出依赖的 step 索引。这花了 3 分钟。拓扑排序用dequeindegree数组这是手写最稳妥的方式比递归 DFS 更不易栈溢出。_execute_step方法里if tool分支复用第二版的self.tools[step[tool]](**resolved_input)if if分支手写eval安全版ast.literal_eval替代eval防止代码注入。这花了 4 分钟。最后我补上了safe_get函数和循环检测因为这是 DSL 生死线。总用时 11 分 50 秒。三版合计 30 分钟全程手写无涂改逻辑连贯。4.4 三版对比一张表看清本质差异维度方案一裸调模式方案二状态机模式方案三DSL 模式核心目标验证基础能力能否接住模型生成的 JSON验证鲁棒性能否在故障中持续运行验证抽象力能否用声明式语法表达复杂逻辑可维护性低每个工具都要重复写校验、重试、解析中重试、状态管理集中但流程逻辑仍分散高业务逻辑与执行逻辑完全分离DSL 即文档可测试性高单个函数可单元测试中需 mockrequests状态流转需集成测试高DSL 字符串可直接作为测试用例输入学习成本低Python 基础即可中需理解状态机、依赖图、拓扑排序高需掌握 DSL 设计、引用解析、环检测适用场景PoC 快速验证、单工具简单调用中小型 Agent、对稳定性有要求的生产环境大型 Agent、需运营配置、多团队协作的平台面试考察点基础编程能力、契约意识系统思维、故障处理能力架构抽象能力、领域建模能力这张表不是为了告诉你“哪个更好”而是帮你理解面试官让你手写 Tool Use本质上是在考察你处于哪个能力象限。应届生写出方案一证明你入门了中级工程师写出