工具#

如需更详细的使用信息，请参阅我们的操作手册：Tools Cookbook

1. 概念#

工具作为接口，使LLM和智能体能够与世界互动。本质上，工具是一个具有名称、描述、输入参数和输出类型的函数。在本节中，我们将介绍CAMEL目前支持的工具，并解释如何定义您自己的工具和工具包。

工具： 工具类似于OpenAI函数，可以轻松转换为该格式。在CAMEL中，我们提供了多种常用工具，您可以直接使用。虽然内置工具非常有用，但您很可能需要定义自己的工具。本指南详细介绍了如何创建自定义工具。

工具包： 工具包是设计为协同工作的工具集合。

2. 开始使用#

要为您的智能体增强CAMEL工具的功能，首先安装我们的附加工具包：

pip install 'camel-ai[tools]'

在CAMEL中，工具是LLM可以调用的FunctionTool。

2.1 如何自定义您的工具？#

开发者可以轻松创建定制工具，以满足其代理的特定需求。以下是定义和使用自定义工具的方法：

示例：两数相加

首先，定义您的函数并使用FunctionTool进行封装

from camel.toolkits import FunctionTool

def add(a: int, b: int) -> int:
    r"""Adds two numbers.

    Args:
        a (int): The first number to be added.
        b (int): The second number to be added.

    Returns:
        integer: The sum of the two numbers.
    """
    return a + b

# Wrap the function with FunctionTool
add_tool = FunctionTool(add)

访问工具属性

一旦定义了你的工具，你可以使用内置方法来检查其属性：

获取函数的名称：

print(add_tool.get_function_name())

>>> add

获取该函数功能的描述：

print(add_tool.get_function_description())

>>> Adds two numbers.

获取OpenAI函数的模式表示：

print(add_tool.get_openai_function_schema())

>>> 
{'name': 'add',
 'description': 'Adds two numbers.',
 'parameters': {'properties': {'a': {'type': 'integer',
    'description': 'The first number to be added.'},
   'b': {'type': 'integer', 'description': 'The second number to be added.'}},
  'required': ['a', 'b'],
  'type': 'object'}}

检索工具架构，兼容OpenAI的结构：

print(add_tool.get_openai_tool_schema())

>>> 
{'type': 'function',
 'function': {'name': 'add',
  'description': 'Adds two numbers.',
  'parameters': {'properties': {'a': {'type': 'integer',
     'description': 'The first number to be added.'},
    'b': {'type': 'integer', 'description': 'The second number to be added.'}},
   'required': ['a', 'b'],
   'type': 'object'}}}

2.2 工具包#

工具包是为特定任务设计、需协同使用的工具集合。所有工具包都暴露一个get_tools方法，该方法会返回工具列表。因此您可以这样操作：

from camel.toolkits import SearchToolkit

# Initialize a toolkit
toolkit = SearchToolkit()

# Get list of tools
tools = toolkit.get_tools()

要使用工具包中的特定工具，您可以实现如下代码：

from camel.toolkits import FunctionTool, SearchToolkit

google_tool = FunctionTool(SearchToolkit().search_google)
wiki_tool = FunctionTool(SearchToolkit().search_wiki)

2.3 向`ChatAgent`传递工具#

通过在初始化时传递自定义工具来增强ChatAgent的功能。以下是具体操作方法：

from camel.agents import ChatAgent

# Initialize a ChatAgent with your custom tools
tool_agent = ChatAgent(
    tools=tools,
)

# Interact with the agent
response = tool_agent.step("A query related to the tool you added")

3. 内置工具包#

CAMEL提供了多种内置工具包，您可以立即使用。以下是可用工具包的完整列表：

