Swarms 工具生态实战指南：从 BaseTool 统一调度到 Agent 即工具的多模式集成

Swarms 工具生态实战指南：从 BaseTool 统一调度到 Agent 即工具的多模式集成

【免费下载链接】swarmsThe Enterprise-Grade Multi-Agent Orchestration Framework. Website: https://swarms.ai项目地址: https://gitcode.com/GitHub_Trending/swar/swarms

本指南围绕 Swarms 开源多智能体编排框架中的工具（Tools）体系展开，完整梳理 examples/tools/README.md 所覆盖的九大类工具集成模式：从承载 schema 转换与统一执行的BaseTool基类，到"Agent 即工具"的嵌套编排，再到浏览器自动化（Browser Use、Stagehand）、Claude Code SDK、Exa 搜索、Firecrawl 抓取与多工具协同。读完本文，你将掌握在 Swarms 中把任意 Python 函数、Pydantic 模型、外部 Agent 乃至完整浏览器会话封装为可被 LLM 调用的工具，并理解其底层执行链路与验证方式。

工具生态全景：一条目录，九类集成模式

examples/tools/目录是 Swarms 工具能力的官方示例集散地，目录本身即索引文档，其组织方式如下：

类别	目录/文件	核心能力
Agent 即工具	agent_as_tools.py	把完整 Agent 作为另一个 Agent 的工具
基类工具	base_tool_examples/	BaseTool核心功能、schema 转换与校验
浏览器自动化	browser_use/	Browser Use 驱动的浏览器操作
Claude 集成	claude/claude_as_a_tool.py	Claude Code SDK 作为开发工具
Exa 搜索	exa_search/	Exa 语义搜索引擎集成
Firecrawl	firecrawl/firecrawl_agents_example.py	整站爬取与营销文案改写
多工具使用	multi_tool_use/	多工具串行/并行编排
Stagehand	stagehand/	Stagehand 自然语言浏览器自动化

说明：关联文档中multii_tool_use/目录名存在拼写，仓库内实际路径为examples/tools/multi_tool_use/（含 README.md 与两个示例），下文均以实际路径为准。

这些示例统一通过swarms.tools包对外导出，入口位于 swarms/tools/init.py，公开了BaseTool、MCPManager、ToolStorage、tool_registry以及一系列 schema 转换函数，是理解整个工具体系的最佳起点。

BaseTool：工具管理的统一基座

BaseTool 是整个工具体系的枢纽类，文档化职责包括三个层面：函数到 OpenAI function calling schema 的转换、Pydantic 模型与其 schema 的管理、带完整错误处理与校验的工具执行，并内置了耗时操作的缓存以提升性能。它是一个 PydanticBaseModel子类，核心字段如下：

字段	类型	作用
verbose	Optional[bool]	是否输出详细日志（通过 loguru_logger 输出到base_tool日志目录）
base_models	Optional[List[type[BaseModel]]]	需要管理的 Pydantic 模型列表
autocheck	Optional[bool]	是否启用自动校验
auto_execute_tool	Optional[bool]	是否在dynamic_run中自动执行工具
tools	Optional[List[Callable]]	需要管理的可调用函数列表
tool_system_prompt	Optional[str]	工具系统的系统提示词
function_map	Optional[Dict[str, Callable]]	函数名到可调用对象的映射，用于按名执行
list_of_dicts	Optional[List[Dict]]	字典表示形式的列表

一、schema 转换方法族

BaseTool提供了一条完整的转换链，覆盖函数、Pydantic 模型与字典三种输入形态：

• func_to_dict(function)：把 Python 函数转换为 OpenAI function calling schema 字典，是function_to_dict的别名；转换结果带缓存。注意该 schema 依赖函数的 docstring 与类型注解，因此官方示例中的工具函数都书写了完整的 Google 风格 docstring。
• base_model_to_dict(pydantic_type, output_str=False)：把 Pydantic 模型转换为 OpenAI function calling schema。内部委托给 pydantic_to_json.py 中的base_model_to_openai_function，并整理为标准{"type": "function", "function": {...}}结构；output_str=True时直接返回字符串。
• multi_base_models_to_dict(base_models, output_str=False)：批量转换多个 Pydantic 模型，输出 schema 列表或 JSON 字符串。
• dict_to_openai_schema_str(dict)/multi_dict_to_openai_schema_str(dicts)：把单个/多个参数字典转换为 schema 字符串，底层调用 func_to_str.py 的function_to_str/functions_to_str。
• get_docs_from_callable(item)：从可调用对象提取文档，供 schema 生成使用，内部调用 function_util.py 的process_tool_docs。

