python examples/workforce/multiple_single_agents.py
BaseAgent abstract class, which defines two essential methods:
| Method | Purpose | Description |
|-------------|---------------------|----------------------------------------------|
| reset() | State Management | Resets the agent to its initial state |
| step() | Task Execution | Performs a single step of the agent's operation |
## Types
### ChatAgent
The `ChatAgent` is the primary implementation that handles conversations with language models. It supports:
- System message configuration for role definition
- Memory management for conversation history
- Tool/function calling capabilities
- Response formatting and structured outputs
- Multiple model backend support with scheduling strategies
- Async operation support
search_limit: Maximum number of search iterations (default: 100)generator_agent: Specialized agent for answer generationverifier_agent: Specialized agent for answer verificationgolden_answers: Pre-defined correct answers for validationagent: ChatAgent instance for generating instructionsseed: Path to human-written seed tasks in JSONL formatnum_machine_instructions: Number of machine-generated instructions (default: 5)data_output_path: Path for saving generated data (default: ./data_output.json)human_to_machine_ratio: Ratio of human to machine tasks (default: (6, 2))instruction_filter: Custom InstructionFilter instance (optional)filter_config: Configuration dictionary for default filters (optional)seed: Random seed for reproducibilitymin_length: Minimum text length for processingmax_length: Maximum text length for processingcomplexity_threshold: Minimum complexity score (0.0–1.0)dataset_size: Target size for the final datasetuse_ai_model: Toggle between AI model and rule-based generationhop_generating_agent: Custom MultiHopGeneratorAgent (optional)max_iterations: Maximum number of improvement iterations (default: 3)score_threshold: Minimum quality thresholds for evaluation dimensions (default: 0.7)few_shot_examples: (Optional) Examples for few-shot learningoutput_path: (Optional) Path for saving generated resultsUnstructured IO module, just import and initialize it. You can parse, clean, extract, chunk, and stage data from files or URLs. Here’s how you use it step by step:
Unstructured IO. For more, see the Unstructured IO Documentation.
"completed", the content extraction is done and you can retrieve the results.
Taicheng Guo 1 , Xiuying Chen 2 , Yaqi Wang 3 \u2217 , Ruidi Chang , Shichao Pei 4 , Nitesh V. Chawla 1 , Olaf Wiest 1 , Xiangliang Zhang 1 \u2020
", "markdown": "Taicheng Guo 1 , Xiuying Chen 2 , Yaqi Wang 3 \u2217 , Ruidi Chang , Shichao Pei 4 , Nitesh V. Chawla 1 , Olaf Wiest 1 , Xiangliang Zhang 1 \u2020\n\n" } ], "chunk_length": 100 } ] } } ```BaseMessage class is the backbone for all message objects in
the CAMEL chat system. It offers a consistent structure for agent
communication and easy conversion between message types.
BaseMessage instance, supply these arguments:
RoleType.ASSISTANT or RoleType.USERBaseMessage class lets you:
new_message = message.create_new_instance("new test content")
openai_message =
message.to_openai_message(role_at_backend=OpenAIBackendRole.USER)
openai_system_message = message.to_openai_system_message()
openai_user_message = message.to_openai_user_message()
openai_assistant_message = message.to_openai_assistant_message()
message_dict = message.to_dict()
BaseMessage into the
right format for different LLM APIs and agent flows.
BaseMessage class is essential for structured, clear, and
flexible communication in the CAMEL-AI ecosystem—making it simple to create,
convert, and handle messages across any workflow.
Llama3ModelFile:
```
FROM llama3
PARAMETER temperature 0.8
PARAMETER stop Result
SYSTEM """ """
```
You can also create a shell script setup_llama3.sh:
```bash
#!/bin/zsh
model_name="llama3"
custom_model_name="camel-llama3"
ollama pull $model_name
ollama create $custom_model_name -f ./Llama3ModelFile
chmod +x setup_llama3.sh
./setup_llama3.sh
```
add(funcs): Register one or more FunctionTool objects for execution
- reset(): Reset the runtime to its initial state
- get_tools(): List all tools managed by the runtime
## Quick Start Example: RemoteHttpRuntime
PYTHON_EXECUTABLE, PYTHONPATH, and more for custom envsFunctionTool-style tool functions.
For agent-level, dynamic code execution, always consider dedicated sandboxing—such as UbuntuDockerRuntime’s exec_python_file()—for running dynamically generated scripts with maximum isolation and safety.
---
---
title: "Societies"
description: "Collaborative agent frameworks in CAMEL: autonomous social behaviors, role-based task solving, and turn-based agent societies."
icon: people-group
---
<ASSISTANT_ROLE>, I am <USER_ROLE>Solution: <YOUR_SOLUTION>Next request.| Attribute | Type | Description |
|---|---|---|
| assistant_role_name | str | Name of assistant's role |
| user_role_name | str | Name of user's role |
| critic_role_name | str | Name of critic's role (optional) |
| task_prompt | str | Prompt for the main task |
| with_task_specify | bool | Enable task specification agent |
| with_task_planner | bool | Enable task planner agent |
| with_critic_in_the_loop | bool | Include critic in conversation loop |
| critic_criteria | str | How the critic scores/evaluates outputs |
| model | BaseModelBackend | Model backend for responses |
| task_type | TaskType | Type/category of the task |
| assistant_agent_kwargs | Dict | Extra options for assistant agent |
| user_agent_kwargs | Dict | Extra options for user agent |
| task_specify_agent_kwargs | Dict | Extra options for task specify agent |
| task_planner_agent_kwargs | Dict | Extra options for task planner agent |
| critic_kwargs | Dict | Extra options for critic agent |
| sys_msg_generator_kwargs | Dict | Options for system message generator |
| extend_sys_msg_meta_dicts | List[Dict] | Extra metadata for system messages |
| extend_task_specify_meta_dict | Dict | Extra metadata for task specification |
| output_language | str | Target output language |
| assistant_agent | ChatAgent | Custom ChatAgent to use as assistant (optional) |
| user_agent | ChatAgent | Custom ChatAgent to use as user (optional) |
with_task_specify and with_task_planner options for highly complex tasks.[examples/society/](https://github.com/camel-ai/camel/tree/master/examples/runtimes) in the CAMEL repo for advanced agent society demos.RolePlaying — Advanced turn-taking, prompt-guarded collaboration (most common for LLM societies).BabyAGI — Autonomous, open-ended R&D loops for big-picture or research goals.<ASSISTANT_ROLE>, I am <USER_ROLE>Solution: <YOUR_SOLUTION>Next request.| Attribute | Type | Description |
|---|---|---|
| assistant_role_name | str | Name of assistant's role |
| user_role_name | str | Name of user's role |
| critic_role_name | str | Name of critic's role (optional) |
| task_prompt | str | Prompt for the main task |
| with_task_specify | bool | Enable task specification agent |
| with_task_planner | bool | Enable task planner agent |
| with_critic_in_the_loop | bool | Include critic in conversation loop |
| critic_criteria | str | How the critic scores/evaluates outputs |
| model | BaseModelBackend | Model backend for responses |
| task_type | TaskType | Type/category of the task |
| assistant_agent_kwargs | Dict | Extra options for assistant agent |
| user_agent_kwargs | Dict | Extra options for user agent |
| task_specify_agent_kwargs | Dict | Extra options for task specify agent |
| task_planner_agent_kwargs | Dict | Extra options for task planner agent |
| critic_kwargs | Dict | Extra options for critic agent |
| sys_msg_generator_kwargs | Dict | Options for system message generator |
| extend_sys_msg_meta_dicts | List[Dict] | Extra metadata for system messages |
| extend_task_specify_meta_dict | Dict | Extra metadata for task specification |
| output_language | str | Target output language |
with_task_specify and with_task_planner options for highly complex tasks.[examples/society/](https://github.com/camel-ai/camel/tree/master/examples/runtimes) in the CAMEL repo for advanced agent society demos.sse or streamable-http for ACI.dev, pick whichever is supported by your agent/server.
SearchToolkit, MathToolkit), they all work the same way!
```python
from camel.toolkits import ArxivToolkit
import argparse
parser = argparse.ArgumentParser(
description="Run Arxiv Toolkit as an MCP server."
)
parser.add_argument(
"--mode",
choices=["stdio", "sse", "streamable-http"],
default="stdio",
help="Select MCP server mode."
)
args = parser.parse_args()
toolkit = ArxivToolkit()
toolkit.mcp.run(args.mode)
```
- **stdio:** For local IPC (default, fast and secure for single-machine setups)
- **sse:** Server-Sent Events (good for remote servers and web clients)
- **streamable-http:** Modern, high-performance HTTP streaming
### Discoverable & Usable Instantly
Once running, your MCP server will:
- Advertise all available toolkit methods as standard MCP tools
- Support dynamic tool discovery (`tools/list` endpoint)
- Allow any compatible agent or client (not just CAMEL) to connect and call your tools
This means you can build an LLM workflow where, for example, Claude running in your browser or another service in your company network can call your toolkit directly—without ever importing your Python code.
MCPClient or MCPToolkit.
mcp_servers_config.json):
```json mcp_servers_config.json lines icon="settings"
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem@2025.1.14",
"."
]
}
},
"mcpWebServers": {}
}
```
step() for synchronous execution:
services/.
Configure your MCP client (Claude, Cursor, etc.) to connect:
```json mcp_servers_config.json Example highlight={5}
{
"camel-chat-agent": {
"command": "/path/to/python",
"args": [
"/path/to/camel/services/agent_mcp_server.py"
],
"env": {
"OPENAI_API_KEY": "...",
"OPENROUTER_API_KEY": "...",
"BRAVE_API_KEY": "..."
}
}
}
```
ChatAgent into an MCP server instantly with to_mcp():
```python agent_mcp_server.py lines icon="python"
from camel.agents import ChatAgent
# Create a chat agent with your model
agent = ChatAgent(model="gpt-4o-mini")
# Convert to an MCP server
mcp_server = agent.to_mcp(
name="demo", description="A demonstration of ChatAgent to MCP conversion"
)
if __name__ == "__main__":
print("Starting MCP server on http://localhost:8000")
mcp_server.run(transport="streamable-http")
```
stdio, sse, streamable-http
## What Changes with MCP?
## Why introduce MCP?
- **Ecosystem**: Leverage a growing library of MCP plugins—just plug them in.
- **Uniformity**: Not limited to any one model or vendor; if your agent supports MCP, you can swap models/tools anytime.
- **Data Security**: Keep sensitive data on your device. MCP servers decide what to expose—your private data never needs to leave your machine.
## MCP Architecture and Principles
**Basic Architecture**
MCP follows a **client-server model** with three main roles:
Please review the attached document.
", cc="manager@example.com", attachments=["/path/to/document.pdf"], is_html=True ) # Create a draft draft_result = gmail.create_draft( to="colleague@example.com", subject="Draft: Project Proposal", body="Here's the initial draft of our project proposal..." ) ``` ### Message Management ```python # Get recent messages messages = gmail.fetch_emails(max_results=10) # Search for specific emails urgent_emails = gmail.fetch_emails(query="is:unread subject:urgent") # Get messages from a specific sender from_sender = gmail.fetch_emails(query="from:important@company.com") # Get message details (internal helper) message = gmail._get_message_details("message_id_here") # Move a message to trash delete_result = gmail.move_to_trash("message_id_here") ``` ### Label Management ```python # Get all labels labels = gmail.list_gmail_labels() # Create a new label new_label = gmail.create_label("Important Projects") # Modify message labels gmail.modify_email_labels( message_id="message_id_here", add_label_ids=["label_id_here"], remove_label_ids=["INBOX"] ) ``` ### Contact Management ```python # Get all contacts contacts = gmail.get_contacts() # Search for specific contacts search_results = gmail.search_contacts("John Smith") # Get user profile profile = gmail.get_profile() ``` ### Thread Management ```python # Get recent threads threads = gmail.list_threads(max_results=5) # Get a specific thread thread = gmail.fetch_thread_by_id("thread_id_here") # Search for threads project_threads = gmail.get_threads(query="subject:project") ``` ## Error Handling All methods return a dictionary with a `success` boolean field. Check this field to determine if the operation was successful: ```python result = gmail.send_email( to="invalid-email", subject="Test", body="Test message" ) if result["success"]: print(f"Email sent successfully! Message ID: {result['message_id']}") else: print(f"Failed to send email: {result['message']}") ``` ## Authentication The Gmail toolkit uses OAuth2 authentication with Google's Gmail API. This section covers the complete authentication setup and mechanisms. ### Prerequisites Before using the Gmail toolkit, you need to set up Google API credentials: 1. **Google Cloud Console Setup:** - Go to the [Google Cloud Console](https://console.cloud.google.com/) - Create a new project or select an existing one - Enable the Gmail API and Google People API - Create OAuth 2.0 credentials (Desktop application type) 2. **Download Credentials:** - Download the `credentials.json` file from the Google Cloud Console - Place it in your project directory or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable ### Authentication Flow The Gmail toolkit implements a multi-step OAuth2 authentication process: #### 1. Initial Authentication On first use, the toolkit will: ```python # The authentication process happens automatically when initializing gmail = GmailToolkit() # This triggers the OAuth flow ``` **What happens behind the scenes:** - Loads the `credentials.json` file - Opens a browser window for user consent - Requests permission for all required Gmail scopes - Exchanges authorization code for access and refresh tokens - Stores tokens securely in `token.json` for future use #### 2. Token Storage The toolkit stores authentication tokens in a local `token.json` file: ```json { "token": "ya29.a0AfH6SMC...", "refresh_token": "1//04...", "token_uri": "https://oauth2.googleapis.com/token", "client_id": "your-client-id.apps.googleusercontent.com", "client_secret": "your-client-secret", "scopes": ["https://mail.google.com/", ...], "expiry": "2024-01-01T12:00:00Z" } ``` #### 3. Automatic Token Refresh The toolkit automatically handles token refresh: - **Access tokens** expire after 1 hour - **Refresh tokens** are used to obtain new access tokens - **Automatic refresh** happens before each API call if needed - **No user intervention** required after initial setup ### Required Scopes The toolkit requests the following Gmail API scopes: | Scope | Purpose | Access Level | |-------|---------|--------------| | `https://www.googleapis.com/auth/gmail.readonly` | Read emails and metadata | Read-only | | `https://www.googleapis.com/auth/gmail.send` | Send emails | Write | | `https://www.googleapis.com/auth/gmail.modify` | Modify emails and labels | Write | | `https://www.googleapis.com/auth/gmail.compose` | Create drafts and compose | Write | | `https://www.googleapis.com/auth/gmail.labels` | Manage labels | Write | | `https://www.googleapis.com/auth/contacts.readonly` | Read Google Contacts | Read-only | | `https://www.googleapis.com/auth/userinfo.profile` | Access user profile | Read-only | ### Environment Variables You can configure authentication using environment variables: ```bash # Set the path to your credentials file export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json" # Optional: Set custom token storage location export GMAIL_TOKEN_PATH="/custom/path/token.json" ``` ### Authentication Methods #### Method 1: Credentials File (Recommended) ```python # Place credentials.json in your project directory gmail = GmailToolkit() ``` #### Method 2: Environment Variable ```python import os os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = '/path/to/credentials.json' gmail = GmailToolkit() ``` #### Method 3: Explicit Path ```python # The toolkit will look for credentials.json in the current directory # or use the path specified in GOOGLE_APPLICATION_CREDENTIALS gmail = GmailToolkit() ``` ### Troubleshooting Authentication #### Common Issues and Solutions **1. "Credentials not found" Error:** ```python # Error: FileNotFoundError: [Errno 2] No such file or directory: 'credentials.json' # Solution: Ensure credentials.json is in the correct location ``` **2. "Invalid credentials" Error:** ```python # Error: google.auth.exceptions.RefreshError: The credentials do not contain the necessary fields # Solution: Re-download credentials.json from Google Cloud Console ``` **3. "Access denied" Error:** ```python # Error: googleapiclient.errors.HttpError: