CAMEL Toolkits 工具包体系完全指南FunctionTool、BaseToolkit 与 MCP Server【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel本文以 CAMEL 框架camel.toolkits包为对象系统讲解其 API 参考索引见 docs/camel.toolkits.rst所覆盖的核心模块与设计思路从FunctionTool这一最小工具单元到BaseToolkit工具包骨架再到把任意工具包一键变成 MCP Server 的完整流程。读完本文你将掌握如何用 CAMEL 定义、包装、组装工具并接入ChatAgent以及如何基于内置工具包快速搭建可远程调用的工具服务。一、camel.toolkits 包定位Agent 与外部世界的接口层在 CAMEL 中Tool工具是一个可被调用的函数它拥有名称、描述、输入参数与输出类型是 Agent 与外部世界之间的接口而Toolkit工具包则是围绕特定目的组织起来的一组相关工具的集合覆盖网页搜索、数据抽取、代码执行、GitHub 集成等场景。camel.toolkits包正是这一能力的载体。其 API 参考索引文档 docs/camel.toolkits.rst 采用 Sphinx autodoc 组织列出的子模块与当前源码的对应关系如下RST 中的个别命名沿用了旧模块名实际源码文件见括号标注RST 索引中的模块当前源码实现职责camel.toolkits.basecamel/toolkits/base.pyBaseToolkit基类、RegisteredAgentToolkitMixin、manual_timeout装饰器camel.toolkits.openai_functioncamel/toolkits/function_tool.pyFunctionTool类与 OpenAI Tool Schema 生成/校验camel.toolkits.code_executioncamel/toolkits/code_execution.py多沙箱代码执行内部 Python、Jupyter、Docker、subprocess、e2bcamel.toolkits.dalle_toolkitcamel/toolkits/image_generation_toolkit.py基于 DALL-E 的图像生成OpenAIImageToolkitcamel.toolkits.github_toolkitcamel/toolkits/github_toolkit.pyGitHub 仓库交互issue 检索、创建 PR 等camel.toolkits.google_maps_toolkitcamel/toolkits/google_maps_toolkit.pyGoogle Maps 服务地址校验、海拔、时区等camel.toolkits.linkedin_toolkitcamel/toolkits/linkedin_toolkit.pyLinkedIn 发帖、删帖、资料查询camel.toolkits.math_toolkitcamel/toolkits/math_toolkit.py基础数学运算camel.toolkits.open_api_toolkitcamel/toolkits/open_api_toolkit.py基于 OpenAPI 规范的 REST API 工具化camel.toolkits.reddit_toolkitcamel/toolkits/reddit_toolkit.pyReddit 热帖、评论情感分析、关键词追踪camel.toolkits.retrieval_toolkitcamel/toolkits/retrieval_toolkit.py本地向量库检索camel.toolkits.search_toolkitcamel/toolkits/search_toolkit.py多引擎网页搜索camel.toolkits.slack_toolkitcamel/toolkits/slack_toolkit.pySlack 频道与成员管理camel.toolkits.twitter_toolkitcamel/toolkits/twitter_toolkit.pyTwitter 发推、删推、资料查询camel.toolkits.weather_toolkitcamel/toolkits/weather_toolkit.pyOpenWeatherMap 天气查询包的总入口 camel/toolkits/init.py 导出了 100 余个工具包类涵盖搜索、代码执行、邮件、日历、知识库、视频、金融、3D 网格等方向完整清单可参见 docs/key_modules/tools.md 中的内置工具包表格。二、FunctionTool一切工具的最小单元FunctionTool是 CAMEL 工具体系的核心抽象定义于 camel/toolkits/function_tool.py。它把一个普通 Python 函数包装成「LLM 可以直接调用」的工具默认从函数签名与 docstring 中解析出 OpenAI Tool Schema也允许用户传入自定义 Schema 覆盖。2.1 三行代码定义一个工具from camel.toolkits import FunctionTool def add(a: int, b: int) - int: Adds two numbers. return a b add_tool FunctionTool(add)包装完成后可以用内置方法查看工具的各项属性print(add_tool.get_function_name()) # add print(add_tool.get_function_description()) # Adds two numbers. print(add_tool.get_openai_function_schema()) # OpenAI Functions schema已弃用推荐下面的方法 print(add_tool.get_openai_tool_schema()) # OpenAI Tool 完整格式get_openai_tool_schema()返回的结构形如{ type: function, function: { name: add, description: Adds two numbers., strict: true, parameters: { type: object, properties: { a: {type: integer, description: The first number to be added.}, b: {type: integer, description: The second number to be added.} }, required: [a, b], additionalProperties: false } } }2.2 Schema 自动解析的规则与边界从源码看get_openai_tool_schema()function_tool.py通过inspect.signature提取参数、用pydantic.create_model构造模型并生成 JSON Schema再借助docstring_parser解析 docstring 中的描述。需要注意的规则包括参数必须有类型注解否则按Any处理*args/**kwargs可变参数不被支持解析时会被跳过所有参数都应在 docstring 中说明支持的 docstring 风格为 ReST、Google、Numpydoc 与 Epydoc生成后会调用sanitize_and_enforce_required()function_tool.py做严格模式适配移除 OpenAI 不允许的default字段、为可选字段补充null类型、把所有字段标记为required并为所有嵌套对象递归添加additionalProperties: false。FunctionTool构造函数还提供若干高级选项参数默认值作用openai_tool_schemaNone用户自定义 OpenAI Tool Schema覆盖自动解析结果synthesize_schemaFalse开启后用 LLM 辅助自动合成 Schemasynthesize_schema_modelNone用于合成 Schema 的模型后端默认取ModelPlatformType.DEFAULTsynthesize_schema_max_retries2Schema 合成的最大重试次数synthesize_outputFalse输出合成模式基于函数执行结果做二次加工synthesize_output_model/synthesize_output_formatNone输出合成使用的模型与返回格式2.3 同步与异步调用FunctionTool实例本身可调用__call__并会在调用前把 LLM 传来的 JSON dict 参数递归强转为函数签名中声明的 Pydantic 模型类型_coerce_arguments见 function_tool.py从而弥合「LLM 输出 JSON」与「Python 类型签名」之间的鸿沟。对于异步工具推荐显式使用await tool.async_call(...)或await agent.astep()FunctionTool内置了共享线程池与持久事件循环_SYNC_TOOL_EXECUTOR、_PERSISTENT_LOOP避免 httpx 连接池问题并防止同步调用阻塞事件循环。此外function_tool.py 还提供了generate_docstring(code, model)函数可调用 LLM 为一段函数源码自动生成符合 PEP 8/PEP 257 的 docstring默认使用 gpt-4o-mini用于批量补齐 Schema 描述。三、BaseToolkit工具包的骨架与统一能力所有内置工具包都继承自 camel/toolkits/base.py 中的BaseToolkit。它提供了三类统一能力3.1 统一超时机制BaseToolkit.__init__(timeoutConstants.TIMEOUT_THRESHOLD)接收一个可选的超时秒数且校验其必须为正数。更关键的是__init_subclass__会在子类定义时自动遍历其可调用方法用with_timeout包装器统一加上超时控制默认阈值来自camel.utils.constants中的Constants.TIMEOUT_THRESHOLD。以下情况会被自动跳过已标注_manual_timeout通过manual_timeout装饰器base.py的方法——它们内部自行管理超时签名中本身带有timeout参数的方法——避免双重包装。3.2 get_tools()统一出口子类必须实现get_tools()返回List[FunctionTool]这是把工具包暴露给 Agent 的标准接口。3.3 MCP Server 能力BaseToolkit声明了mcp: FastMCP属性并提供run_mcp_server(mode)方法mode取值为stdio、sse、streamable-http三者之一直接调用self.mcp.run(mode)。配合MCPServer()装饰器如MathToolkit、WeatherToolkit、SearchToolkit类上方所示任何工具包都能一键作为 MCP 服务器运行。此外base.py 还定义了RegisteredAgentToolkitMixin需要持有ChatAgent引用的工具包如消息代理类工具继承它后ChatAgent初始化时若通过toolkits_to_register_agent参数传入该类工具包会自动调用register_agent(agent)完成注册。3.4 完整示例MathToolkitMathToolkit 是理解工具包写法的最佳范本其结构为「MCPServer()装饰 继承BaseToolkit 实现get_tools()」from typing import List, Union from camel.toolkits.base import BaseToolkit from camel.toolkits.function_tool import FunctionTool from camel.utils import MCPServer MCPServer() class MathToolkit(BaseToolkit): def math_add(self, a: float, b: float) - float: Adds two numbers. Args: a (float): The first number to be added. b (float): The second number to be added. Returns: float: The sum of the two numbers. return a b # math_subtract / math_multiply / math_divide / math_round 同理 ... def get_tools(self) - List[FunctionTool]: return [ FunctionTool(self.math_add), FunctionTool(self.math_subtract), FunctionTool(self.math_multiply), FunctionTool(self.math_divide), FunctionTool(self.math_round), ]MathToolkit提供的方法与参数如下源码与测试 test/toolkits/test_math_functions.py 相互印证方法参数说明math_add(a, b)float, float求和math_subtract(a, b)float, float求差math_multiply(a, b, decimal_places2)float, float, int求积默认保留 2 位小数math_divide(a, b, decimal_places2)float, float, int求商除数为 0 时返回错误字符串Error: Cannot divide by zero.math_round(a, decimal_places0)float, int四舍五入值得留意的是MathToolkit还保留了add/sub/multiply/divide/round等旧别名其中round曾遮蔽 Python 内建函数现在调用会触发DeprecationWarning提示改用math_前缀的新方法。四、内置工具包实战详解4.1 安装与导入内置工具包的完整能力通过额外依赖安装获得pip install camel-ai[tools]然后即可从camel.toolkits导入所需工具包from camel.toolkits import SearchToolkit, WeatherToolkit, CodeExecutionToolkit4.2 WeatherToolkit带 API Key 校验的工具包WeatherToolkit 封装了 OpenWeatherMap 天气查询是「依赖环境变量 第三方库」型工具包的典型代表构造函数WeatherToolkit(timeoutNone)timeout为 API 请求超时秒数get_openweathermap_api_key()从环境变量OPENWEATHERMAP_API_KEY读取密钥缺失时抛出ValueError并提示去 OpenWeatherMap 获取get_weather_data(city, ...)需要pyowm库未安装会提示pip install pyowm返回一段格式化天气报告字符串异常时返回错误信息而非抛出。get_weather_data的参数细节参数取值默认值说明city字符串必填城市名建议格式City, CountryCode如Paris, FR省略国家码可能因同名城市而查询不准temp_unitskelvin/celsius/fahrenheitkelvin温度单位wind_unitsmeters_sec/miles_hour/knots/beaufortmeters_sec风速单位visibility_unitsmeters/milesmeters能见度单位time_unitsunix/iso/dateunix日出日落时间格式从源码注释看该工具的time_units等参数本应设计为枚举类型当前尚未支持枚举型参数源码中以Literal替代并在注释中提示此限制读者在使用时需注意参数取值必须严格匹配上述字面量。其单测见 test/toolkits/test_weather_function.py。4.3 SearchToolkit多引擎网页搜索SearchToolkit 是使用率最高的工具包之一覆盖 Google、DuckDuckGo、Wikipedia、Wolfram Alpha、Brave、Perplexity 等搜索渠道。其构造函数支持timeoutAPI 请求超时exclude_domains需要排除的域名列表当前仅search_google支持示例见 examples/toolkits/search_google_with_exclusion.py。典型方法包括toolkit SearchToolkit() tools toolkit.get_tools() # 一次性拿到全部搜索工具 google_tool FunctionTool(SearchToolkit().search_google) wiki_tool FunctionTool(SearchToolkit().search_wiki)search_serper(query, page10, locationUnited States)通过 Serper.dev 的 Google 搜索 API 实现需要环境变量SERPER_API_KEY源码用api_keys_required装饰器在调用前做密钥校验返回包含organic、peopleAlsoAsk等字段的结果字典search_wiki(entity)则依赖wikipedia包dependencies_required(wikipedia)返回实体页面的摘要文本。对应测试见 test/toolkits/test_search_functions.py。4.4 其他内置工具包速览CodeExecutionToolkit在内部 Python、Jupyter、Docker、subprocess、e2b 等沙箱中执行代码GitHubToolkit检索 issue、创建 pull request 等 GitHub 仓库操作GoogleMapsToolkit地址校验、海拔与时区数据OpenAPIToolkit把任意 OpenAPI 规范的 REST API 动态转为可用工具RetrievalToolkit基于本地向量库的检索RedditToolkit热帖收集、评论情感分析、关键词讨论追踪SlackToolkit / TwitterToolkit / LinkedInToolkit对应平台的发帖、删帖、资料查询与频道管理。完整的内置工具包列表含每个工具包的一句话职责说明请查阅 docs/key_modules/tools.md。五、把工具接入 ChatAgent工具包装配到 Agent 只需在初始化ChatAgent时传入tools列表ChatAgent 定义见 camel/agents/chat_agent.pyfrom camel.agents import ChatAgent tool_agent ChatAgent( toolstools, # List[FunctionTool] ) response tool_agent.step(A query related to the tool you added)需要ChatAgent实例的工具包如基于RegisteredAgentToolkit的消息代理类工具包则应通过toolkits_to_register_agent参数传入ChatAgent会自动完成注册。完整的单 Agent 工具示例见 examples/toolkits/function_tool_example.py角色扮演 函数调用示例见 examples/toolkits/role_playing_with_functions.py超时配置示例见 examples/toolkits/toolkit_timeout.py。六、把工具包变成 MCP Server分布式工具执行CAMEL 支持Model Context ProtocolMCP任何工具包都能作为独立的 MCP 服务器对外暴露客户端通过统一协议远程发现并调用工具。这一能力在BaseToolkit.run_mcp_server()与MCPServer()装饰器的配合下实现。6.1 启动 MCP Server以ArxivToolkit为例完整代码见 docs/key_modules/tools.md 中的「Expose a Toolkit as an MCP Server」一节import argparse import sys from camel.toolkits import ArxivToolkit if __name__ __main__: parser argparse.ArgumentParser( descriptionRun Arxiv Toolkit in MCP server mode., usagepython arxiv_mcp_server.py [--mode MODE] [--timeout TIMEOUT] ) parser.add_argument( --mode, choices[stdio, sse, streamable-http], defaultstdio, helpMCP server mode (default: stdio) ) parser.add_argument( --timeout, typefloat, defaultNone, helpTimeout in seconds (default: None) ) args parser.parse_args() toolkit ArxivToolkit(timeoutargs.timeout) toolkit.run_mcp_server(modeargs.mode)三种运行模式对应不同部署形态stdio适合本地进程间通信sse与streamable-http适合跨进程、跨主机的 HTTP 场景。CAMEL 的 MCP 集成文档参见 docs/mcp/ 目录。6.2 客户端配置与远程调用服务器侧可以用 JSON 配置文件描述启动方式commandargs定义进程拉起指令{ mcpServers: { arxiv_toolkit: { command: python, args: [ -m, examples.mcp_arxiv_toolkit.arxiv_toolkit_server, --timeout, 30 ] } } }注意args中的模块路径需要指向你实际的 MCP 服务器入口脚本本仓库的工具包示例集中位于 examples/toolkits/。客户端侧通过MCPToolkit连接并调用远程工具import asyncio from mcp.types import CallToolResult from camel.toolkits.mcp_toolkit import MCPToolkit, MCPClient async def run_example(): mcp_toolkit MCPToolkit(config_pathpath/to/mcp_servers_config.json) await mcp_toolkit.connect() mcp_client: MCPClient mcp_toolkit.servers[0] res await mcp_client.list_mcp_tools() if isinstance(res, str): raise Exception(res) tools [tool.name for tool in res.tools] print(fAvailable tools: {tools}) result: CallToolResult await mcp_client.session.call_tool( tool_name, {param1: value1, param2: value2} ) print(result.content[0].text) await mcp_toolkit.disconnect() if __name__ __main__: asyncio.run(run_example())6.3 MCP 化部署的收益与实践建议从官方文档与架构看将工具包部署为 MCP Server 带来的收益包括分布式执行工具可运行在任何机器或容器上、进程隔离每个工具包独立进程提升可靠性与安全性、资源管理为重型工具包分配独立内存/CPU、可伸缩性按负载单独扩容某个工具包以及语言互操作性任何支持 MCP 的语言都可实现服务器端。官方文档给出的生产级实践建议始终设置超时防止阻塞在服务端与客户端都实现健壮的异常处理结束任务后正确断开连接、释放资源用配置文件或环境变量管理部署参数为生产环境补充日志与健康检查。七、进一步探索源码、示例与测试核心源码camel/toolkits/base.py基类与超时机制、camel/toolkits/function_tool.pySchema 解析与工具调用、camel/toolkits/init.py工具包全量导出典型实现camel/toolkits/math_toolkit.py、camel/toolkits/weather_toolkit.py、camel/toolkits/search_toolkit.py示例程序examples/toolkits/ 目录下有 90 余个可直接运行的示例覆盖从function_tool_example.py、toolkit_timeout.py到各业务工具包的完整用法测试佐证test/toolkits/test_math_functions.py、test/toolkits/test_weather_function.py、test/toolkits/test_search_functions.py 等 80 余个测试文件验证了各工具包的实际行为配套文档docs/key_modules/tools.mdTools 用户指南与内置工具包总表、docs/mcp/MCP 集成系列文档、docs/camel.toolkits.rstAPI 参考索引。从最小的FunctionTool到自动加超时的BaseToolkit再到开箱即用的 100 余个内置工具包与一键 MCP Server 化camel.toolkits构成了 CAMEL 中「Agent 连接真实世界」的完整通路——掌握这套体系你就能为任意 Agent 快速注入搜索、计算、代码执行与外部系统集成能力。【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考