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

11.3 KB
Raw Blame

title: "Workforce" icon: "users"

doc_code_map: - "camel/societies/workforce/**/*.py"

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.

Core Components Deep Dive

The `Workforce` class is the central orchestrator. It manages the entire lifecycle of a multi-agent task.
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,
        default_model: Optional[Union[BaseModelBackend, ModelManager]] = None,
        graceful_shutdown_timeout: float = 15.0,
        task_timeout_seconds: Optional[float] = None,
        share_memory: bool = False,
        use_structured_output_handler: bool = True,
        callbacks: Optional[List[WorkforceCallback]] = None,
        mode: WorkforceMode = WorkforceMode.AUTO_DECOMPOSE,
        failure_handling_config: Optional[
            Union[FailureHandlingConfig, Dict]
        ] = None,
    ) -> 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.
  • task_timeout_seconds: Optional per-workforce task timeout in seconds.
  • 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.
  • callbacks: Optional A list of callback handlers to observe and record workforce lifecycle events and metrics.
  • mode: Execution mode, either WorkforceMode.AUTO_DECOMPOSE (default) or WorkforceMode.PIPELINE.
  • failure_handling_config: Controls retry count, enabled recovery strategies, and whether to halt on max retries.
The Workforce can be composed of different types of workers, each suited for different kinds of tasks. 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. 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.

Creating and Adding Workers

Here are detailed examples of how to create and add `SingleAgentWorker` instances to your workforce. ```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,
)
```python from camel.societies.workforce import Workforce from camel.agents import ChatAgent from camel.models import ModelFactory from camel.types import ModelPlatformType, ModelType

workforce = Workforce("Creative Writing Team")

Create an agent with a specific model for creative tasks

creative_model = ModelFactory.create( model_platform=ModelPlatformType.OPENAI, 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>

<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 ...
The `Workforce` manages a sophisticated task lifecycle.
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.
Besides automatic decomposition, Workforce also supports predefined pipeline execution (`WorkforceMode.PIPELINE`) for deterministic multi-step workflows.
from camel.societies.workforce import Workforce, WorkforceMode
from camel.tasks import Task

workforce = Workforce("Report Pipeline", mode=WorkforceMode.PIPELINE)

workforce.pipeline_add("Collect data", task_id="collect") \
         .pipeline_fork(["Analyze market", "Analyze risks"]) \
         .pipeline_join("Write final report", task_id="report") \
         .pipeline_build()

result = workforce.process_task(Task(content="Generate weekly report"))

In pipeline mode, downstream tasks can still receive failure context from upstream tasks, which is useful for robust join/aggregation steps.

Workforce provides built-in runtime control APIs for human intervention and safe operations:
  • pause() / resume()
  • stop_gracefully() / stop_immediately() / skip_gracefully()
  • save_snapshot() / list_snapshots() / restore_from_snapshot(...)
  • add_main_task(...), add_subtask(...), modify_task_content(...), reorder_tasks(...)

This makes it possible to inspect and adjust execution while tasks are in progress.

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).
from camel.societies.workforce import Workforce
from camel.agents import ChatAgent
from camel.toolkits import HumanToolkit

# 1) Prepare human-in-the-loop tools
human_toolkit = HumanToolkit()
human_tools = human_toolkit.get_tools()  # includes ask_human_via_console, send_message_to_user, ...

# 2) 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`
)

# 3) 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)

# 4) 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.
For recurring tasks, `SingleAgentWorker` can persist and reuse workflow traces:
  • save_workflow_memories_async() (recommended async path)
  • load_workflow_memories(...)
  • Selection metadata via WorkflowSelectionMethod

This helps workers reuse proven execution patterns across similar tasks.

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.
  • TaskAnalysisResult: Unified output for failure/quality analysis, including recommended recovery strategy.

Understanding these models is key to interpreting the workforce's internal state and logs.

See a real-world multi-agent workflow with Workforce. Full documentation for advanced usage and configuration.