Camel.societies.workforce.workforce
WorkforceState
Workforce execution state for human intervention support.
WorkforceSnapshot
Snapshot of workforce state for resuming execution.
init
Workforce
A system where multiple worker nodes (agents) cooperate together to solve tasks. It can assign tasks to worker nodes and also take strategies such as create new worker, decompose tasks, etc. to handle situations when the task fails.
The workforce uses three specialized ChatAgents internally:
- Coordinator Agent: Assigns tasks to workers based on their capabilities
- Task Planner Agent: Decomposes complex tasks and composes results
- Dynamic Workers: Created at runtime when tasks fail repeatedly
Parameters:
- description (str): Description of the workforce.
- children (Optional[List[BaseNode]], optional): List of child nodes under this node. Each child node can be a worker node or another workforce node. (default: :obj:
None
) - coordinator_agent_kwargs (Optional[Dict], optional): Keyword arguments passed directly to the coordinator :obj:
ChatAgent
constructor. The coordinator manages task assignment and failure handling strategies. See :obj:ChatAgent
documentation for all available parameters. (default: :obj:None
- uses ModelPlatformType.DEFAULT, ModelType.DEFAULT) - task_agent_kwargs (Optional[Dict], optional): Keyword arguments passed directly to the task planning :obj:
ChatAgent
constructor. The task agent handles task decomposition into subtasks and result composition. See :obj:ChatAgent
documentation for all available parameters. (default: :obj:None
- uses ModelPlatformType.DEFAULT, ModelType.DEFAULT) - new_worker_agent_kwargs (Optional[Dict], optional): Default keyword arguments passed to :obj:
ChatAgent
constructor for workers created dynamically at runtime when existing workers cannot handle failed tasks. See :obj:ChatAgent
documentation for all available parameters. (default: :obj:None
- creates workers with SearchToolkit, CodeExecutionToolkit, and ThinkingToolkit) - graceful_shutdown_timeout (float, optional): The timeout in seconds for graceful shutdown when a task fails 3 times. During this period, the workforce remains active for debugging. Set to 0 for immediate shutdown. (default: :obj:
15.0
) - share_memory (bool, optional): Whether to enable shared memory across SingleAgentWorker instances in the workforce. When enabled, all SingleAgentWorker instances, coordinator agent, and task planning agent will share their complete conversation history and function-calling trajectory, providing better context for task handoffs and continuity. Note: Currently only supports SingleAgentWorker instances; RolePlayingWorker and nested Workforce instances do not participate in memory sharing. (default: :obj:
False
)
init
repr
_collect_shared_memory
Returns:
Dict[str, List]: A dictionary mapping agent types to their memory records. Contains entries for ‘coordinator’, ‘task_agent’, and ‘workers’.
_share_memory_with_agents
Share collected memory with coordinator, task agent, and SingleAgentWorker instances.
Parameters:
- shared_memory (Dict[str, List]): Memory records collected from all agents to be shared.
_sync_shared_memory
Synchronize memory across all agents by collecting and sharing.
_decompose_task
Returns:
List[Task]: The subtasks.
pause
Pause the workforce execution. If the internal event-loop is already running we schedule the asynchronous pause coroutine onto it. When the loop has not yet been created (e.g. the caller presses the hot-key immediately after workforce start-up) we fall back to a synchronous state change so that no tasks will be scheduled until the loop is ready.
resume
Resume execution after a manual pause.
stop_gracefully
Request workforce to finish current in-flight work then halt.
Works both when the internal event-loop is alive and when it has not yet been started. In the latter case we simply mark the stop flag so that the loop (when it eventually starts) will exit immediately after initialisation.
save_snapshot
Save current state as a snapshot.
list_snapshots
List all available snapshots.
get_pending_tasks
Get current pending tasks for human review.
get_completed_tasks
Get completed tasks.
modify_task_content
Modify the content of a pending task.
add_task
Add a new task to the pending queue.
remove_task
Remove a task from the pending queue.
reorder_tasks
Reorder pending tasks according to the provided task IDs list.
resume_from_task
Resume execution from a specific task.
restore_from_snapshot
Restore workforce state from a snapshot.
get_workforce_status
Get current workforce status for human review.
process_task
Synchronous wrapper for process_task that handles async operations internally.
Parameters:
- task (Task): The task to be processed.
Returns:
Task: The updated task.
_process_task_with_intervention
Process task with human intervention support. This creates and manages its own event loop to allow for pausing/resuming functionality.
Parameters:
- task (Task): The task to be processed.
Returns:
Task: The updated task.
continue_from_pause
Returns:
Optional[Task]: The completed task if execution finishes, None if still running/paused.
add_single_agent_worker
Add a worker node to the workforce that uses a single agent.
Parameters:
- description (str): Description of the worker node.
- worker (ChatAgent): The agent to be added.
- pool_max_size (int): Maximum size of the agent pool. (default: :obj:
10
)
Returns:
Workforce: The workforce node itself.
add_role_playing_worker
Add a worker node to the workforce that uses RolePlaying
system.
Parameters:
- description (str): Description of the node.
- assistant_role_name (str): The role name of the assistant agent.
- user_role_name (str): The role name of the user agent.
- assistant_agent_kwargs (Optional[Dict]): The keyword arguments to initialize the assistant agent in the role playing, like the model name, etc. (default: :obj:
None
) - user_agent_kwargs (Optional[Dict]): The keyword arguments to initialize the user agent in the role playing, like the model name, etc. (default: :obj:
None
) - summarize_agent_kwargs (Optional[Dict]): The keyword arguments to initialize the summarize agent, like the model name, etc. (default: :obj:
None
) - chat_turn_limit (int): The maximum number of chat turns in the role playing. (default: :obj:
3
)
Returns:
Workforce: The workforce node itself.
add_workforce
Add a workforce node to the workforce.
Parameters:
- workforce (Workforce): The workforce node to be added.
Returns:
Workforce: The workforce node itself.
reset
Reset the workforce and all the child nodes under it. Can only be called when the workforce is not running.
set_channel
Set the channel for the node and all the child nodes under it.
_get_child_nodes_info
Get the information of all the child nodes under this node.
_find_assignee
Assigns multiple tasks to worker nodes with the best capabilities.
Parameters:
- tasks (List[Task]): The tasks to be assigned.
Returns:
TaskAssignResult: Assignment result containing task assignments with their dependencies.
_create_worker_node_for_task
Creates a new worker node for a given task and add it to the children list of this node. This is one of the actions that the coordinator can take when a task has failed.
Parameters:
- task (Task): The task for which the worker node is created.
Returns:
Worker: The created worker node.
_create_new_agent
get_workforce_log_tree
Returns an ASCII tree representation of the task hierarchy and worker status.
get_workforce_kpis
Returns a dictionary of key performance indicators.
dump_workforce_logs
Dumps all collected logs to a JSON file.
Parameters:
- file_path (str): The path to the JSON file.
_submit_coro_to_loop
Thread-safe submission of coroutine to the workforce loop.
stop
Stop all the child nodes under it. The node itself will be stopped by its parent node.
clone
Creates a new instance of Workforce with the same configuration.
Parameters:
- with_memory (bool, optional): Whether to copy the memory (conversation history) to the new instance. If True, the new instance will have the same conversation history. If False, the new instance will have a fresh memory. (default: :obj:
False
)
Returns:
Workforce: A new instance of Workforce with the same configuration.
to_mcp
Expose this Workforce as an MCP server.
Parameters:
- name (str): Name of the MCP server. (default: :obj:
CAMEL-Workforce
) - description (str): Description of the workforce. If None, a generic description is used. (default: :obj:
A workforce system using the CAMEL AI framework for multi-agent collaboration.
) - dependencies (Optional[List[str]]): Additional dependencies for the MCP server. (default: :obj:
None
) - host (str): Host to bind to for HTTP transport. (default: :obj:
localhost
) - port (int): Port to bind to for HTTP transport. (default: :obj:
8001
)
Returns:
FastMCP: An MCP server instance that can be run.