🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
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: AChatAgentfor assigning tasks.task_agent: AChatAgentfor decomposing tasks.new_worker_agent: A templateChatAgentfor creating new workers.task_timeout_seconds: Optional per-workforce task timeout in seconds.share_memory: IfTrue,SingleAgentWorkerinstances will share memory.use_structured_output_handler: Defaults toTrue. 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, eitherWorkforceMode.AUTO_DECOMPOSE(default) orWorkforceMode.PIPELINE.failure_handling_config: Controls retry count, enabled recovery strategies, and whether to halt on max retries.
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 ChatAgentworkforce = 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]
- Decomposition: The
task_agentbreaks the main task into smaller, self-contained subtasks. - Assignment: The
coordinator_agentassigns each subtask to the most suitable worker. - Execution: Workers execute their assigned tasks, often in parallel.
- Completion: A task's result is stored and can be used as a dependency for other tasks.
- Failure Handling: If a task fails, the
Workforceinitiates its recovery protocols.
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
HumanToolkittool. - If you need async control,
process_task_asyncis available, but it is not required for HITL.
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 ofTaskAssignmentobjects.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.