Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

feat: Add Klavis toolkit. (#2309)

Xiangkai Zeng14c9586311ac
diff --git a/.env b/.env
index f44cea2a2..07cfe4c58 100644
--- a/.env
+++ b/.env
@@ -108,4 +108,7 @@
# BEDROCK_API_KEY="Fill your Secret Access Key here"
# Bocha Platform API(https://open.bochaai.com)
-# BOCHA_API_KEY="Fill your API key here"
\ No newline at end of file
+# BOCHA_API_KEY="Fill your API key here"
+
+# Klavis AI API (https://www.klavis.ai)
+# KLAVIS_API_KEY="Fill your API key here"
\ No newline at end of file
diff --git a/camel/toolkits/__init__.py b/camel/toolkits/__init__.py
index 7a8074f2d..1df14d274 100644
--- a/camel/toolkits/__init__.py
+++ b/camel/toolkits/__init__.py
@@ -68,6 +68,7 @@ from .pyautogui_toolkit import PyAutoGUIToolkit
from .openai_agent_toolkit import OpenAIAgentToolkit
from .searxng_toolkit import SearxNGToolkit
from .jina_reranker_toolkit import JinaRerankerToolkit
+from .klavis_toolkit import KlavisToolkit
__all__ = [
@@ -124,4 +125,5 @@ __all__ = [
'OpenAIAgentToolkit',
'SearxNGToolkit',
'JinaRerankerToolkit',
+ 'KlavisToolkit',
]
diff --git a/camel/toolkits/klavis_toolkit.py b/camel/toolkits/klavis_toolkit.py
new file mode 100644
index 000000000..172403f3f
--- /dev/null
+++ b/camel/toolkits/klavis_toolkit.py
@@ -0,0 +1,228 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import os
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from camel.logger import get_logger
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+from camel.utils import MCPServer, api_keys_required, dependencies_required
+
+logger = get_logger(__name__)
+
+
+@MCPServer()
+class KlavisToolkit(BaseToolkit):
+ r"""A class representing a toolkit for interacting with Klavis API.
+
+ This class provides methods for interacting with Klavis MCP server
+ instances, retrieving server information, managing tools, and handling
+ authentication.
+
+ Attributes:
+ api_key (str): The API key for authenticating with Klavis API.
+ base_url (str): The base URL for Klavis API endpoints.
+ timeout (Optional[float]): The timeout value for API requests
+ in seconds. If None, no timeout is applied.
+ (default: :obj:`None`)
+ """
+
+ @dependencies_required("requests")
+ @api_keys_required(
+ [
+ (None, "KLAVIS_API_KEY"),
+ ]
+ )
+ def __init__(self, timeout: Optional[float] = None) -> None:
+ r"""Initialize the KlavisToolkit with API client. The API key is
+ retrieved from environment variables.
+ """
+ super().__init__(timeout=timeout)
+ self.api_key = os.environ.get("KLAVIS_API_KEY")
+ self.base_url = "https://api.klavis.ai"
+
+ def _request(
+ self,
+ method: str,
+ endpoint: str,
+ payload: Optional[Dict[str, Any]] = None,
+ additional_headers: Optional[Dict[str, str]] = None,
+ ) -> Dict[str, Any]:
+ r"""Make an HTTP request to the Klavis API.
+
+ Args:
+ method (str): HTTP method (e.g., 'GET', 'POST', 'DELETE').
+ endpoint (str): API endpoint path.
+ payload (Optional[Dict[str, Any]]): JSON payload for POST
+ requests.
+ additional_headers (Optional[Dict[str, str]]): Additional
+ headers to include in the request.
+
+ Returns:
+ Dict[str, Any]: The JSON response from the API or an error
+ dict.
+ """
+ url = f"{self.base_url}{endpoint}"
+ headers = {
+ 'accept': 'application/json',
+ 'Authorization': f'Bearer {self.api_key}',
+ }
+ if additional_headers:
+ headers.update(additional_headers)
+
+ logger.debug(
+ f"Making {method} request to {url} with payload: {payload}"
+ )
+
+ try:
+ response = requests.request(
+ method,
+ url,
+ headers=headers,
+ json=payload,
+ timeout=self.timeout,
+ )
+ response.raise_for_status()
+ return response.json()
+ except requests.exceptions.RequestException as e:
+ logger.error(f"Request failed for {method} {endpoint}: {e!s}")
+ return {"error": f"Request failed: {e!s}"}
+ except ValueError:
+ logger.error(f"Response for {method} {endpoint} is not valid JSON")
+ return {"error": "Response is not valid JSON"}
+
+ def create_server_instance(
+ self, server_name: str, user_id: str, platform_name: str
+ ) -> Dict[str, Any]:
+ r"""Create a Server-Sent Events (SSE) URL for a specified MCP server.
+
+ Args:
+ server_name (str): The name of the target MCP server.
+ user_id (str): The ID for the user requesting the server URL.
+ platform_name (str): The name of the platform associated
+ with the user.
+
+ Returns:
+ Dict[str, Any]: Response containing the server instance details.
+ """
+ endpoint = "/mcp-server/instance/create"
+ payload = {
+ "serverName": server_name,
+ "userId": user_id,
+ "platformName": platform_name,
+ }
+ headers = {'Content-Type': 'application/json'}
+ return self._request(
+ 'POST', endpoint, payload=payload, additional_headers=headers
+ )
+
+ def get_server_instance(self, instance_id: str) -> Dict[str, Any]:
+ r"""Get details of a specific server connection instance.
+
+ Args:
+ instance_id (str): The ID of the connection instance whose status
+ is being checked.
+
+ Returns:
+ Dict[str, Any]: Details about the server instance.
+ """
+ endpoint = f"/mcp-server/instance/get/{instance_id}"
+ return self._request('GET', endpoint)
+
+ def delete_auth_data(self, instance_id: str) -> Dict[str, Any]:
+ r"""Delete authentication metadata for a specific server
+ connection instance.
+
+ Args:
+ instance_id (str): The ID of the connection instance to
+ delete auth for.
+
+ Returns:
+ Dict[str, Any]: Status response for the operation.
+ """
+ endpoint = f"/mcp-server/instance/delete-auth/{instance_id}"
+ return self._request('DELETE', endpoint)
+
+ def delete_server_instance(self, instance_id: str) -> Dict[str, Any]:
+ r"""Completely removes a server connection instance.
+
+ Args:
+ instance_id (str): The ID of the connection instance to delete.
+
+ Returns:
+ Dict[str, Any]: Status response for the operation.
+ """
+ endpoint = f"/mcp-server/instance/delete/{instance_id}"
+ return self._request('DELETE', endpoint)
+
+ def get_server_tools(self, server_name: str) -> Dict[str, Any]:
+ r"""Get list of tool names for a specific MCP server.
+
+ Args:
+ server_name (str): The name of the target MCP server.
+
+ Returns:
+ Dict[str, Any]: List of tools available for the specified server.
+ """
+ endpoint = f"/mcp-server/tools/{server_name}"
+ return self._request('GET', endpoint)
+
+ def get_all_servers(self) -> Dict[str, Any]:
+ r"""Get all MCP servers with their basic information.
+
+ Returns:
+ Dict[str, Any]: Information about all available MCP servers.
+ """
+ endpoint = "/mcp-server/servers"
+ return self._request('GET', endpoint)
+
+ def set_auth_token(
+ self, instance_id: str, auth_token: str
+ ) -> Dict[str, Any]:
+ r"""Sets an authentication token for a specific instance.
+
+ Args:
+ instance_id (str): The ID for the connection instance.
+ auth_token (str): The authentication token to save.
+
+ Returns:
+ Dict[str, Any]: Status response for the operation.
+ """
+ endpoint = "/mcp-server/instance/set-auth-token"
+ payload = {"instanceId": instance_id, "authToken": auth_token}
+ headers = {'Content-Type': 'application/json'}
+ return self._request(
+ 'POST', endpoint, payload=payload, additional_headers=headers
+ )
+
+ def get_tools(self) -> List[FunctionTool]:
+ r"""Returns a list of FunctionTool objects representing the functions
+ in the toolkit.
+
+ Returns:
+ List[FunctionTool]: A list of FunctionTool objects representing
+ the functions in the toolkit.
+ """
+ return [
+ FunctionTool(self.create_server_instance),
+ FunctionTool(self.get_server_instance),
+ FunctionTool(self.delete_auth_data),
+ FunctionTool(self.delete_server_instance),
+ FunctionTool(self.get_server_tools),
+ FunctionTool(self.get_all_servers),
+ FunctionTool(self.set_auth_token),
+ ]
diff --git a/camel/utils/commons.py b/camel/utils/commons.py
index 96bd4fa80..285d66785 100644
--- a/camel/utils/commons.py
+++ b/camel/utils/commons.py
@@ -352,6 +352,8 @@ def api_keys_required(
key_way = "https://platform.lingyiwanwu.com/docs"
elif env_var_name == 'ZHIPUAI_API_KEY':
key_way = "https://www.zhipuai.cn/"
+ elif env_var_name == 'KLAVIS_API_KEY':
+ key_way = "https://www.klavis.ai/docs"
if missing_keys:
raise ValueError(
diff --git a/docs/key_modules/tools.md b/docs/key_modules/tools.md
index 1e383e69f..31c49ac2b 100644
--- a/docs/key_modules/tools.md
+++ b/docs/key_modules/tools.md
@@ -192,6 +192,7 @@ CAMEL provides a variety of built-in toolkits that you can use right away. Here'
| WeatherToolkit | A toolkit for fetching weather data for cities using the OpenWeatherMap API. |
| WhatsAppToolkit | A toolkit for interacting with the WhatsApp Business API, including sending messages, managing message templates, and accessing business profile information. |
| ZapierToolkit | A toolkit for interacting with Zapier's NLA API to execute actions through natural language commands and automate workflows. |
+| KlavisToolkit | A toolkit for interacting with Kavis AI's API to create remote hosted production-ready MCP servers. |
## 4. Using Toolkits as MCP Servers
diff --git a/examples/toolkits/klavis_toolkit.py b/examples/toolkits/klavis_toolkit.py
new file mode 100644
index 000000000..5abb0cf99
--- /dev/null
+++ b/examples/toolkits/klavis_toolkit.py
@@ -0,0 +1,126 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+from camel.agents import ChatAgent
+from camel.configs.openai_config import ChatGPTConfig
+from camel.models import ModelFactory
+from camel.toolkits import KlavisToolkit
+from camel.types import ModelPlatformType, ModelType
+
+# Define system message
+sys_msg = """You are a helpful AI assistant that can use Klavis API tools
+to manage MCP server instances and perform various server-related tasks.
+When using tools, first list the available servers using get_all_servers,
+then use the appropriate tool based on the task. Always provide clear
+explanations of what you're doing."""
+
+# Set model config
+tools = KlavisToolkit().get_tools()
+model_config_dict = ChatGPTConfig(
+ temperature=0.0,
+).as_dict()
+
+model = ModelFactory.create(
+ model_platform=ModelPlatformType.DEFAULT,
+ model_type=ModelType.DEFAULT,
+ model_config_dict=model_config_dict,
+)
+
+# Set agent
+camel_agent = ChatAgent(
+ system_message=sys_msg,
+ model=model,
+ tools=tools,
+)
+camel_agent.reset()
+
+# First, list all available servers
+usr_msg = "List all available MCP servers."
+response = camel_agent.step(usr_msg)
+print("Available MCP Servers:")
+print(response.msg.content)
+print("\n" + "=" * 80 + "\n")
+
+# Create a new server instance
+usr_msg = """Now, create a new Klavis AI MCP server instance.
+Use the server name 'GitHub', user ID 'user123', and platform
+name '<your-platform-name>'."""
+response = camel_agent.step(usr_msg)
+print("Server Instance Creation Result:")
+print(response.msg.content)
+print("\n" + "=" * 80 + "\n")
+
+# Get details about the created server instance
+usr_msg = """Get details about the server instance we just created.
+Use the instance_id returned from the previous response."""
+response = camel_agent.step(usr_msg)
+print("Server Instance Details:")
+print(response.msg.content)
+
+"""
+Expected output would show:
+1. **Markdown2doc**
+ - **Description:** Convert markdown text to different file
+ formats (pdf, docx, doc, html), based on Pandoc.
+ - **Tools:**
+ - Convert markdown text to different file formats (pdf, docx,
+ doc, html, html5)
+
+2. **Discord**
+ - **Description:** Discord is a VoIP and instant messaging
+ social platform.
+ - **Tools:**
+ - Get information about a Discord server (guild)
+ - Get a list of members in a server
+ - Create a new text channel
+ - Add a reaction emoji to a message
+ - Send a text message to a specific Discord channel
+ - Read recent messages from a Discord channel
+
+3. **YouTube**
+ - **Description:** Extract and convert YouTube video information to
+ markdown format.
+ - **Tools:**
+ - Retrieve the transcript/subtitles for a YouTube video and convert
+ it to markdown
+
+.....
+
+========================================================================
+
+Server Instance Creation Result:
+A new Klavis AI MCP server instance has been successfully created for the
+server named **GitHub**. Here are the details:
+
+- **Server URL:** [https://github-mcp-server.klavis.ai/sse?instance_id=
+{instance_id}](https://github-mcp-server.klavis.ai/sse?instance_id={instance_id})
+- **Instance ID:** {instance_id}
+
+You can use this URL to connect to the server instance. If you need any further
+assistance or actions, feel free to ask!
+
+=========================================================================
+
+Server Instance Details:
+Here are the details about the server instance we just created:
+
+- **Instance ID:** {instance_id}
+- **Server Name:** GitHub
+- **Platform:** `<your-platform-name>`
+- **External User ID:** user123
+- **Is Authenticated:** No
+
+The instance is currently not authenticated. If you need to set an
+authentication token or perform any other actions, please let me know!
+"""
diff --git a/test/toolkits/test_klavis_toolkit.py b/test/toolkits/test_klavis_toolkit.py
new file mode 100644
index 000000000..d223b844b
--- /dev/null
+++ b/test/toolkits/test_klavis_toolkit.py
@@ -0,0 +1,249 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from unittest.mock import MagicMock, patch
+
+import pytest
+import requests
+
+from camel.toolkits import FunctionTool, KlavisToolkit
+
+
+# Fixture for mocking environment variables
+def mock_env_api_key(monkeypatch):
+ monkeypatch.setenv("KLAVIS_API_KEY", "test_api_key")
+
+
+# Fixture for KlavisToolkit instance
+def klavis_toolkit(mock_env_api_key):
+ # Patch requests dependency during initialization
+ with patch('requests.request'):
+ toolkit = KlavisToolkit(timeout=10.0)
+ return toolkit
+
+
+# Fixture for mocking requests.request
+def mock_requests():
+ with patch('requests.request') as mock_req:
+ yield mock_req
+
+
+# --------------------------
+# Test __init__ method
+# --------------------------
+def test_init(klavis_toolkit):
+ assert klavis_toolkit.api_key == "test_api_key"
+ assert klavis_toolkit.base_url == "https://api.klavis.ai"
+ assert klavis_toolkit.timeout == 10.0
+
+
+# --------------------------
+# Test _request method
+# --------------------------
+def test_request_success(klavis_toolkit, mock_requests):
+ mock_response = MagicMock()
+ mock_response.raise_for_status.return_value = None
+ mock_response.json.return_value = {"status": "success"}
+ mock_requests.return_value = mock_response
+
+ result = klavis_toolkit._request('GET', '/test-endpoint')
+
+ mock_requests.assert_called_once_with(
+ 'GET',
+ 'https://api.klavis.ai/test-endpoint',
+ headers={
+ 'accept': 'application/json',
+ 'Authorization': 'Bearer test_api_key',
+ },
+ json=None,
+ timeout=10.0,
+ )
+ assert result == {"status": "success"}
+
+
+def test_request_with_payload_and_headers(klavis_toolkit, mock_requests):
+ mock_response = MagicMock()
+ mock_response.raise_for_status.return_value = None
+ mock_response.json.return_value = {"status": "posted"}
+ mock_requests.return_value = mock_response
+
+ payload = {"key": "value"}
+ headers = {"X-Custom": "Header"}
+ result = klavis_toolkit._request(
+ 'POST', '/post-endpoint', payload=payload, additional_headers=headers
+ )
+
+ expected_headers = {
+ 'accept': 'application/json',
+ 'Authorization': 'Bearer test_api_key',
+ 'X-Custom': 'Header',
+ }
+ mock_requests.assert_called_once_with(
+ 'POST',
+ 'https://api.klavis.ai/post-endpoint',
+ headers=expected_headers,
+ json=payload,
+ timeout=10.0,
+ )
+ assert result == {"status": "posted"}
+
+
+def test_request_http_error(klavis_toolkit, mock_requests):
+ mock_response = MagicMock()
+ http_error = requests.exceptions.HTTPError("404 Client Error: Not Found")
+ mock_response.raise_for_status.side_effect = http_error
+ mock_requests.return_value = mock_response
+
+ result = klavis_toolkit._request('GET', '/not-found')
+
+ assert "error" in result
+ assert "Request failed: 404 Client Error: Not Found" in result["error"]
+
+
+def test_request_connection_error(klavis_toolkit, mock_requests):
+ connection_error = requests.exceptions.ConnectionError(
+ "Connection timed out"
+ )
+ mock_requests.side_effect = connection_error
+
+ result = klavis_toolkit._request('GET', '/timeout-endpoint')
+
+ assert "error" in result
+ assert "Request failed: Connection timed out" in result["error"]
+
+
+def test_request_non_json_response(klavis_toolkit, mock_requests):
+ mock_response = MagicMock()
+ mock_response.raise_for_status.return_value = None
+ mock_response.json.side_effect = ValueError(
+ "No JSON object could be decoded"
+ )
+ mock_requests.return_value = mock_response
+
+ result = klavis_toolkit._request('GET', '/bad-json')
+
+ assert result == {"error": "Response is not valid JSON"}
+
+
+# --------------------------
+# Test public methods calling _request
+# --------------------------
[email protected](KlavisToolkit, '_request')
+def test_create_server_instance(mock_request, klavis_toolkit):
+ mock_request.return_value = {"instanceId": "inst-123"}
+ result = klavis_toolkit.create_server_instance(
+ "test-server", "user-abc", "platform-xyz"
+ )
+ expected_payload = {
+ "serverName": "test-server",
+ "userId": "user-abc",
+ "platformName": "platform-xyz",
+ }
+ expected_headers = {'Content-Type': 'application/json'}
+ mock_request.assert_called_once_with(
+ 'POST',
+ '/mcp-server/instance/create',
+ payload=expected_payload,
+ additional_headers=expected_headers,
+ )
+ assert result == {"instanceId": "inst-123"}
+
+
[email protected](KlavisToolkit, '_request')
+def test_get_server_instance(mock_request, klavis_toolkit):
+ mock_request.return_value = {"status": "active"}
+ result = klavis_toolkit.get_server_instance("inst-123")
+ mock_request.assert_called_once_with(
+ 'GET', '/mcp-server/instance/get/inst-123'
+ )
+ assert result == {"status": "active"}
+
+
[email protected](KlavisToolkit, '_request')
+def test_delete_auth_data(mock_request, klavis_toolkit):
+ mock_request.return_value = {"status": "deleted"}
+ result = klavis_toolkit.delete_auth_data("inst-123")
+ mock_request.assert_called_once_with(
+ 'DELETE', '/mcp-server/instance/delete-auth/inst-123'
+ )
+ assert result == {"status": "deleted"}
+
+
[email protected](KlavisToolkit, '_request')
+def test_delete_server_instance(mock_request, klavis_toolkit):
+ mock_request.return_value = {"status": "instance deleted"}
+ result = klavis_toolkit.delete_server_instance("inst-123")
+ mock_request.assert_called_once_with(
+ 'DELETE', '/mcp-server/instance/delete/inst-123'
+ )
+ assert result == {"status": "instance deleted"}
+
+
[email protected](KlavisToolkit, '_request')
+def test_get_server_tools(mock_request, klavis_toolkit):
+ mock_request.return_value = {"tools": ["tool1", "tool2"]}
+ result = klavis_toolkit.get_server_tools("test-server")
+ mock_request.assert_called_once_with(
+ 'GET', '/mcp-server/tools/test-server'
+ )
+ assert result == {"tools": ["tool1", "tool2"]}
+
+
[email protected](KlavisToolkit, '_request')
+def test_get_all_servers(mock_request, klavis_toolkit):
+ mock_request.return_value = {"servers": [{"name": "server1"}]}
+ result = klavis_toolkit.get_all_servers()
+ mock_request.assert_called_once_with('GET', '/mcp-server/servers')
+ assert result == {"servers": [{"name": "server1"}]}
+
+
[email protected](KlavisToolkit, '_request')
+def test_set_auth_token(mock_request, klavis_toolkit):
+ mock_request.return_value = {"status": "token set"}
+ result = klavis_toolkit.set_auth_token("inst-123", "auth-token-xyz")
+ expected_payload = {
+ "instanceId": "inst-123",
+ "authToken": "auth-token-xyz",
+ }
+ expected_headers = {'Content-Type': 'application/json'}
+ mock_request.assert_called_once_with(
+ 'POST',
+ '/mcp-server/instance/set-auth-token',
+ payload=expected_payload,
+ additional_headers=expected_headers,
+ )
+ assert result == {"status": "token set"}
+
+
+# --------------------------
+# Test get_tools method
+# --------------------------
+def test_get_tools(klavis_toolkit):
+ tools = klavis_toolkit.get_tools()
+ assert len(tools) == 7
+ expected_func_names = [
+ 'create_server_instance',
+ 'get_server_instance',
+ 'delete_auth_data',
+ 'delete_server_instance',
+ 'get_server_tools',
+ 'get_all_servers',
+ 'set_auth_token',
+ ]
+ for i, tool in enumerate(tools):
+ assert isinstance(tool, FunctionTool)
+ # Check if the function name matches the expected name
+ assert tool.func.__name__ == expected_func_names[i]