1. 项目概述当智能体开始为自己锻造工具最近在折腾各种AI智能体Agents时我遇到了一个挺有意思的瓶颈智能体本身很强大能理解、能规划、能执行但它的“手”和“眼睛”——也就是我们为它提供的工具Tools——却常常显得笨拙和低效。我们手动编写的工具无论是调用一个API、解析一段文本还是操作一个软件其设计思路往往源于人类工程师的直觉未必是智能体最高效的交互方式。这就引出了一个颇具递归色彩的想法我们能否让智能体来参与甚至主导“编写高效工具”这个过程本身这正是“Writing effective tools for agents — with agents”这个项目标题的核心。它不是一个简单的工具使用教程而是一种方法论和工程实践的探索旨在通过智能体的视角来重新定义和构建工具最终形成一个正向循环更好的工具让智能体更强大而更强大的智能体又能设计出更好的工具。这背后涉及几个关键概念。首先是智能体Agents在这里它指的是能够理解目标、制定计划、调用工具函数来执行任务的大型语言模型应用。其次是工具Tools这是智能体与外部世界交互的接口通常是一个个函数描述其功能、输入参数和输出格式。而MCPModel Context Protocol正是一个新兴的、旨在标准化智能体与工具之间通信的协议它让工具的接入和管理变得更清晰、更模块化。当我们谈论用智能体编写工具时我们实际上是在利用智能体在代码生成、逻辑理解和需求分析方面的能力来优化这个接口层使其更“智能体友好”。这项工作适合所有正在构建或计划构建AI智能体应用的开发者、产品经理和技术负责人。无论你是想提升现有智能体工作流的效率还是探索下一代人机协作的界面理解如何让智能体参与工具设计都将是一个关键杠杆点。接下来我将拆解这一理念的完整实现路径从设计思路到实操编码再到效果评估。2. 核心理念与设计范式的转变2.1 从“人类友好”到“智能体友好”的工具设计传统软件开发中工具API、库、命令行工具的设计首要考虑的是人类开发者的体验清晰的命名、合理的默认值、完整的错误信息、易于阅读的文档。然而对于智能体而言它的“体验”是完全不同的。智能体通过自然语言描述和结构化模式如JSON Schema来理解一个工具。因此一个对人类友好的工具对智能体可能并不友好。智能体友好型工具的核心特征精确且无歧义的描述工具的名称和描述必须极度精确避免使用多义词或依赖上下文。例如“处理文件”就是一个糟糕的描述而“将Markdown文件转换为HTML字符串”则好得多。智能体依赖这些描述进行工具选择。结构化与强类型的输入/输出智能体擅长处理结构化的数据。工具的参数应该使用明确的类型字符串、整数、数组、对象并尽可能提供详细的模式Schema约束。这减少了智能体“猜”参数格式的可能。确定性与可预测性工具的行为应该是确定性的。相同的输入应产生相同的输出或可预见的错误。非确定性的工具如依赖随机数、未明确状态的系统会让智能体难以规划和调试。完备的错误处理与信息反馈当工具失败时返回的错误信息应该对智能体有指导意义。不仅仅是“错误代码500”最好是“无法连接到数据库‘用户数据’原因网络超时。请检查网络连接或数据库地址。”这样的信息能帮助智能体进行下一步决策例如重试或切换备用方案。适度的功能粒度工具应该保持单一职责。一个“万能”的工具如“管理用户”对智能体来说难以理解和正确调用。将其拆分为“创建用户”、“查询用户”、“更新用户”、“删除用户”等细粒度工具虽然数量多了但智能体的调用准确率会大幅提升。注意设计“智能体友好”工具并非意味着完全抛弃人类可读性。优秀的工具设计应该能在两者之间取得平衡例如通过自动生成的人类可读文档或者设计时同时考虑两套接口描述。2.2 智能体作为工具设计协作者的工作流让智能体参与工具设计并不是简单地让它写一段代码。而是一个多阶段、迭代的协作过程。一个典型的工作流如下需求澄清与分解人类提出一个模糊的需求如“帮我从网页上提取产品价格”。智能体作为协作者通过提问将模糊需求分解为具体的、可操作的工具规格。例如它会问“目标网页是静态还是动态渲染价格信息是否有固定的CSS选择器或HTML标签模式需要处理货币单位转换吗”工具接口原型设计基于澄清后的需求智能体生成一个初始的工具函数签名和描述。例如它可能设计一个工具叫extract_price_from_html输入是html_content(字符串) 和price_selector(CSS选择器字符串)输出是一个包含price(浮点数) 和currency(字符串) 的对象。实现方案生成与评审智能体根据接口原型生成具体的代码实现可能是Python、JavaScript等。人类开发者在此环节进行代码评审关注安全性、性能、异常处理等智能体可能忽略的深层工程问题。测试用例生成智能体可以为新创建的工具自动生成一组测试用例包括正常情况和边界情况。这极大地提升了工具的可靠性。文档与描述优化智能体可以自动生成或优化工具的“智能体端”描述使其更清晰、无歧义同时也能生成供人类阅读的API文档。工具链的自动化组装对于复杂任务智能体可以识别出现有工具之间的缺口并建议或直接创建新的“粘合剂”工具将多个工具串联成一个更高效的工作流。这个过程中人类扮演的是“产品经理”、“架构师”和“安全审计员”的角色而智能体则是“高级程序员”、“测试工程师”和“技术写手”。两者的优势得到了结合。3. 关键技术栈与协议选型3.1 MCPModel Context Protocol的核心价值在构建智能体与工具的生态系统时一个核心挑战是工具的动态发现与标准化接入。每个项目、每个框架都可能定义自己的一套工具格式导致智能体难以复用和组合不同来源的能力。这就是M协议要解决的根本问题。MCP可以理解为智能体世界的“USB标准”。它定义了一套简单的、与模型无关的协议用于服务器提供工具和数据源与客户端智能体运行时环境之间的通信。其核心价值在于标准化统一的工具描述格式名称、描述、输入模式让任何兼容MCP的智能体都能立即理解和使用这些工具。动态性工具服务器可以在运行时启动、注册其工具智能体客户端可以动态发现并加载这些工具无需重新部署或修改智能体核心代码。安全性通过资源Resources和提示Prompts的概念MCP提供了更细粒度的上下文控制服务器可以声明式地控制哪些数据或提示模板可供客户端使用而不是暴露原始文件系统或数据库连接。生态互操作性随着Anthropic、Google等公司支持MCP一个庞大的工具生态正在形成。你可以轻松找到用于文件操作、数据库查询、天气获取、代码仓库管理的MCP服务器并一键接入你的智能体。在“用智能体写工具”的上下文中MCP为我们提供了一个完美的目标框架我们最终要生成的不仅仅是一个孤立的Python函数而是一个符合MCP标准的、可以轻松集成到任何兼容环境如Claude Code、Cursor等中的工具服务器。3.2 Claude Code 作为实践平台Claude Code或指代集成了Claude模型的IDE环境是目前实践这一理念的绝佳平台。它本质上是一个强大的智能体运行时环境天然支持工具调用。在其生态中有两个紧密相关的概念Skills这通常指一些预定义的、高级的、针对特定领域如代码重构、文档生成的任务流程或复杂提示模板。一个Skill内部可能会调用多个底层Tools。Tools (via MCP)这就是我们讨论的原子操作。在Claude Code中你可以通过配置MCP服务器来为其添加成千上万个Tools。我们的项目重点在于Tools。在Claude Code中实践意味着我们设计和实现的工具能立刻在一个功能丰富、交互直观的环境中得到测试和应用形成快速反馈闭环。你可以亲眼看到智能体是如何理解、选择并调用你编写的工具的这是最直接的评估方式。3.3 辅助工具链从代码生成到评估除了核心的智能体和协议一个高效的工具体系还需要一系列辅助工具代码生成与补全模型这是我们的“核心工人”。除了通用的Chat模型如Claude 3.5 Sonnet, GPT-4专门针对代码微调的模型如Claude 3.5 Sonnet for Code, CodeLlama在生成高质量、符合约定的工具代码方面表现更佳。静态分析工具用于检查生成的代码是否符合安全规范、有无明显的语法错误或不良模式。例如对于Python可以使用bandit安全、pylint代码质量在工具代码被集成前进行自动化扫描。测试框架pytest是Python世界的事实标准。我们可以引导智能体不仅生成工具代码还生成对应的pytest测试用例并设置自动化流程来运行这些测试。评估框架这是衡量“工具是否有效”的关键。我们需要设计评估指标例如工具调用准确率给定一个任务描述智能体是否能正确选择并调用这个工具参数填充正确率调用时提供的参数是否符合模式且语义正确任务完成成功率端到端地执行一个需要多步工具调用的任务最终的成功率是多少效率提升使用新设计的工具后完成同一任务所需的交互轮次或时间是否减少一个常见的评估方法是构建一个基准测试集Benchmark包含一系列具有标准答案的任务然后让智能体在接入新旧不同工具集的情况下分别运行对比其表现。4. 实操构建一个“智能体友好”的网页抓取工具链让我们通过一个具体的例子将上述理念付诸实践。假设我们的目标是让智能体能够从电商产品页面提取结构化信息名称、价格、图片URL。我们将用智能体来协助我们创建这个工具链。4.1 阶段一需求澄清与工具规划我们首先向智能体例如在Claude Code中提出原始需求“我需要一个工具来从网页抓取产品信息。”一个优秀的智能体会开始反问和澄清“您希望从哪些网站抓取不同网站的结构差异很大。”“产品信息具体包括哪些字段例如名称、价格、描述、图片链接、规格参数”“网页是公开可访问的吗是否需要处理登录、JavaScript渲染或反爬虫机制”“输出格式您希望是JSON还是直接存入数据库”经过几轮交互我们与智能体共同确定如下规格目标针对已知结构的、静态渲染的电商页面如一个模拟的练习网站。字段product_name(字符串),price(浮点数),image_url(字符串),availability(布尔值)。技术使用requests获取HTML使用BeautifulSoup4进行解析。工具设计考虑到灵活性和复用性我们决定设计两个工具而不是一个“巨无霸”。工具Afetch_html输入url(字符串)。输出html_content(字符串) 或错误信息。工具Bparse_product_page输入html_content(字符串)selectors(一个JSON对象包含各字段的CSS选择器)。输出结构化的产品信息JSON对象。这种拆分的妙处在于fetch_html是一个通用工具可被任何需要原始HTML的任务复用parse_product_page专注于解析逻辑并且通过selectors参数使其可配置能适应不同网站而不是写死在代码里。4.2 阶段二智能体辅助的代码实现接下来我们要求智能体根据上述规划实现这两个工具并遵循MCP服务器的大致结构。我们以Python为例。首先我们让智能体生成fetch_html工具import requests from typing import Any import json def fetch_html(url: str) - str: Fetches the raw HTML content from a given public URL. Args: url (str): The full URL of the webpage to fetch. Returns: str: The raw HTML content as a string if successful. Raises: Exception: If the network request fails (e.g., connection error, timeout, or HTTP error). try: # 设置一个合理的超时和User-Agent是良好实践 headers {User-Agent: Mozilla/5.0 (compatible; AgentTool/1.0)} response requests.get(url, headersheaders, timeout10) response.raise_for_status() # 如果状态码不是200抛出HTTPError return response.text except requests.exceptions.RequestException as e: # 将异常转换为对智能体友好的错误信息 raise Exception(fFailed to fetch URL {url}: {type(e).__name__} - {str(e)}) # 接下来我们需要将这个函数包装成MCP工具。 # 以下是一个模拟的MCP工具定义格式具体取决于你使用的MCP服务器库如 mcp Python SDK def fetch_html_tool(): from mcp import Tool return Tool( namefetch_html, descriptionFetches the raw HTML content from a given public URL. Useful for web scraping tasks., input_schema{ type: object, properties: { url: { type: string, description: The full HTTP/HTTPS URL of the webpage to fetch. } }, required: [url] }, handlerlambda **kwargs: fetch_html(kwargs[url]) # 实际处理函数 )实操心得在让智能体生成代码时明确的指令至关重要。我会要求它“包含详细的错误处理将网络异常转换为对人类和智能体都可读的异常信息”并“添加适当的超时和请求头以模拟普通浏览器访问避免被简单屏蔽”。这能显著提升生成代码的健壮性。接着生成更复杂的parse_product_page工具from bs4 import BeautifulSoup import json def parse_product_page(html_content: str, selectors: dict) - dict: Parses HTML content of a product page to extract structured information. Args: html_content (str): The raw HTML string of the product page. selectors (dict): A dictionary mapping field names to CSS selectors. Example: {name: h1.product-title, price: .price}. Returns: dict: A dictionary containing extracted product info. Missing fields will be None. Example: {product_name: Awesome Chair, price: 99.99, image_url: ..., availability: True} soup BeautifulSoup(html_content, html.parser) result {} # 定义我们希望提取的字段及其处理逻辑 field_config { product_name: lambda sel: soup.select_one(sel).get_text(stripTrue) if soup.select_one(sel) else None, price: lambda sel: _parse_price(soup.select_one(sel).get_text(stripTrue) if soup.select_one(sel) else None), image_url: lambda sel: soup.select_one(sel).get(src) if soup.select_one(sel) else None, availability: lambda sel: in stock in soup.select_one(sel).get_text(stripTrue).lower() if soup.select_one(sel) else False, } for field, selector in selectors.items(): if field in field_config: try: result[field] field_config[field](selector) except Exception as e: # 记录解析错误但不要使整个工具失败 result[field] None print(fWarning: Failed to parse field {field} with selector {selector}: {e}) else: print(fWarning: Field {field} is not configured for parsing.) return result def _parse_price(price_text: str) - float: Helper function to extract numeric price from text like $99.99 or €123,45. if not price_text: return None import re # 移除货币符号和千位分隔符将逗号替换为点处理欧洲格式 numeric_str re.sub(r[^\d.,], , price_text) numeric_str numeric_str.replace(,, .) # 处理可能残留的多个点如小数点后的部分 if numeric_str.count(.) 1: # 保留最后一个点作为小数点 parts numeric_str.split(.) numeric_str .join(parts[:-1]) . parts[-1] try: return float(numeric_str) except ValueError: return None # 对应的MCP工具定义 def parse_product_page_tool(): from mcp import Tool return Tool( nameparse_product_page, descriptionExtracts product information (name, price, image, availability) from HTML content using provided CSS selectors., input_schema{ type: object, properties: { html_content: { type: string, description: The HTML content of the product page. }, selectors: { type: object, description: A JSON object mapping field names to CSS selectors. E.g., {\product_name\: \h1\, \price\: \.price\}, additionalProperties: {type: string} } }, required: [html_content, selectors] }, handlerlambda **kwargs: parse_product_page(kwargs[html_content], kwargs[selectors]) )在这个阶段智能体不仅生成了核心解析逻辑还根据我们的要求“处理不同价格格式”生成了一个辅助函数_parse_price。这展示了它理解跨领域需求字符串处理、正则表达式的能力。4.3 阶段三集成与测试有了工具代码下一步是将其集成到一个MCP服务器中并编写测试。1. 构建简易MCP服务器我们可以使用Python的mcpSDK来快速搭建一个服务器。智能体可以生成服务器框架代码# server.py import asyncio from mcp.server import Server, NotificationOptions from mcp.server.models import InitializationOptions import mcp.server.stdio # 导入我们之前定义的工具函数 from my_tools import fetch_html_tool, parse_product_page_tool async def main(): # 创建服务器实例 server Server(product-scraper-tools) # 向服务器注册我们的工具 server.add_tool(fetch_html_tool()) server.add_tool(parse_product_page_tool()) # 使用标准输入/输出运行服务器这是MCP的常见通信方式 async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): await server.run(read_stream, write_stream, InitializationOptions()) if __name__ __main__: asyncio.run(main())2. 生成自动化测试我们要求智能体为这两个工具生成pytest测试用例。这是确保工具可靠性的关键。# test_tools.py import pytest from my_tools import fetch_html, parse_product_page # 模拟一个简单的HTML内容用于测试解析工具 SAMPLE_HTML html body h1 class\product-title\Ergonomic Office Chair/h1 p class\price\$299.99/p img src\https://example.com/chair.jpg\ alt\Chair\ div class\stock\In stock/div /body /html class TestFetchHtml: def test_fetch_valid_url(self, requests_mock): # 使用pytest-mock或requests-mock来模拟网络请求 test_url https://example.com test_content htmlTest/html requests_mock.get(test_url, texttest_content) result fetch_html(test_url) assert result test_content def test_fetch_invalid_url_raises_exception(self, requests_mock): test_url https://invalid.example requests_mock.get(test_url, status_code404) with pytest.raises(Exception, matchFailed to fetch URL): fetch_html(test_url) class TestParseProductPage: def test_parse_all_fields(self): selectors { product_name: h1.product-title, price: .price, image_url: img, availability: .stock } result parse_product_page(SAMPLE_HTML, selectors) assert result[product_name] Ergonomic Office Chair assert result[price] 299.99 assert result[image_url] https://example.com/chair.jpg assert result[availability] True def test_parse_missing_field_returns_none(self): selectors {product_name: h1.nonexistent} result parse_product_page(SAMPLE_HTML, selectors) assert result[product_name] is None def test_price_parsing_helper(self): from my_tools import _parse_price assert _parse_price($99.99) 99.99 assert _parse_price(€123,45) 123.45 assert _parse_price(1.234,56 €) 1234.56 # 处理复杂格式 assert _parse_price(Free) is None通过运行pytest test_tools.py我们可以快速验证工具的基本功能。智能体生成的这些测试覆盖了正常流程、错误情况和边界条件为工具的可靠性打下了基础。5. 效果评估与迭代优化工具构建完成后最重要的环节是评估其“有效性”。我们如何知道这个由智能体协助设计的工具链真的比我们随手写的一个“全能”抓取函数更好5.1 设计评估实验我们可以设计一个简单的评估基准任务集准备10个不同结构的模拟产品页面HTML文件或指向真实但稳定的测试页面。智能体环境在Claude Code中配置两个不同的工具集对照组只有一个工具scrape_product(url)其内部硬编码了针对某个特定网站的选择器逻辑。实验组拥有我们刚创建的两个工具fetch_html(url)和parse_product_page(html, selectors)。评估指令给智能体同样的任务“请从[URL]中提取产品名称、价格、图片链接和库存状态。” 对于实验组我们需要额外提供或让智能体自己推断每个页面对应的selectors字典。这本身也可以是一个子任务。评估指标任务成功率成功提取所有四个字段且信息正确的任务比例。交互轮次平均完成一个任务需要多少轮对话智能体调用工具、用户提供选择器等。工具调用准确率智能体是否每次都正确选择了需要的工具有没有误调用或遗漏泛化能力当面对一个全新的、不在训练集中的页面结构时哪组工具能更快适应实验组只需更新selectors字典而对照组可能需要重写整个函数。5.2 分析结果与迭代假设我们运行了评估可能发现实验组成功率更高因为parse_product_page工具更鲁棒错误处理更好且将获取和解析分离降低了单点故障风险。对照组在已知网站更快因为无需考虑选择器一步到位。实验组在适应新网站时更灵活人类或另一个智能体可以很容易地通过检查元素获取新的选择器然后更新给工具而无需修改代码。基于这些发现我们可以进行迭代优化优化工具描述如果发现智能体有时不理解selectors参数该怎么填我们可以优化工具描述增加更详细的示例。增加工具如果发现频繁需要“从页面中找出产品区块的选择器”我们可以考虑创建一个新的工具discover_product_container(html)用启发式方法自动猜测主要产品内容的选择器从而进一步自动化流程。改进错误信息如果_parse_price经常失败我们可以让它返回更详细的错误原因帮助智能体决定下一步例如尝试另一种解析方法或向用户请求帮助。5.3 将评估自动化最终我们可以将上述评估流程脚本化形成一个持续的集成测试环节。每当工具代码更新或接入了新的智能体模型都可以自动运行这个评估基准监控工具效能的波动。这确保了我们的“用智能体写工具”的循环是数据驱动的并且朝着真正提升效率的方向演进。6. 常见陷阱与进阶技巧在实际操作中你会遇到各种预料之外的问题。以下是我从多次实践中总结的一些关键点和进阶思路。6.1 智能体编写工具时的常见陷阱过度抽象与“魔法”智能体有时会倾向于编写过于“聪明”或抽象的工具试图用一个工具解决所有问题。这通常会导致工具接口复杂、行为不可预测。必须坚持“单一职责”和“明确接口”的原则。如果一个工具变得复杂就拆分成多个。忽视安全性与副作用智能体生成的代码可能包含安全漏洞如命令注入如果工具涉及执行命令、路径遍历如果涉及文件操作或向未经验证的URL发起请求。人类审核必须将安全性作为最高优先级对任何涉及外部输入执行、文件系统访问或网络请求的代码进行严格审查。脆弱的解析逻辑就像我们例子中的HTML解析基于CSS选择器或正则表达式的解析对网页结构变化非常敏感。智能体生成的解析器可能缺乏健壮性。解决方法是结合多种解析策略如同时尝试多个选择器、使用HTML结构特征并增加重试或降级逻辑。工具描述质量不佳工具的描述description和参数描述是智能体理解它的唯一途径。模糊的描述会导致误用。必须像编写产品说明书一样精心打磨这些描述可以多次让智能体自己来评审和优化这些描述。6.2 进阶技巧让工具生态自我演进当基础工具集搭建起来后可以探索更自动化的演进路径工具使用日志分析记录智能体对每个工具的调用频率、成功/失败情况、常见的参数错误。这些数据是优化工具接口和实现的黄金指标。例如如果某个工具频繁因同一类参数错误而调用失败说明它的参数描述不够清晰或者需要增加输入验证。自动生成“胶水”技能Skills观察智能体执行复杂任务时的常见工具调用序列。这些序列可以被抽象和固化成一个新的“Skill”。例如如果“抓取产品信息 - 生成产品描述 - 保存到数据库”是一个固定流程就可以创建一个Skill来自动化这个流程对上层提供一个更简单的接口。引入工具间的竞争对于同一个功能比如文本摘要可以设计多个不同实现基于不同算法或模型的工具。智能体在运行时可以根据上下文如文本长度、所需速度或历史性能数据动态选择最合适的工具。这可以通过在工具描述中增加“元信息”如best_for: long_documents,latency: high来实现。闭环优化建立一个系统当智能体任务失败时自动分析失败原因。如果原因是缺少某个关键工具系统可以触发一个流程让另一个智能体根据失败案例的需求草拟一个新工具的设计方案提交给人类审核和实现。这样就形成了一个从“使用发现问题”到“创造新工具”的闭环。“Writing effective tools for agents — with agents” 不是一个一蹴而就的项目而是一个持续的工程哲学。它要求我们从智能体的“思维”方式出发重新审视我们构建软件接口的方法。通过将智能体视为协作者而非仅仅是工具的使用者我们不仅能创造出更高效、更鲁棒的智能体系统更是在探索一种全新的人机协作范式——人类负责定义意图、把握方向和审核安全而智能体负责将意图转化为精确、可执行、可组合的数字化能力。这个过程本身就像是在教一个超级实习生如何更好地为你工作而最终你们将成为一个无与伦比的团队。