1. 这不是写个函数那么简单Tool Use 在面试现场的真实分量“面试官让我手写一个 Tool Use”——这句话最近在多个技术社区高频出现背后藏着的不是一道算法题而是一次对工程直觉、系统思维和真实落地能力的综合压力测试。我带过不少准备大厂后端/智能体方向面试的开发者几乎所有人都低估了“手写 Tool Use”这五个字的重量。它不考你背没背过 OpenAI 的 function calling 文档而是看你能不能在白板或终端前三分钟内画出工具调用的边界、定义清晰的输入契约、处理真实的失败路径并让整个流程可调试、可扩展、可解释。关键词里反复出现的“3 种方案”恰恰暴露了面试官的深层意图他要的不是标准答案而是你面对同一问题时如何在抽象层级、执行粒度、错误韧性三个维度上做权衡取舍。比如有人一上来就堆 JSON Schema结果连参数校验都漏掉类型转换有人执着于用装饰器封装却在多工具串行时陷入回调地狱还有人直接抄 LangChain 的 Tool 接口但完全说不清return_direct和handle_tool_error的触发时机。这不是考框架熟练度是考你脑子里有没有一套“工具即服务”的建模本能。适合谁看如果你正卡在 LLM 应用开发的临门一脚写 prompt 很溜但一加 tool 就崩如果你在设计 Agent 系统时总在“该不该把数据库操作封装成 tool”上犹豫或者你刚被问到“如果这个 tool 超时了你是重试、降级还是报错给用户”却答得含糊——那这篇就是为你写的。它不讲虚的架构图只拆解我在真实模拟面试中用三种截然不同的方式手写 Tool Use 的全过程从最简原型到生产就绪每一步为什么这么选、踩过什么坑、参数怎么定全摊开给你看。2. 方案一极简契约型——用纯 Python 函数 类型注解打底2.1 为什么先从“裸函数”开始很多人一听到 Tool Use 就想上 class、上 registry、上异步但我在实际面试中发现80% 的候选人连最基础的输入输出契约都定义不清。方案一的核心思想是先砍掉所有框架依赖用 Python 原生能力把“工具是什么”这件事钉死。它的价值不在于功能多强而在于强制你回答三个问题这个工具的唯一职责是什么它的合法输入范围有哪些它的失败表现形式该怎么暴露比如面试官让你实现一个“查天气”的 tool你绝不能写def get_weather(city)就完事。城市名为空、城市名拼错、API 返回 404、网络超时——这些都不是“意外”而是契约的一部分。所以方案一的第一步永远是定义类型from typing import Optional, Dict, Any from dataclasses import dataclass dataclass class WeatherResult: city: str temperature_c: float condition: str humidity_percent: int dataclass class ToolError: code: str # INVALID_INPUT, NETWORK_ERROR, RATE_LIMIT message: str retryable: bool False看到这里你可能觉得啰嗦但这就是关键。我见过太多人把错误直接 print 出来或者用raise Exception(xxx)结果在 Agent 编排层根本无法区分“用户输错城市”和“服务暂时不可用”。用ToolError数据类等于提前把错误分类、可重试性、用户提示语都固化下来。这不是炫技是让后续所有逻辑有据可依。2.2 实现细节参数校验与防御式编程接下来是函数本体。注意这里不用任何外部库连 requests 都不引入面试时可能禁网用urllib或直接 mock 返回值def get_weather(city: str) - Dict[str, Any]: # 第一层校验空值、长度、非法字符 if not isinstance(city, str) or not city.strip(): return ToolError( codeINVALID_INPUT, message城市名不能为空请输入有效的中文或英文城市名, retryableFalse ).__dict__ city city.strip() if len(city) 50: return ToolError( codeINVALID_INPUT, message城市名过长请输入50个字符以内的城市名, retryableFalse ).__dict__ # 第二层校验常见无效输入面试官最爱问这个 if city.lower() in [unknown, null, undefined, 123]: return ToolError( codeINVALID_INPUT, messagef‘{city}’不是有效城市名请确认后重试, retryableFalse ).__dict__ # 模拟 API 调用真实场景替换为 requests.get try: # 这里可以 mock 一个固定返回比如北京25°C晴湿度45% return WeatherResult( citycity, temperature_c25.0, conditionSunny, humidity_percent45 ).__dict__ except TimeoutError: return ToolError( codeNETWORK_ERROR, message查询天气信息时网络超时请稍后重试, retryableTrue ).__dict__ except Exception as e: return ToolError( codeUNKNOWN_ERROR, messagef查询天气时发生未知错误{str(e)}, retryableFalse ).__dict__重点来了为什么所有返回都是Dict[str, Any]因为这是 LLM 解析 tool call 的事实标准。OpenAI、Anthropic、Ollama 的 tool calling 协议都要求最终输出是 JSON-serializable 的 dict。你返回 dataclass 实例LLM 解析器会懵你返回 tuple它更懵。所以.__dict__是必须的。另外retryableTrue的设定不是拍脑袋——网络超时大概率能重试但用户输错城市重试十次也没用。这个判断直接影响 Agent 的决策逻辑必须在 tool 层就明确。2.3 面试现场实操心得如何让面试官眼前一亮在白板上写这段代码时我建议你边写边说三句话“我把输入校验拆成两层第一层是类型和空值第二层是业务语义比如过滤掉‘unknown’这种明显无效值这样既防 crash又提升用户体验。”“所有错误都走ToolError统一出口而不是 raise 异常因为 Agent 需要结构化错误码来决定下一步动作比如重试或换工具。”“返回强制 dict是为了和 LLM 的 tool calling 协议对齐避免解析失败——这点很多候选人忽略但恰恰是工程落地的关键。”这三句话比你多写十个装饰器更有说服力。方案一的价值就是用最朴素的代码把“工具”的本质讲透它是一个有明确定义、有清晰边界、有可预测行为的独立单元。不是代码越短越好而是契约越稳越好。3. 方案二注册中心型——用装饰器 全局 registry 构建可发现工具集3.1 为什么需要注册中心当工具数超过 3 个时的必然选择方案一解决了单个 tool 的契约问题但现实中的 Agent 不可能只用一个工具。当你需要同时管理“查天气”、“搜新闻”、“算数学”、“查股票”四个工具时硬编码调用就崩了。方案二的核心突破点是把工具从“函数”升级为“可发现的服务”。它的驱动力很朴素——面试官问“如果我新增一个‘查快递’工具你现在的代码要改几处”如果你答“改调用的地方”那就输了如果你答“只加一个被装饰的函数其他地方零改动”面试官就会点头。这就是注册中心的价值解耦工具定义和工具使用。实现的关键在于两个东西一个全局 registry 字典和一个tool装饰器。注意这里不用functools.wraps做复杂包装而是用最轻量的方式# 全局 registry面试时写在模块顶层就行 TOOL_REGISTRY {} def tool(name: str None, description: str ): def decorator(func): # 自动推导 name如果没传就用函数名否则用指定名 tool_name name or func.__name__ # 提取函数签名生成 tool 的 schema这才是重点 import inspect sig inspect.signature(func) parameters {} for param_name, param in sig.parameters.items(): # 只处理有类型注解的参数 if param.annotation ! inspect.Parameter.empty: param_type param.annotation.__name__ if hasattr(param.annotation, __name__) else str(param.annotation) parameters[param_name] { type: string if param_type str else number if param_type in [int, float] else string, description: f参数 {param_name} } # 构建 tool 的完整描述供 LLM 理解 TOOL_REGISTRY[tool_name] { function: func, name: tool_name, description: description, parameters: { type: object, properties: parameters, required: list(parameters.keys()) } } return func return decorator看到这里你可能会疑惑为什么parameters里要手动映射类型为什么不直接用jsonschema因为在面试高压环境下你不可能现场 pip install而且jsonschema对Optional[str]这种联合类型处理很麻烦。方案二的哲学是用 80% 的 effort 解决 95% 的 case。绝大多数 tool 参数就是 string/number手动映射既快又稳。等你写完tool装饰器就可以这样定义工具tool(description根据城市名查询当前天气信息返回温度、天气状况和湿度) def get_weather(city: str) - Dict[str, Any]: # 复用方案一的实现但去掉返回 dict 的逻辑专注业务 pass tool(description搜索指定关键词的最新新闻返回标题和摘要) def search_news(keyword: str, max_results: int 5) - Dict[str, Any]: pass执行完这两段TOOL_REGISTRY就自动有了两个条目每个条目都包含name、description、parameters——这正是 LLM tool calling 所需的全部元数据。3.2 核心难点如何让 LLM 看懂你的工具描述很多候选人卡在这里他们写了装饰器也存了 registry但 LLM 就是调用不了get_weather。问题出在description的写法上。我实测过几十个描述发现 LLM 对“模糊动词”极其敏感。比如❌ 错误示范“获取天气数据”——LLM 不知道“获取”是查实时、查历史还是查预报。✅ 正确示范“根据城市名查询当前实时天气信息包括温度、天气状况如晴、雨和相对湿度百分比”。区别在哪动词具体化 输出明确化 场景限定化。面试时你可以当场优化描述“我刚写的‘获取天气数据’太笼统改成‘查询当前实时天气’加上‘温度、状况、湿度’三个必返字段这样 LLM 才能精准匹配用户 query 中的‘现在北京多少度’。” 这种现场迭代能力比写出完美代码更重要。3.3 实操避坑参数默认值与 required 字段的陷阱另一个高频翻车点是required字段。看上面的search_newsmax_results有默认值 5但keyword没有。按理说required应该只包含[keyword]。但很多候选人会把max_results也加进去导致 LLM 即使没提数量也强行传{max_results: null}然后你的函数收到None就崩了。解决方案很简单在装饰器里加一行判断# 在构建 parameters 循环里 if param.default inspect.Parameter.empty: # 这个参数没有默认值必须 required required_params.append(param_name) else: # 有默认值不强制 required但要在 description 里说明 pass提示面试时如果时间紧可以直接说“我会检查param.default是否为Parameter.empty只有无默认值的参数才加入 required 列表这样既保证必要性又避免 LLM 传 null 引发异常。”这个细节暴露的是你对协议规范的理解深度而不是代码能力。4. 方案三生产就绪型——带超时控制、熔断降级、日志追踪的完整工具框架4.1 为什么方案三才是真正的“手写 Tool Use”方案一和方案二解决了“能不能用”方案三解决的是“敢不敢用”。想象一下你的 Agent 正在帮用户订机票调用“查航班”工具时第三方 API 响应时间从 200ms 涨到 8s而你的 tool 没设超时整个对话就卡死或者“支付”工具连续三次失败你还在傻等重试用户已经怒关页面。方案三的目标就是让每个 tool 都像微服务一样自带健康检查、流量控制和可观测性。它的核心不是堆功能而是建立一套可配置的执行生命周期准备 → 执行 → 成功/失败 → 清理。我们从最痛的痛点入手超时。Python 标准库的signal.alarm在 Windows 不可用threading.Timer又难控制所以方案三采用concurrent.futures的wait机制兼容性最好import time from concurrent.futures import ThreadPoolExecutor, wait, FIRST_COMPLETED from typing import Callable, Any, Dict, Optional class ToolExecutor: def __init__(self, timeout: float 5.0, max_retries: int 2, circuit_breaker_threshold: int 3): self.timeout timeout self.max_retries max_retries self.circuit_breaker_threshold circuit_breaker_threshold self.failure_count 0 # 简化版熔断计数器 def execute(self, func: Callable, *args, **kwargs) - Dict[str, Any]: start_time time.time() # 熔断检查如果失败次数超阈值直接返回熔断错误 if self.failure_count self.circuit_breaker_threshold: return ToolError( codeCIRCUIT_OPEN, message服务暂时不可用请稍后重试, retryableTrue ).__dict__ # 提交任务到线程池 with ThreadPoolExecutor(max_workers1) as executor: future executor.submit(func, *args, **kwargs) # 等待完成或超时 done, not_done wait([future], timeoutself.timeout, return_whenFIRST_COMPLETED) if future in done: try: result future.result() # 成功重置失败计数 self.failure_count 0 return result except Exception as e: # 执行异常记录失败尝试重试 self.failure_count 1 if self._should_retry(e): return self._retry(func, args, kwargs) else: return ToolError( codeEXECUTION_ERROR, messagef工具执行失败{str(e)}, retryableFalse ).__dict__ else: # 超时取消任务记录失败 future.cancel() self.failure_count 1 return ToolError( codeTIMEOUT, messagef工具执行超时{self.timeout}s请稍后重试, retryableTrue ).__dict__ def _should_retry(self, exc: Exception) - bool: # 可重试的错误类型 return isinstance(exc, (TimeoutError, ConnectionError, OSError)) def _retry(self, func: Callable, args, kwargs) - Dict[str, Any]: for i in range(self.max_retries): try: time.sleep(0.1 * (2 ** i)) # 指数退避 return func(*args, **kwargs) except Exception as e: if not self._should_retry(e): raise e return ToolError( codeRETRY_EXHAUSTED, message重试次数已用尽, retryableFalse ).__dict__这个ToolExecutor类就是方案三的骨架。它不关心你 tool 具体做什么只负责“安全地执行它”。面试时你可以指着execute方法说“我把超时、熔断、重试这三个最关键的稳定性保障全部收在这个方法里。以后加新 tool只要传进来就自动获得这些能力——这才是真正可维护的工程实践。”4.2 日志与追踪让每个 tool 调用都可审计生产环境里你不可能靠 print 调试。方案三必须包含轻量日志。面试时不用上 ELK用logging模块就够了但关键是要记录上下文import logging logger logging.getLogger(tool_executor) def execute_with_logging(self, func: Callable, *args, **kwargs) - Dict[str, Any]: tool_name func.__name__ # 生成 trace_id面试时用时间戳随机数即可 import random trace_id f{int(time.time())}_{random.randint(1000,9999)} logger.info(f[{trace_id}] 开始执行工具: {tool_name}, 参数: {kwargs}) start time.time() result self.execute(func, *args, **kwargs) duration time.time() - start if isinstance(result, dict) and code in result and result[code].startswith(ERROR): logger.error(f[{trace_id}] 工具执行失败: {tool_name}, 错误码: {result[code]}, 耗时: {duration:.2f}s) else: logger.info(f[{trace_id}] 工具执行成功: {tool_name}, 耗时: {duration:.2f}s) return result注意面试时强调一点——日志里必须包含trace_id。因为 Agent 的一次完整对话可能串行调用 5 个 tool没有 trace_id你就根本分不清哪个 log 属于哪次对话。这是分布式系统的基本素养哪怕只是模拟。4.3 方案三的终极价值把“手写”变成“可演进”方案三的代码量最大但它最大的优势是可演进性。比如你想加监控指标只需要在execute末尾加一行metrics.observe_duration(tool_name, duration)你想加权限校验就在execute开头插入self._check_permission(func, kwargs)你想支持异步就把ThreadPoolExecutor换成asyncio.to_thread。所有这些扩展都不影响已有的 tool 定义。这才是资深工程师的思维方式不追求一次性写完所有功能而是设计一个能随着业务增长自然长出新能力的骨架。我在某次模拟面试中候选人写完方案三后面试官问“如果我要支持 tool 的并发限流比如同一个用户每分钟最多调用 10 次‘查天气’你怎么加” 他没改一行现有代码只在ToolExecutor里加了一个RateLimiter成员在execute开头调用limiter.acquire(tool_name, user_id)就完成了。这种“小步快跑、渐进增强”的能力远比写出一个巨无霸框架更能打动面试官。5. 三种方案对比与实战选型指南什么时候该用哪一种5.1 一张表看清本质差异维度方案一极简契约型方案二注册中心型方案三生产就绪型核心目标定义单个 tool 的清晰契约管理多个 tool 的可发现性保障 tool 在生产环境的稳定性代码量 50 行~100 行~200 行依赖无仅inspectconcurrent.futures,logging适用场景面试白板速写、单工具 PoC、教学演示多工具 Agent 原型、内部 demo、中小项目面向用户的正式产品、高可用要求场景LLM 兼容性高返回 dict 直接可解析高registry 自动生成符合协议的 schema高执行层透明不影响协议最大风险无法扩展多 tool 时重复代码爆炸注册逻辑简单但缺乏运行时保护过度设计小项目增加维护成本这张表不是让你死记硬背而是帮你建立一个决策树。面试时你可以这样说“如果面试官只要求实现一个 tool我首选方案一因为它最聚焦本质如果他问‘怎么管理 10 个 tool’我会立刻切到方案二展示架构演进思路如果他追问‘线上出问题怎么兜底’我就拿出方案三的核心模块证明我考虑到了真实世界的复杂性。”5.2 面试官最想听的“选型理由”话术别只说“方案三更好”要说清楚为什么此时此地选它。我总结了三句万能话术面试时直接套用关于方案一“我选择从裸函数开始是因为 Tool Use 的第一性原理是‘契约’。在没厘清输入输出边界、错误分类、返回格式之前加任何框架都是空中楼阁。就像盖房子得先打地基再砌墙。”关于方案二“当工具数量超过 3 个硬编码调用就成了技术债。注册中心不是炫技而是把‘工具发现’这个横切关注点抽离出来让业务代码只关心‘做什么’不关心‘怎么做’和‘在哪找’。”关于方案三“生产环境里没有‘理论上能跑通’只有‘实际上扛得住’。超时、熔断、日志不是锦上添花的功能而是把 tool 当作一个独立服务来对待的基本要求。我把它做进框架就是为了避免每个 tool 都重复造轮子。”这三句话把技术选择升维到了工程哲学层面瞬间拉开和只会写代码的候选人的差距。5.3 真实踩坑复盘那些面试官不会说但决定成败的细节最后分享三个血泪教训全是我在陪练中亲眼所见坑一JSON 序列化陷阱有候选人用datetime.now()作为 tool 返回值的一部分结果json.dumps报错Object of type datetime is not JSON serializable。救急方案在返回前统一处理import json from datetime import datetime def make_json_safe(obj): if isinstance(obj, datetime): return obj.isoformat() elif isinstance(obj, (list, tuple)): return [make_json_safe(i) for i in obj] elif isinstance(obj, dict): return {k: make_json_safe(v) for k, v in obj.items()} else: return obj # 在所有 tool 返回前调用 return make_json_safe(result)面试时你甚至不用写完整函数只要说“我会在最终返回前递归处理 datetime、bytes 等非 JSON 类型确保 100% 可序列化。”坑二LLM 的“幻觉调用”LLM 有时会编造 tool name比如把get_weather写成get_weatcher。方案二的 registry 是字典查找直接 keyerror。正确做法是在调用前加一层校验def safe_call_tool(tool_name: str, params: Dict[str, Any]) - Dict[str, Any]: if tool_name not in TOOL_REGISTRY: return ToolError( codeTOOL_NOT_FOUND, messagef未找到工具 {tool_name}请确认名称是否正确, retryableFalse ).__dict__ return TOOL_REGISTRY[tool_name][function](**params)这个safe_call_tool应该成为你 Agent 的唯一入口。坑三参数类型失真用户说“查上海的天气”LLM 可能传{city: 上海}没问题但如果说“查温度高于20度的城市”LLM 可能传{city: temperature 20}你的字符串校验就失效了。终极解法在 tool 内部做二次语义校验。比如get_weather函数里加一句if temperature in city or in city or in city: return ToolError(...).__dict__这不是 paranoid是面对 LLM 不确定性时的必要防御。6. 我的个人体会手写 Tool Use写的是代码练的是系统观写完这三种方案我越来越觉得“手写 Tool Use”这道题本质上是一面镜子。它照出来的不是你对某个框架的熟悉程度而是你脑子里有没有建立起一套分层抽象的工程直觉最底层是数据契约方案一中间层是服务治理方案二最上层是可靠性保障方案三。很多候选人败在试图用一个方案通吃所有场景结果方案一写得太糙方案三又太重中间的方案二反而成了鸡肋。但真实世界里好的系统从来不是非此即彼而是像搭积木一样根据当前阶段的需求选择恰到好处的那一块。我自己在带团队做 Agent 项目时也是这么推进的MVP 阶段用方案一快速验证用户反馈好加功能时切到方案二等 DAU 过万立刻补上方案三的熔断和监控。没有银弹只有适配。所以下次面试官再让你手写 Tool Use别慌着敲键盘。先问他一句“请问这次考察的重点是契约设计、多工具管理还是生产稳定性”——这个问题本身就已经赢了一半。因为真正的资深工程师永远先问“为什么”再想“怎么做”。