工具包	描述
ArxivToolkit	一个用于与arXiv API交互以搜索和下载学术论文的工具包。
AskNewsToolkit	一个基于AskNews API的工具包，用于根据用户查询获取新闻、故事和其他内容。
AudioAnalysisToolkit	一个用于音频处理和分析的工具包，包括音频内容的转录和问答功能。
BrowserToolkit	一个用于浏览网页并与网页交互的工具包，包括浏览器模拟和内容提取功能。
CodeExecutionToolkit	一个用于代码执行的工具包，可以在各种沙箱环境中运行代码，包括内部Python、Jupyter、Docker、子进程或e2b。
DalleToolkit	一个使用OpenAI的DALL-E模型进行图像生成的工具包。
DappierToolkit	一个用于搜索实时数据并通过Dappier API获取新闻、金融、股市、体育、天气等关键领域AI推荐的工具包。
DataCommonsToolkit	一个用于从Data Commons知识图谱查询和检索数据的工具包，包括SPARQL查询、统计时间序列数据和属性分析。
ExcelToolkit	一个用于从Excel文件中提取和处理内容的工具包，包括转换为markdown表格。
FunctionTool	一个基础工具包，用于创建基于函数的工具，供OpenAI聊天模型调用，支持模式解析和合成。
FileWriteTool	一个用于创建、写入和修改文件中文本的工具包。
GitHubToolkit	一个用于与GitHub仓库交互的工具包，包括检索问题和创建拉取请求。
GoogleCalendarToolkit	一个用于在Google日历中创建、检索、更新和删除活动的工具包
GoogleMapsToolkit	一个用于访问Google地图服务的工具包，包括地址验证、海拔数据和时区信息。
GoogleScholarToolkit	一个用于从Google Scholar检索作者及其出版物信息的工具包。
HumanToolkit	一个用于促进AI系统中人机交互和反馈的工具包。
ImageAnalysisToolkit	一个利用视觉能力语言模型进行综合图像分析和理解的工具包。
LinkedInToolkit	一个用于LinkedIn操作的工具包，包括创建帖子、删除帖子和获取用户资料信息。
MathToolkit	一个用于执行基本数学运算（如加法、减法和乘法）的工具包。
MCPToolkit	一个用于通过模型上下文协议(MCP)与外部工具交互的工具包。
MemoryToolkit	用于保存、加载和清除ChatAgent记忆的工具包。
MeshyToolkit	用于处理3D网格数据和操作的工具包。
MinerUToolkit	一个使用MinerU API进行文档内容提取和处理的工具包，支持OCR、公式识别和表格检测。
NetworkXToolkit	一个使用NetworkX库进行图操作和分析的工具包。
NotionToolkit	一个用于通过Notion API从Notion页面和工作区检索信息的工具包。
OpenAPIToolkit	一个用于处理OpenAPI规范和REST API的工具包。
OpenBBToolkit	一个通过OpenBB平台访问和分析金融市场数据的工具包，包括股票、ETF、加密货币和经济指标。
PubMedToolkit	一个用于与PubMed的E-utilities API交互以访问MEDLINE数据的工具包。
RedditToolkit	一个用于Reddit操作的工具包，包括收集热门帖子、对评论进行情感分析以及追踪关键词讨论。
RetrievalToolkit	一个用于根据指定查询从本地向量存储系统中检索信息的工具包。
SearchToolkit	一个用于通过Google、DuckDuckGo、Wikipedia、Bing、BaiDu和Wolfram Alpha等各种搜索引擎执行网络搜索的工具包。
SemanticScholarToolkit	一个用于与Semantic Scholar API交互的工具包，用于从学术出版物中获取论文和作者数据。
SlackToolkit	一个用于Slack操作的工具包，包括创建频道、加入频道和管理频道成员。
StripeToolkit	一个用于通过Stripe处理支付和管理金融交易的工具包。
SymPyToolkit	一个使用SymPy进行符号计算的工具包，包括代数运算、微积分和线性代数。
TerminalToolkit	一个用于终端操作的工具包，例如按名称或内容搜索文件、执行shell命令以及跨多个操作系统管理终端会话。
TwitterToolkit	一个用于Twitter操作的工具包，包括创建推文、删除推文和检索用户个人资料信息。
VideoAnalysisToolkit	一个用于通过视觉语言模型分析视频内容的工具包，包括帧提取和关于视频内容的问答功能。
VideoDownloaderToolkit	一个用于下载视频并可选择将其分割成块的工具包，支持多种视频服务。
WeatherToolkit	一个使用OpenWeatherMap API获取城市天气数据的工具包。
WhatsAppToolkit	一个用于与WhatsApp商业API交互的工具包，包括发送消息、管理消息模板和访问商业资料信息。
ZapierToolkit	一个用于与Zapier的NLA API交互的工具包，可通过自然语言命令执行操作并自动化工作流程。

4. 使用工具包作为MCP服务器#

CAMEL支持模型上下文协议(MCP)，该协议允许您将工具包作为独立服务器暴露，供客户端访问。这实现了分布式工具执行以及与各种系统的集成。

4.1 什么是MCP？#

模型上下文协议(MCP)是一种使语言模型能够与外部工具和服务交互的协议。在CAMEL中，工具包可以作为MCP服务器暴露，允许客户端远程发现和调用工具。

4.2 从工具包创建MCP服务器#

任何CAMEL工具包都可以作为MCP服务器公开。以下是如何以ArXiv工具包为例创建MCP服务器：

# arxiv_toolkit_server.py
import argparse
import sys

from camel.toolkits import ArxivToolkit

if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="Run Arxiv Toolkit with MCP server mode.",
        usage=f"python {sys.argv[0]} [--mode MODE]",
    )
    parser.add_argument(
        "--mode",
        choices=["stdio", "sse"],
        default="stdio",
        help="MCP server mode (default: 'stdio')",
    )
    parser.add_argument(
        "--timeout",
        type=float,
        default=None,
        help="Timeout for the MCP server (default: None)",
    )

    args = parser.parse_args()

    toolkit = ArxivToolkit(timeout=args.timeout)

    # Run the toolkit as an MCP server
    toolkit.mcp.run(args.mode)

服务器可以运行在两种模式下：

stdio: 标准输入/输出模式（默认）
sse: 服务器发送事件模式

4.3 配置MCP服务器#

创建一个配置文件（例如 mcp_servers_config.json）来指定如何启动您的 MCP 服务器：

{
  "mcpServers": {
    "arxiv_toolkit": {
      "command": "python",
      "args": [
        "-m",
        "examples.mcp_arxiv_toolkit.arxiv_toolkit_server",
        "--timeout",
        "30"
      ]
    }
  }
}

4.4 从客户端连接MCP服务器#

您可以通过客户端应用程序连接到MCP服务器并使用其工具：

import asyncio
from mcp.types import CallToolResult
from camel.toolkits.mcp_toolkit import MCPToolkit, MCPClient

async def run_example():
    # Initialize the MCPToolkit with your configuration file
    mcp_toolkit = MCPToolkit(config_path="path/to/mcp_servers_config.json")

    # Connect to all configured MCP servers
    await mcp_toolkit.connect()

    # Get the first MCP server
    mcp_client: MCPClient = mcp_toolkit.servers[0]
    
    # List available tools from the server
    res = await mcp_client.list_mcp_tools()
    if isinstance(res, str):
        raise Exception(res)

    tools = [tool.name for tool in res.tools]
    print(f"Available tools: {tools}")

    # Call a tool from the server
    result: CallToolResult = await mcp_client.session.call_tool(
        "tool_name", {"param1": "value1", "param2": "value2"}
    )
    print(result.content[0].text)

    # Disconnect from all servers
    await mcp_toolkit.disconnect()

if __name__ == "__main__":
    asyncio.run(run_example())

4.5 使用MCP服务器的优势#

分布式执行: 在独立的机器或进程上运行工具。
隔离性: 每个工具包都在自己的进程中运行，提供更好的隔离性和稳定性。
资源管理: 根据各工具包的需求分配资源。
可扩展性: 根据需求独立扩展各个工具包。
语言互操作性: MCP服务器可以用不同的编程语言实现。

4.6 最佳实践#

超时设置: 始终设置适当的超时以防止操作挂起。
错误处理: 为服务器端和客户端实现适当的错误处理。
资源清理: 使用完成后确保正确断开与服务器的连接。
配置管理: 使用环境变量或配置文件进行服务器设置。
监控: 在生产环境中为MCP服务器实现日志记录和监控。

5. 结论#

工具对于扩展CAMEL代理的能力至关重要，使它们能够执行各种任务并高效协作。

工具

本页内容

工具#