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

Auto-update documentation after merge [skip ci]

camel-docs-bote6166175ab43
diff --git a/docs/key_modules/tools.md b/docs/key_modules/tools.md
index 3e274c7b9..c3042e488 100644
--- a/docs/key_modules/tools.md
+++ b/docs/key_modules/tools.md
@@ -28,7 +28,7 @@ A tool in CAMEL is just a <b>FunctionTool</b>—an interface any agent can call
<Card title="Define a Custom Tool" icon="toolbox">
You can easily create your own tools for any use case. Just write a Python function and wrap it using <b>FunctionTool</b>:
-<CodeBlock language="python" title="add_tool.py">
+```python add_tool.py lines icon="python"
from camel.toolkits import FunctionTool
def add(a: int, b: int) -> int:
@@ -36,7 +36,8 @@ def add(a: int, b: int) -> int:
return a + b
add_tool = FunctionTool(add)
-</CodeBlock>
+```
+
Inspect your tool’s properties—such as its name, description, and OpenAI-compatible schema—using built-in methods:
<CodeGroup>
@@ -58,35 +59,33 @@ Adds two numbers.
</Card>
<Card title="Using Toolkits" icon="screwdriver-wrench">
-Toolkits group related tools for specialized tasks—search, math, or automation. Use built-in toolkits or build your own.
+Toolkits group related tools for specialized tasks—search, math, or automation. Use built‑in toolkits or build your own:
-<CodeBlock language="python" title="toolkit_usage.py">
+```python toolkit_usage.py lines icon="python"
from camel.toolkits import SearchToolkit
toolkit = SearchToolkit()
-tools = toolkit.get_tools()
-</CodeBlock>
+tools = toolkit.get_tools()
+```
You can also wrap toolkit methods as individual FunctionTools:
-<CodeBlock language="python" title="custom_tools.py">
-from camel.toolkits import FunctionTool, SearchToolkit
+```python custom_tools.py lines icon="python"
+from camel.toolkits import FunctionTool, SearchToolkit
google_tool = FunctionTool(SearchToolkit().search_google)
-wiki_tool = FunctionTool(SearchToolkit().search_wiki)
-</CodeBlock>
+wiki_tool = FunctionTool(SearchToolkit().search_wiki)
+```
</Card>
<Card title="Passing Tools to ChatAgent" icon="user-cog">
You can enhance any <b>ChatAgent</b> with custom or toolkit-powered tools. Just pass the tools during initialization:
-<CodeBlock language="python" title="chatagent_tools.py">
+```python chatagent_tools.py lines icon="python"
from camel.agents import ChatAgent
-
tool_agent = ChatAgent(
tools=tools, # List of FunctionTools
)
-
response = tool_agent.step("A query related to the tool you added")
-</CodeBlock>
+```
</Card>
## Built-in Toolkits
@@ -152,42 +151,35 @@ MCP (Model Context Protocol) is a unified protocol for connecting LLMs with exte
</Card>
<Card title="Expose a Toolkit as an MCP Server" icon="rocket">
-Any CAMEL toolkit can run as an MCP server. Here’s how you can start an ArXiv toolkit server from a script:
+Any CAMEL toolkit can run as an MCP server. Example for ArxivToolkit:
-<CodeGroup>
-```python
+```python arxiv_mcp_server.py lines icon="python"
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] [--timeout TIMEOUT]",
+ description="Run Arxiv Toolkit in MCP server mode.",
+ usage="python arxiv_mcp_server.py [--mode MODE] [--timeout TIMEOUT]"
)
parser.add_argument(
"--mode",
choices=["stdio", "sse", "streamable-http"],
default="stdio",
- help="MCP server mode (default: 'stdio')",
+ help="MCP server mode (default: 'stdio')"
)
parser.add_argument(
"--timeout",
type=float,
default=None,
- help="Timeout for the MCP server (default: None)",
+ help="Timeout in seconds (default: None)"
)
-
args = parser.parse_args()
+
toolkit = ArxivToolkit(timeout=args.timeout)
toolkit.run_mcp_server(mode=args.mode)
- ```
-</CodeGroup>
-Supported modes:
-- <b>stdio</b>: Standard input/output (default)
-- <b>sse</b>: Server-Sent Events
-- <b>streamable-http</b>: Streamable HTTP
+```
</Card>
<Card title="MCP Server Configuration" icon="settings">
diff --git a/docs/mcp/connecting_existing_mcp_tools.md b/docs/mcp/connecting_existing_mcp_tools.md
new file mode 100644
index 000000000..dbedbe952
--- /dev/null
+++ b/docs/mcp/connecting_existing_mcp_tools.md
@@ -0,0 +1,155 @@
+---
+title: 'Connect to Existing MCP Tools in CAMEL ChatAgent'
+description: 'How to plug any MCP protocol tool (like file systems, web APIs) into your CAMEL ChatAgent for seamless tool-using agents.'
+icon: 'network'
+---
+
+## Overview
+
+You can connect any Model Context Protocol (MCP) tool—like the official filesystem server—directly to your CAMEL ChatAgent.
+This gives your agents natural language access to external filesystems, databases, or any MCP-compatible service.
+
+<Info>
+<strong>Use Case:</strong>
+Let your agent list files or read documents by wiring up the official MCP Filesystem server as a tool—no code changes to the agent required!
+</Info>
+
+<Steps>
+ <Step title="Install the MCP Tool Server">
+ You can use any MCP-compatible tool.
+ For this example, we'll use the <strong>official filesystem server</strong> from the Model Context Protocol community.
+ <br /><br />
+ Install globally using npm:
+ <br /><br />
+ ```bash Terminal
+ npm install -g @modelcontextprotocol/server-filesystem
+ ```
+ </Step>
+
+ <Step title="Start the MCP Tool Server">
+ Start the server in the directory you want to expose (e.g., your project root):
+ <br /><br />
+ ```bash Terminal
+ npx -y @modelcontextprotocol/server-filesystem .
+ ```
+ This limits all file operations to the current directory.
+ </Step>
+
+ <Step title="Connect MCP Tool Server to CAMEL">
+ Now, connect the MCP tool server to CAMEL using <code>MCPClient</code> or <code>MCPToolkit</code>.
+ <br /><br />
+ <strong>Direct Client Example (Async):</strong>
+ ```python mcp_filesystem_client.py lines icon="python"
+ import asyncio
+ from camel.utils.mcp_client import MCPClient
+
+ async def mcp_client_example():
+ config = {
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
+ }
+ async with MCPClient(config) as client:
+ mcp_tools = await client.list_mcp_tools()
+ print("Available MCP tools:", [tool.name for tool in mcp_tools.tools])
+ call_tool_result = await client.call_tool(
+ "list_directory", {"path": "."}
+ )
+ print("Directory Contents:")
+ for i, item in enumerate(call_tool_result.content[0].text.split('\n')):
+ if item.strip():
+ print(f" {item}")
+ if i >= 4:
+ break
+
+ asyncio.run(mcp_client_example())
+ ```
+ </Step>
+
+ <Step title="Integrate with CAMEL ChatAgent">
+ Add the tools exposed by the MCP server to your ChatAgent.
+ <br /><br />
+ <strong>Async Agent Integration:</strong>
+ ```python mcp_agent_integration.py lines icon="python"
+ import asyncio
+ from pathlib import Path
+ from camel.agents import ChatAgent
+ from camel.models import ModelFactory
+ from camel.toolkits import MCPToolkit
+ from camel.types import ModelPlatformType, ModelType
+
+ async def mcp_toolkit_example():
+ config_path = Path(__file__).parent / "mcp_servers_config.json"
+ async with MCPToolkit(config_path=str(config_path)) as mcp_toolkit:
+ sys_msg = "You are a helpful assistant"
+ model = ModelFactory.create(
+ model_platform=ModelPlatformType.DEFAULT,
+ model_type=ModelType.DEFAULT,
+ )
+ camel_agent = ChatAgent(
+ system_message=sys_msg,
+ model=model,
+ tools=[*mcp_toolkit.get_tools()],
+ )
+ user_msg = "List 5 files in the project, using relative paths"
+ response = await camel_agent.astep(user_msg)
+ print(response.msgs[0].content)
+ print(response.info['tool_calls'])
+
+ asyncio.run(mcp_toolkit_example())
+ ```
+ <br />
+ <strong>Config Example (<code>mcp_servers_config.json</code>):</strong>
+ ```json mcp_servers_config.json lines icon="settings"
+ {
+ "mcpServers": {
+ "filesystem": {
+ "command": "npx",
+ "args": [
+ "-y",
+ "@modelcontextprotocol/[email protected]",
+ "."
+ ]
+ }
+ },
+ "mcpWebServers": {}
+ }
+ ```
+ </Step>
+
+ <Step title="Sync Version (Optional)">
+ Use <code>step()</code> for synchronous execution:
+ <br /><br />
+ ```python mcp_agent_sync.py lines icon="python"
+ from pathlib import Path
+ from camel.agents import ChatAgent
+ from camel.models import ModelFactory
+ from camel.toolkits import MCPToolkit
+ from camel.types import ModelPlatformType, ModelType
+
+ def mcp_toolkit_example_sync():
+ config_path = Path(__file__).parent / "mcp_servers_config.json"
+ with MCPToolkit(config_path=str(config_path)) as mcp_toolkit:
+ sys_msg = "You are a helpful assistant"
+ model = ModelFactory.create(
+ model_platform=ModelPlatformType.DEFAULT,
+ model_type=ModelType.DEFAULT,
+ )
+ camel_agent = ChatAgent(
+ system_message=sys_msg,
+ model=model,
+ tools=[*mcp_toolkit.get_tools()],
+ )
+ user_msg = "List 5 files in the project, using relative paths"
+ response = camel_agent.step(user_msg)
+ print(response.msgs[0].content)
+ print(response.info['tool_calls'])
+
+ mcp_toolkit_example_sync()
+ ```
+ </Step>
+</Steps>
+
+<Info>
+That's it!
+Your CAMEL agent can now leverage any external tool (filesystem, APIs, custom scripts) that supports MCP. Plug and play!
+</Info>
diff --git a/docs/mintlify/reference/camel.toolkits.human_toolkit.mdx b/docs/mintlify/reference/camel.toolkits.human_toolkit.mdx
index 1f4d4e6bf..f98ff5cab 100644
--- a/docs/mintlify/reference/camel.toolkits.human_toolkit.mdx
+++ b/docs/mintlify/reference/camel.toolkits.human_toolkit.mdx
@@ -46,14 +46,14 @@ credentials, file paths).
### send_message_to_user
```python
-def send_message_to_user(self, message: str) -> str:
+def send_message_to_user(self, message: str):
```
Use this tool to send a tidy message to the user in one short
sentence.
This one-way tool keeps the user informed about your progress,
-decisions, or actions. It does not require a response from user.
+decisions, or actions. It does not require a response.
You should use it to:
- Announce what you are about to do (e.g., "I will now search for
papers on GUI Agents.").
@@ -66,6 +66,10 @@ papers.").
- **message** (str): The tidy and informative message for the user.
+**Returns:**
+
+ str: Confirmation that the message was successfully sent.
+
<a id="camel.toolkits.human_toolkit.HumanToolkit.get_tools"></a>
### get_tools