đ« 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
docs: Improvise Workforce (#2926)
Sarthak Bhardwaj32b548bc0076
diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.jsonindex e65411118..67aa5fab4 100644--- a/docs/mintlify/docs.json+++ b/docs/mintlify/docs.json@@ -72,6 +72,13 @@"key_modules/retrievers"]},+ {+ "group": "Awesome Toolkits",+ "pages": [+ "key_modules/browsertoolkit",+ "key_modules/terminaltoolkit"+ ]+ },{"group": "CAMEL with MCP","pages": [diff --git a/docs/mintlify/key_modules/browsertoolkit.mdx b/docs/mintlify/key_modules/browsertoolkit.mdxnew file mode 100644index 000000000..29a4afc88--- /dev/null+++ b/docs/mintlify/key_modules/browsertoolkit.mdx@@ -0,0 +1,139 @@+---+title: "Browser Toolkit"+icon: "globe"+---++<Note type="info" title="What is the Browser Toolkit?">+ The <b>Browser Toolkit</b> provides a powerful set of tools to automate and interact with web browsers. It allows CAMEL agents to perform complex web-based tasks, from simple page navigation to intricate form submissions and data extraction.+</Note>++<CardGroup cols={2}>+ <Card title="Two-Agent System" icon="users">+ Uses a sophisticated two-agent system: a `planning_agent` to create and refine high-level plans, and a `web_agent` to observe the screen and execute low-level actions.+ </Card>+ <Card title="Visual Reasoning" icon="image">+ The `web_agent` can analyze "Set-of-Marks" (SoM) screenshots, which are visual representations of the page with interactive elements highlighted, enabling it to perform complex visual reasoning.+ </Card>+ <Card title="Persistent Sessions" icon="cookie">+ Supports persistent browser sessions by saving and loading cookies and user data, allowing the agent to stay logged into websites across multiple sessions.+ </Card>+ <Card title="Video Analysis" icon="video">+ Can analyze videos on the current page (e.g., YouTube) to answer questions about their content, leveraging the `VideoAnalysisToolkit`.+ </Card>+</CardGroup>++## Initialization++To get started, initialize the `BrowserToolkit`. You can configure the underlying models for the planning and web agents.++<Tabs>+<Tab title="Default">+```python+from camel.toolkits import BrowserToolkit++# Initialize with default models+browser_toolkit = BrowserToolkit()+```+</Tab>+<Tab title="Custom Models">+```python+from camel.toolkits import BrowserToolkit+from camel.models import ModelFactory+from camel.types import ModelPlatformType, ModelType++# Define custom models for the agents (use latest OpenAI models)+web_agent_model = ModelFactory.create(+ model_platform=ModelPlatformType.OPENAI,+ model_type=ModelType.GPT_5_MINI,+)+planning_agent_model = ModelFactory.create(+ model_platform=ModelPlatformType.OPENAI,+ model_type=ModelType.O4_MINI,+)++browser_toolkit = BrowserToolkit(+ web_agent_model=web_agent_model,+ planning_agent_model=planning_agent_model,+)+```+</Tab>+</Tabs>++## Core Functionality: `browse_url`++The main entry point for the toolkit is the `browse_url` function. It takes a high-level task and a starting URL, and then autonomously navigates the web to complete the task.++<Card title="Example: Researching a Topic" icon="magnifying-glass">+```python+task_prompt = "Find the main contributions of the paper 'Sparks of AGI' by Microsoft Research."+start_url = "https://www.google.com"++# The agent will navigate from Google, find the paper, and extract the information.+result = browser_toolkit.browse_url(+ task_prompt=task_prompt,+ start_url=start_url,+)++print(result)+```+</Card>++## How It Works: The Two-Agent System++The `browse_url` function orchestrates a loop between the `planning_agent` and the `web_agent`.++<Steps>+<Step title="Planning">+The `planning_agent` creates a high-level plan to accomplish the task.+</Step>+<Step title="Observation">+The `web_agent` observes the current page by taking a "Set-of-Marks" (SoM) screenshot.+</Step>+<Step title="Action">+Based on the observation and the plan, the `web_agent` decides on the next action to take (e.g., click, type, scroll).+</Step>+<Step title="Execution">+The toolkit executes the action and the loop repeats.+</Step>+<Step title="Replanning">+If the `web_agent` gets stuck, the `planning_agent` can re-evaluate the situation and create a new plan.+</Step>+</Steps>++## Advanced Usage++### Persistent Sessions+You can maintain login sessions across runs by providing a path to a `cookies.json` file or a `user_data_dir`.++<Card title="Using a Persistent Session" icon="cookie">+```python+# The toolkit will save cookies and local storage to this file+cookie_path = "./my_browser_session.json"++# First run: Log in to a website+# browser_toolkit = BrowserToolkit(cookie_json_path=cookie_path)+# browser_toolkit.browse_url(task_prompt="Log in to my account...", start_url="...")++# Subsequent runs: The agent will be logged in automatically+browser_toolkit_loggedin = BrowserToolkit(cookie_json_path=cookie_path)+```+</Card>++### Video Analysis++The toolkit can answer questions about videos on a webpage.++<Card title="Asking a Question About a YouTube Video" icon="video">+```python+# First, navigate to the video+browser_toolkit.browse_url(task_prompt="Navigate to a specific YouTube video", start_url="...")++# Then, ask a question about it+# Note: This is an example of how you might use the underlying BaseBrowser.+# The browse_url function would orchestrate this automatically.+question = "What is the main topic of this video?"+answer = browser_toolkit.browser.ask_question_about_video(question=question)++print(answer)+```+</Card>\ No newline at end of filediff --git a/docs/mintlify/key_modules/terminaltoolkit.mdx b/docs/mintlify/key_modules/terminaltoolkit.mdxnew file mode 100644index 000000000..e451384d8--- /dev/null+++ b/docs/mintlify/key_modules/terminaltoolkit.mdx@@ -0,0 +1,152 @@+---+title: "Terminal Toolkit"+icon: "terminal"+---++<Note type="info" title="What is the Terminal Toolkit?">+ The <b>Terminal Toolkit</b> provides a secure and powerful way for CAMEL agents to interact with a terminal. It allows agents to execute shell commands, manage files, and even ask for human help, all within a controlled, sandboxed environment.+</Note>++<CardGroup cols={2}>+ <Card title="Secure Sandboxed Execution" icon="lock">+ All file-writing and execution commands are restricted to a designated `working_directory` to prevent unintended system modifications. Dangerous commands are blocked by default.+ </Card>+ <Card title="Multi-Session Management" icon="window-restore">+ Run multiple, independent terminal sessions concurrently. Each session maintains its own state and history, allowing for complex, parallel workflows.+ </Card>+ <Card title="Virtual Environment Management" icon="binary">+ Automatically create and manage isolated Python virtual environments, ensuring that package installations and script executions don't conflict with your system setup.+ </Card>+ <Card title="Human-in-the-Loop" icon="hand">+ When an agent gets stuck, it can pause its execution and request human assistance. A human can then take over the terminal session to resolve the issue before handing control back.+ </Card>+</CardGroup>++## Initialization++To get started, initialize the `TerminalToolkit`. You can configure its behavior, such as the working directory and environment settings.++<Tabs>+<Tab title="Default">+```python+from camel.toolkits import TerminalToolkit++# Initialize with default settings.+# Safe mode is ON and working_directory is './workspace'+terminal_toolkit = TerminalToolkit()+```+</Tab>+<Tab title="Custom Workspace">+```python+from camel.toolkits import TerminalToolkit++# Specify a custom sandboxed working directory+terminal_toolkit = TerminalToolkit(+ working_directory="./my_safe_workspace"+)+```+</Tab>+<Tab title="Cloned Environment">+```python+from camel.toolkits import TerminalToolkit++# Clone the current python environment into the workspace+# for the agent to use without affecting the original.+terminal_toolkit = TerminalToolkit(clone_current_env=True)+```+</Tab>+</Tabs>++## Usage Examples++### Executing Commands+The `shell_exec` function is the primary way to execute commands. Each command is run within a session, identified by a unique `id`.++<Tabs>+<Tab title="Listing Files">+```python+# Execute the 'ls -l' command in 'session_1'+output = terminal_toolkit.shell_exec(id='session_1', command='ls -l')+print(output)+```+</Tab>+<Tab title="Running a Python Script">+```python+# First, create a python script inside the workspace+write_script_cmd = """+echo 'print("Hello from a sandboxed CAMEL environment!")' > hello.py+"""+terminal_toolkit.shell_exec(id='session_1', command=write_script_cmd)++# Now, execute the script+output = terminal_toolkit.shell_exec(id='session_1', command='python hello.py')+print(output)+```+</Tab>+</Tabs>++### Interacting with Processes+You can manage long-running or interactive processes.++<Tabs>+<Tab title="Writing to a Process">+You can write to a process's standard input using `shell_write_to_process`. This is useful for interactive command-line tools.+```python+# Start a python REPL in a new session+terminal_toolkit.shell_exec(id='interactive_session', command='python')++# Write code to the python process+terminal_toolkit.shell_write_to_process(+ id='interactive_session',+ input='print("Hello, interactive world!")',+ press_enter=True+)++# View the output+output = terminal_toolkit.shell_view(id='interactive_session')+print(output)+```+</Tab>+<Tab title="Killing a Process">+Forcibly terminate a running process using `shell_kill_process`.+```python+# Start a long-running process+terminal_toolkit.shell_exec(id='long_process', command='sleep 100')++# Kill the process before it finishes+result = terminal_toolkit.shell_kill_process(id='long_process')+print(result)+```+</Tab>+</Tabs>+++### Safe Mode+When `safe_mode` is enabled (default), the toolkit blocks commands that could be harmful to your system.++<Card title="Example of a Blocked Command" icon="shield-halved">+```python+# This command attempts to delete a file outside the workspace.+# The toolkit will block it and return an error message.+output = terminal_toolkit.shell_exec(id='session_1', command='rm /etc/hosts')++print(output)+# Expected Output:+# Command rejected: Safety restriction: Cannot delete files outside of working directory ...+```+</Card>+++### Human-in-the-Loop+When an agent gets stuck, it can use `ask_user_for_help` to request human intervention.++<Card title="Asking for Human Help" icon="hand">+```python+# The agent is stuck, so it asks for help in 'session_1'+help_result = terminal_toolkit.ask_user_for_help(id='session_1')++# The script will now pause and wait for the user to type commands+# in the console. After the user types '/exit', the script will resume.+print(help_result)+```+</Card>\ No newline at end of filediff --git a/docs/mintlify/key_modules/workforce.mdx b/docs/mintlify/key_modules/workforce.mdxindex ea8f770ef..d2192203a 100644--- a/docs/mintlify/key_modules/workforce.mdx+++ b/docs/mintlify/key_modules/workforce.mdx@@ -1,146 +1,237 @@---title: "Workforce"-icon: users+icon: "users"---<Card title="Concept" icon="users">-Workforce is CAMEL-AIâs multi-agent teamwork engine.--Instead of relying on a single agent, Workforce lets you organize a *team* of specialized agentsâeach with its own strengthsâunder a single, coordinated system. You can quickly assemble, configure, and launch collaborative agent âworkforcesâ for any task that needs parallelization, diverse expertise, or complex workflows.--With Workforce, agents plan, solve, and verify work togetherâlike a project team in an organization, but fully automated.--<Note type="info">-**Key advantages of Workforce:**-- Instantly scale from single-agent to multi-agent workflows-- Built-in coordination, planning, and failure recovery-- Ideal for hackathons, evaluations, code review, brainstorming, and more-- Configure roles, toolsets, and communication patterns for *any* scenario-</Note>+Workforce is CAMEL-AIâs powerful multi-agent collaboration engine. It enables you to assemble, manage, and scale teams of AI agents to tackle complex tasks that are beyond the capabilities of a single agent. By creating a "workforce" of specialized agents, you can automate intricate workflows, foster parallel execution, and achieve more robust and intelligent solutions.</Card>-<Card title="See More: Hackathon Judge Committee Example" icon="link" href="https://colab.research.google.com/drive/18ajYUMfwDx3WyrjHow3EvUMpKQDcrLtr?usp=sharing">- Check out our in-depth Workforce example:- <b>Create a Hackathon Judge Committee with Workforce</b>+## Core Components Deep Dive++<Card title="The Workforce Class" icon="layer-group">+The `Workforce` class is the central orchestrator. It manages the entire lifecycle of a multi-agent task.++```python title="Workforce Initialization"+class Workforce(BaseNode):+ def __init__(+ self,+ description: str,+ children: Optional[List[BaseNode]] = None,+ coordinator_agent: Optional[ChatAgent] = None,+ task_agent: Optional[ChatAgent] = None,+ new_worker_agent: Optional[ChatAgent] = None,+ graceful_shutdown_timeout: float = 15.0,+ share_memory: bool = False,+ use_structured_output_handler: bool = True,+ ) -> None:+ # ...+```++**Key Parameters:**++- `description`: A high-level description of the workforce's purpose.+- `children`: A list of initial worker nodes.+- `coordinator_agent`: A `ChatAgent` for assigning tasks.+- `task_agent`: A `ChatAgent` for decomposing tasks.+- `new_worker_agent`: A template `ChatAgent` for creating new workers.+- `share_memory`: If `True`, `SingleAgentWorker` instances will share memory.+- `use_structured_output_handler`: Defaults to `True`. Enables structured output handling so models without native JSON + tool-calling can still interop reliably.</Card>------## System Design--### Architecture: How Workforce Works--Workforce uses a **hierarchical, modular design** for real-world team problem-solving:--See how the coordinator and task planner agents orchestrate a multi-agent workflow:----- **Workforce:** The âteamâ as a whole.-- **Worker nodes:** Individual contributorsâeach node can contain one or more agents, each with their own capabilities.-- **Coordinator agent:** The âproject managerââroutes tasks to worker nodes based on their role and skills.-- **Task planner agent:** The âstrategy leadââbreaks down big jobs into smaller, doable subtasks and organizes the workflow.--### Communication: A Shared Task Channel--- Every Workforce gets a **shared task channel** when itâs created.-- **How it works:**- - All tasks are posted into this channel.- - Worker nodes âlistenâ and accept their assigned tasks.- - Results are posted back to the channel, where theyâre available as dependencies for the next steps.+<Card title="Worker Types" icon="users-gear">+The Workforce can be composed of different types of workers, each suited for different kinds of tasks.+<CardGroup cols={2}>+ <Card title="SingleAgentWorker" icon="user">+ The most common type of worker. It consists of a single `ChatAgent` configured with specific tools and a system prompt. For efficiency, it uses an `AgentPool` to reuse agent instances.+ </Card>+ <Card title="RolePlayingWorker" icon="users">+ This worker uses a `RolePlaying` session between two agents (an assistant and a user) to accomplish a task. It's useful for brainstorming, debate, or exploring a topic from multiple perspectives.+ </Card>+</CardGroup>+</Card>-*This design lets agents build on each other's work and ensures no knowledge is lost between steps.*+## Creating and Adding Workers++<Card title="SingleAgentWorker Examples" icon="user">+Here are detailed examples of how to create and add `SingleAgentWorker` instances to your workforce.+<Tabs>+<Tab title="Simple Worker">+```python+from camel.societies.workforce import Workforce+from camel.agents import ChatAgent++workforce = Workforce("My Research Team")++# Create a general-purpose agent+general_agent = ChatAgent(system_message="You are a helpful research assistant.")++# Add the worker+workforce.add_single_agent_worker(+ description="A worker for general research tasks",+ worker=general_agent,+)+```+</Tab>+<Tab title="Worker with Tools">+```python+from camel.societies.workforce import Workforce+from camel.agents import ChatAgent+from camel.toolkits import SearchToolkit++workforce = Workforce("Web Research Team")++# Create a search agent with a web search tool+search_agent = ChatAgent(+ system_message="A research assistant that can search the web.",+ tools=[SearchToolkit().search_duckduckgo]+)++# Add the worker+workforce.add_single_agent_worker(+ description="A worker that can perform web searches",+ worker=search_agent,+)+```+</Tab>+<Tab title="Worker with a Specific Model">+```python+from camel.societies.workforce import Workforce+from camel.agents import ChatAgent+from camel.models import ModelFactory+from camel.types import ModelType++workforce = Workforce("Creative Writing Team")++# Create an agent with a specific model for creative tasks+creative_model = ModelFactory.create(model_type=ModelType.GPT_5_MINI)+creative_agent = ChatAgent(+ system_message="A creative writer for generating stories.",+ model=creative_model+)++# Add the worker+workforce.add_single_agent_worker(+ description="A worker for creative writing",+ worker=creative_agent,+)+```+</Tab>+</Tabs>+</Card>-### Failure Handling: Built-In Robustness+<Card title="RolePlayingWorker Example" icon="users">+This example sets up a role-playing session between a "solution architect" and a "software developer" to design a system.++```python title="role_playing_example.py"+from camel.societies.workforce import Workforce++workforce = Workforce("System Design Team")++workforce.add_role_playing_worker(+ description="A role-playing session for system design.",+ assistant_role_name="Software Developer",+ user_role_name="Solution Architect",+ assistant_agent_kwargs=dict(+ system_message="You are a software developer responsible for implementing the system."+ ),+ user_agent_kwargs=dict(+ system_message="You are a solution architect responsible for the high-level design."+ ),+ chat_turn_limit=5,+)++# ... process a task with this workforce ...+```+</Card>-Workforce is designed to handle failures and recover gracefully:+<Card title="Task Lifecycle and Management" icon="diagram-project">+The `Workforce` manages a sophisticated task lifecycle.++```mermaid+graph TD+ A[Start: High-Level Task] --> B{Decompose Task}+ B --> C[Subtask 1]+ B --> D[Subtask 2]+ B --> E[...]+ C --> F{Assign Tasks}+ D --> F+ E --> F+ F --> G[Execute Tasks in Parallel by Workers]+ G --> H{Task Completed?}+ H -->|Yes| I[Store Result as Dependency]+ H -->|No| J{Failure Recovery}+ J -->|Retry| G+ J -->|Replan| G+ J -->|Decompose| B+ I --> K[Next Ready Tasks]+ K --> G+ G --> L[All Tasks Done]+ L --> M[Final Result]+```++1. **Decomposition**: The `task_agent` breaks the main task into smaller, self-contained subtasks.+2. **Assignment**: The `coordinator_agent` assigns each subtask to the most suitable worker.+3. **Execution**: Workers execute their assigned tasks, often in parallel.+4. **Completion**: A task's result is stored and can be used as a dependency for other tasks.+5. **Failure Handling**: If a task fails, the `Workforce` initiates its recovery protocols.+</Card>-- If a worker fails a task, the coordinator agent will:- - **Decompose and retry:** Break the task into even smaller pieces and reassign.- - **Escalate:** If the task keeps failing, create a new worker designed for that problem.-- To prevent infinite loops, if a task has failed or been decomposed more than a set number of times (default: 3), Workforce will automatically halt that workflow.+<Card title="Advanced Usage: Human-in-the-Loop (HITL)" icon="hand">+To enable HITL inside a Workforce, equip the agents (coordinator, task agent, or workers) with the `HumanToolkit`. Agents can then call a human during execution (e.g., to clarify requirements, approve actions, or unblock errors).++```python title="hitl_with_human_toolkit.py"+from camel.societies.workforce import Workforce+from camel.agents import ChatAgent+from camel.toolkits import HumanToolkit++# 1) Create the workforce+workforce = Workforce("Interactive Workforce")++# 2) Prepare human-in-the-loop tools+human_toolkit = HumanToolkit()+human_tools = human_toolkit.get_tools() # includes ask_human_via_console, send_message_to_user, ...++# 3) Attach HumanToolkit to any agents that may need human help+coordinator = ChatAgent(+ system_message="You coordinate tasks and may ask a human for help when needed.",+ tools=human_tools,+)++worker = ChatAgent(+ system_message="You execute tasks and can ask the human for clarification.",+ tools=[human_toolkit.ask_human_via_console], # or use `human_tools`+)++# 4) Register agents into the workforce+workforce = Workforce(+ description="Interactive Workforce",+ coordinator_agent=coordinator,+ task_agent=None,+)+workforce.add_single_agent_worker(description="Worker", worker=worker)++# 5) Run tasks as usual. When an agent invokes a human tool, it will prompt via console.+# workforce.process_task(Task(content="Build a quick demo and confirm requirements with the human."))+```++Notes:+- No special threading is required. Agents prompt the user when they call a `HumanToolkit` tool.+- If you need async control, `process_task_async` is available, but it is not required for HITL.+</Card>-<Tip>- <b>Tip:</b> Workforce automatically stops stuck workflowsâso you donât waste compute or get caught in agent loops!-</Tip>+<Card title="Key Data Structures" icon="database">+The `workforce` module uses several Pydantic models to ensure structured data exchange.----+- **`WorkerConf`**: Defines the configuration for a new worker.+- **`TaskResult`**: Represents the output of a completed task.+- **`TaskAssignment`**: A single task-to-worker assignment, including dependencies.+- **`TaskAssignResult`**: A list of `TaskAssignment` objects.+- **`RecoveryDecision`**: The output of the failure analysis process, dictating the recovery strategy.-<Card title="Quickstart: Build Your First Workforce" icon="rocket">--<Steps>- <Step title="Create a Workforce Instance">- To begin, import and create a new Workforce:-- ```python- from camel.societies.workforce import Workforce-- # Create a workforce instance- workforce = Workforce("A Simple Workforce")- ```-- <Tip>- For quick setups, just provide the description.- For advanced workflows, you can pass in custom worker lists or configure the coordinator and planner agents.- </Tip>- </Step>-- <Step title="Add Worker Nodes">- Now add your worker agents.- (Example: a `ChatAgent` for web search, named `search_agent`.)-- ```python- # Add a worker agent to the workforce- workforce.add_single_agent_worker(- "An agent that can do web searches",- worker=search_agent,- )- ```-- **Chain multiple agents for convenience:**- ```python- workforce.add_single_agent_worker(- "An agent that can do web searches",- worker=search_agent,- ).add_single_agent_worker(- "Another agent",- worker=another_agent,- ).add_single_agent_worker(- "Yet another agent",- worker=yet_another_agent,- )- ```-- <Tip>- The *description* is important!- The coordinator uses it to assign tasksâso keep it clear and specific.- </Tip>- </Step>-- <Step title="Start the Workforce and Solve Tasks">- Define a task and let the workforce handle it:-- ```python- from camel.tasks import Task-- # The id can be any string- task = Task(- content="Make a travel plan for a 3-day trip to Paris.",- id="0",- )-- # Process the task with the workforce- task = workforce.process_task(task)-- # See the result- print(task.result)- ```- </Step>-</Steps>+Understanding these models is key to interpreting the workforce's internal state and logs.</Card>-----<CardGroup cols={2}><Cardtitle="Cookbook: Hackathon Judge Committee"@@ -156,5 +247,4 @@ Workforce is designed to handle failures and recover gracefully:>Full documentation for advanced usage and configuration.</Card>-</CardGroup>-+</CardGroup>\ No newline at end of file