tests/tools/test_base_tool.py对上述方法进行了逐一断言，例如func_to_dict的输出必须满足result["type"] == "function"且包含function["name"]与parameters字段。

二、执行方法族

• execute_tool(response)：接收包含调用信息的 JSON 字符串，委托 tool_parse_exec.py 的parse_and_execute_json解析并执行。执行前会校验 response 非空且tools已配置。
• execute_tool_by_name(tool_name, response)：在function_map中按名称查找工具并执行，未找到时抛出ToolNotFoundError。
• execute_tool_from_text(text)：将形如{"name": "add", "parameters": {"a": 1, "b": 2}}的 JSON 文本解析为工具调用并直接以func(**tool_params)方式执行。
• dynamic_run(input)：自动类型检测的智能入口，内部先调用detect_tool_input_type判断输入是Pydantic/Dictionary/Function/Unknown，再走对应转换路径；若开启auto_execute_tool=True，则把函数注册进function_map后直接执行，否则只返回 schema 字符串。
• check_str_for_functions_valid(output)：校验模型输出是否为合法的 function call JSON，且函数名存在于function_map中，常用于输出过滤与防幻觉。

三、层级化的异常体系

BaseTool定义了完整的异常层级（base_tool.py）：

BaseToolError ├── ToolValidationError # 工具校验失败（如参数为空、tools 未配置） ├── ToolExecutionError # 工具执行失败 ├── ToolNotFoundError # 按名称找不到工具 ├── FunctionSchemaError # schema 转换失败 ├── ToolDocumentationError # 工具文档缺失或无效 └── ToolTypeHintError # 类型注解缺失或无效

这使上层 Agent 可以根据异常类型精确区分"参数问题、执行问题、注册问题"，在示例中常配合try/except做差异化降级处理。

从函数到 OpenAI Schema 的完整转换

conver_funcs_to_schema.py 演示了最直接的用法：定义一组带完整类型注解和 docstring 的函数，再调用 py_func_to_openai_func_str.py 中的convert_multiple_functions_to_openai_function_schema(funcs)批量生成 OpenAI function calling schema：

import json from swarms.tools.py_func_to_openai_func_str import ( convert_multiple_functions_to_openai_function_schema, ) funcs = [get_coin_price, get_top_cryptocurrencies, search_cryptocurrencies] print(json.dumps( convert_multiple_functions_to_openai_function_schema(funcs), indent=2, ))

该模块底层基于 Pydantic 的TypeAdapter完成类型到 JSON Schema 的映射（见 py_func_to_openai_func_str.py），并依赖函数参数的类型注解推导required字段、从 docstring 解析description。因此，工具函数的"注释质量"直接决定 schema 质量——这也是示例代码不惜篇幅书写完整 docstring 的原因。

多厂商 schema 校验

LLM 供应商的 function calling 格式并不统一。schema_validation_example.py 演示了BaseTool.validate_function_schema(schema, provider)对两类主流格式的校验：

• OpenAI 风格：{"type": "function", "function": {"name", "description", "parameters"}}
• Anthropic 风格：{"name", "description", "input_schema": {"type": "object", "properties", "required"}}

同一套工具定义经过转换后，可针对不同供应商的 schema 形态分别校验，为多模型兼容（如 multi_tool_anthropic.py 所示）提供了基础。

Agent 即工具：把完整 Agent 嵌入另一个 Agent

agent_as_tools.py 是 Swarms 工具哲学最具代表性的演示：一个 Agent 的run()可以被包装成另一个 Agent 的工具，从而实现"总监 Agent 调度专家 Agent"的分层编排。

示例中定义了多个可复用的量化交易 Agent（run_quant_trading_agent、run_crypto_quant_agent），每个 Agent 自带tools（如create_python_file、update_python_file、backtest_summary、get_coin_price），最终被一个Director-Agent作为工具引用：

