🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
feat: Add Klavis toolkit. (#2309)
Xiangkai Zeng14c9586311ac
diff --git a/.env b/.envindex 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 filediff --git a/camel/toolkits/__init__.py b/camel/toolkits/__init__.pyindex 7a8074f2d..1df14d274 100644--- a/camel/toolkits/__init__.py+++ b/camel/toolkits/__init__.py@@ -68,6 +68,7 @@ from .pyautogui_toolkit import PyAutoGUIToolkitfrom .openai_agent_toolkit import OpenAIAgentToolkitfrom .searxng_toolkit import SearxNGToolkitfrom .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.pynew file mode 100644index 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.pyindex 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.mdindex 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 Serversdiff --git a/examples/toolkits/klavis_toolkit.py b/examples/toolkits/klavis_toolkit.pynew file mode 100644index 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.pynew file mode 100644index 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]