agent = Agent( agent_name="Director-Agent", system_prompt="... 战略规划、项目协调、资源分配 ...", max_loops=1, model_name="gpt-5.4", output_type="final", interactive=False, tools=[run_quant_trading_agent], # 把 Agent 作为工具 ) out = agent.run("请调用量化交易 Agent 生成比特币回测代码 ...")

这种模式的要点：

1. 工具签名必须规范：被包装的 Agent 函数以task: str为入参、返回str，完全符合普通工具函数的契约，因此无需任何额外适配即可进入tools=[...]。
2. 职责隔离：专家 Agent 内部再装配自己的工具链（写文件、执行 Python、拉行情），形成"总监 → 专家 → 基础工具"三层结构。
3. 上下文自治：被调用的 Agent 拥有独立 system prompt 与max_loops上限，不会污染调用方上下文。

浏览器自动化：把整个浏览器装进工具

Browser Use 集成

browser_use_as_tool.py 将 Browser Use 框架封装为 Swarms 工具：内部用BrowserAgent（由ChatOpenAI驱动）异步执行任务，外层通过asyncio.run提供同步接口browser_agent_tool(task)，返回model_dump_json格式的完整会话结果：

def browser_agent_tool(task: str): """以可调用工具的形式执行浏览器自动化 Agent。""" return BrowserAgent().run(task) agent = Agent( name="Browser Agent", model_name="gpt-5.4", tools=[browser_agent_tool], ) agent.run("请访问 https://www.coingecko.com 找出过去 24 小时表现最佳的加密货币。")

封装的核心在于异步桥接：底层浏览器操作是异步的，工具函数用asyncio.run把async结果转换为同步返回值，从而与 Swarms 的同步工具执行模型无缝对接。

Stagehand 集成

stagehand/ 目录提供了更细粒度的浏览器能力切分，其 README 定义了三种集成层级：

1. 包装 Agent 模式（1_stagehand_wrapper_agent.py）：让StagehandAgent直接继承 SwarmsAgent，通过env="LOCAL"（Playwright 本地）或env="BROWSERBASE"（云端）控制执行环境，用自然语言下达浏览器任务。
2. 工具模式（2_stagehand_tools_agent.py）：把 Stagehand 能力拆成NavigateTool、ActTool（点击/输入/滚动）、ExtractTool、ObserveTool、ScreenshotTool、CloseBrowserTool等独立工具，交给 Agent 策略性组合，适合"搜索→点开→提取"这类多步骤流程。
3. MCP 模式（3_stagehand_mcp_agent.py）：通过 MCP server 暴露浏览器能力，复用 Swarms 的 MCPManager 统一管理多服务器工具。

三者分别对应"最简接入、精细控制、标准协议"三种取舍，4_stagehand_multi_agent_workflow.py则演示了多 Agent 各自操作不同网站并行的场景。

Claude Code SDK：把编码 Agent 变成工具

claude_as_a_tool.py 将 Anthropic 的 Claude Code SDK 封装为"开发者 Worker Agent"，可直接生成代码、读写文件、执行 shell 命令、操作 Git/GitHub 与 WebSearch。其自带完整安装指引：

pip install claude-code-sdk npm install -g @anthropic-ai/claude-code export ANTHROPIC_API_KEY="your-api-key-here"

核心类ClaudeAppGenerator的几个值得关注的配置：

参数	默认值	说明
retries/retry_delay	3 / 2.0	失败重试次数与间隔，配合tenacity的指数退避
max_steps	40	max_turns上限，供复杂开发任务使用
model	claude-sonnet-4-20250514	底层模型
allowed_tools	Read/Write/Bash/GitHub/Git/Grep/WebSearch	授予 Claude Code 的能力白名单
debug_mode	False	开启后打印工具调用的输入（截断至 200 字符）

对外暴露的developer_worker_agent(task, system_prompt)与普通工具函数契约一致，可直接挂入任何 Swarms Agent 的tools列表。

搜索与抓取：Exa 与 Firecrawl

Exa 语义搜索

exa_search_agent.py 是最精简的搜索集成，直接引入swarms_tools生态的exa_search函数作为工具：

from swarms import Agent from swarms_tools import exa_search agent = Agent( name="Exa Search Agent", model_name="gpt-5.4", tools=[exa_search], tool_call_summary=False, ) agent.run("What are the latest experimental treatments for diabetes?")

Firecrawl 整站抓取

firecrawl_agents_example.py 演示了"营销文案改写"场景：Agent 携带crawl_entire_site_firecrawl工具抓取整站内容，再结合专门定制的 system prompt 完成分析改写。该示例还展示了相关 Agent 参数的作用——dynamic_context_window=True（动态上下文窗口）、dynamic_temperature_enabled=True（动态温度）与max_loops=1配合，让单次抓取改写任务保持稳定输出。

多工具编排：串行链式与并行批量

multi_tool_use/ 目录聚焦多工具的编排能力，其 README 明确了两类场景：多工具按顺序链式调用完成复合任务，以及一次模型输出触发多个工具调用的高效处理。

• many_tool_use_demo.py：为 Agent 装配get_coin_price、get_top_cryptocurrencies等多个行情工具，让模型根据任务自主选择、组合调用。
• multi_tool_anthropic.py：在 Anthropic 模型上验证多工具调用链路，配合前文的多厂商 schema 校验，保证同一套工具在不同供应商下的兼容性。

从源码结构看，多工具执行的吞吐支撑来自BaseTool内部的ThreadPoolExecutor（以os.cpu_count()为池大小）以及 tool_registry.py 中ToolStorage的线程池，多个相互独立的工具调用可以被并行执行。

工具注册表与统一入口

除BaseTool外，tool_registry.py 提供了面向规模化管理的ToolStorage与全局tool_registry：每个工具以ToolMetadata（名称、文档、创建时间）登记在ToolStorageSchema结构中，并支持通过tool_find_by_name按名检索。配合 swarms/tools/init.py 的统一导出（BaseTool、ToolStorage、tool_registry、MCPManager、各类 schema 转换函数），开发者可以：

1. 用BaseTool完成单个 Agent 内的工具转换与执行；
2. 用ToolStorage做跨 Agent 的工具注册与复用；
3. 用MCPManager接入外部 MCP 服务器（如 examples/mcp/ 中的多个演示）扩展生态。

测试验证：如何确认工具链路正确

仓库在 tests/tools/test_base_tool.py 中为工具层提供了可复现的验证用例，覆盖：

• func_to_dict输出结构断言（type、function.name、parameters）；
• base_model_to_dict对 Pydantic 模型的转换正确性；
• detect_tool_input_type对 Pydantic / Dictionary / Function 三种输入的类型识别；
• execute_tool_by_name的按名执行与结果正确性（assert result == 3）；
• check_str_for_functions_valid对函数调用的合法性校验。

此外 example_usage.py 模拟了 LiteLLM 返回的tool_calls结构（OpenAI 与 Anthropic 混合格式），演示通过execute_function_calls_from_api_response与detect_api_response_format自动识别响应格式并批量执行——这是把工具层接入真实模型推理链路的关键一环。

选型建议与最佳实践

需求	推荐方案	参考示例
函数工具化	BaseTool.tools+func_to_dict	base_tool_examples.py
结构化输出工具	Pydantic 模型 +base_model_to_dict	schema_validation_example.py
分层 Agent 编排	Agent 包装为工具	agent_as_tools.py
浏览器交互	Browser Use / Stagehand	browser_use_as_tool.py、stagehand/
代码生成	Claude Code SDK	claude_as_a_tool.py
实时搜索	Exa	exa_search_agent.py
整站抓取	Firecrawl	firecrawl_agents_example.py

实操要点归纳：

1. 工具函数必须写全类型注解与 docstring，这是 schema 自动生成的质量前提；
2. 优先用dynamic_run让框架自动识别输入类型，减少手工分支；
3. 开启verbose=True定位问题，日志统一输出到base_tool日志目录；
4. 多供应商场景用validate_function_schema预检，并用detect_api_response_format适配响应格式；
5. Agent 作为工具时保持task: str → str的契约，即可无缝嵌套多层编排。

至此，从BaseTool的 schema 转换与执行链路，到九大类外部能力集成，再到测试验证与选型建议，Swarms 的工具体系已构成一条完整可落地的实战路径：任意函数、模型、Agent 与外部服务，都能在统一契约下成为多智能体系统可调用的能力单元。

【免费下载链接】swarmsThe Enterprise-Grade Multi-Agent Orchestration Framework. Website: https://swarms.ai项目地址: https://gitcode.com/GitHub_Trending/swar/swarms