Skip to content

Commit 0564672

Browse files
WHALEEYEWendong-Fan
WHALEEYE
and
Wendong-Fan
authored
docs: update the document of Workforce (#981)
Co-authored-by: Wendong-Fan <133094783+Wendong-Fan@users.noreply.github.com>
1 parent fa37a73 commit 0564672

File tree

1 file changed

+109
-163
lines changed

1 file changed

+109
-163
lines changed

‎docs/key_modules/workforce.md‎

Lines changed: 109 additions & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -1,217 +1,163 @@
11
# Workforce
22

3-
> Workforce is a system where multiple agents/role-playing systems work together to solve tasks. By using Workforce, users can quickly set up a multi-agent task solving system with customized configurations. In this section, we will give a brief view on the architecture of workforce, and how you can configure and utilize it to solve problems.
3+
> Workforce is a system where multiple agents work together to solve tasks.
4+
> By using Workforce, users can quickly set up a multi-agent task solving
5+
> system with customized configurations. In this section, we will give a
6+
> brief view on the architecture of workforce, and how you can configure
7+
> and utilize it to solve tasks.
48
5-
> *The current Workforce in CAMEL is still in beta version. We are working on the stable version of Workforce, which will have a simpler user interface and better performance. If you have any suggestions or questions, please feel free to contact us or [create an issue](https://github.com/camel-ai/camel/issues/new?assignees=lightaime&labels=bug&projects=&template=bug_report.yml&title=%5BBUG%5D+).*
9+
## System Design
610

7-
## Architecture
11+
### Architecture
812

9-
Workforce follows a tree-shaped architecture, with one or more managers (internal nodes) managing multiple fine-tuned workers with different roles (leaf nodes). A manager is responsible of managing and coordinating its child nodes and can also be a child of another manager; a worker, on the other hand, must be a child node of a manager.
13+
Workforce follows a hierarchical architecture. A workforce can consist of
14+
multiple worker nodes, and each of the worker nodes will contain an agent
15+
as the worker. The worker nodes are managed by a coordinator agent inside the
16+
workforce, and the coordinator agent will assign tasks to the worker nodes
17+
according to the description of the worker nodes, along with their tool sets.
1018

11-
> For now, CAMEL only supports the mode with one manager as root and multiple workers as direct leaf nodes of the root.
19+
Alongside the coordinator agent, there is also a task planner agent inside the
20+
workforce. The task planner agent will take the responsibility of decomposing
21+
and composing tasks, so that the workforce can solve the task step by step.
1222

13-
All manager and worker nodes share a single channel, where they can post and receive tasks, broadcast task results, etc.
23+
### Communication Mechanism
1424

15-
## Workflow
25+
The communication inside the workforce is based on the task channel. The
26+
initialization of workforce will create a channel that will be shared by
27+
all the nodes. Tasks will later be posted into this channel, and each
28+
worker node will listen to the channel, accept tasks that are assigned
29+
to it from this channel to solve.
1630

17-
In this section we are going to talk about how workforce works under the hood, briefly.
31+
When a task is solved, the worker node will post the result back to the
32+
channel, and the result will reside in the channel as a 'dependency' for
33+
other tasks, which will be shared by all the worker nodes.
1834

19-
As mentioned above, workforce is a system to solve tasks. Based on this, intrinsically, we make the initial input to a workforce as be a `Task` instance describing the main task that should be solved. This task will then be passed into the root of the workforce as the initial task of it.
35+
With this mechanism, the workforce can solve tasks in a collaborative and
36+
efficient way.
2037

21-
After starting up, the first thing that the root manager will do is decomposing the main task into multiple subtasks, so that it can be solved step by step.
38+
### Failure Handling
2239

23-
Afterwards, the manager will assign each of them to a worker that is most capable of doing this task, according to the global information it has, such as the description of each worker it manages. The subtasks are not posted all in a time. Instead, due to the dependency relationships, it will only post tasks with all the dependencies (also tasks) completed.
40+
In the workforce, we have a mechanism to handle failures. When a task fails,
41+
the coordinator agent will take actions to fix it. The actions can be either
42+
decomposing the task into smaller ones and assign them again, or creating a
43+
new worker that is capable of doing the task.
2444

25-
Each worker will take the assigned tasks and try to complete it. If the task is successfully done, the worker will update the result of the task and notify the manager, so that the manager can post new tasks that depends on it.
45+
For now, the coordinator will make decisions based on the number of times the
46+
task has been decomposed. If the task has already been decomposed for more
47+
than a certain number of times, the coordinator will take the new worker
48+
creation action; if not, the coordinator will simply take the decomposition
49+
action.
2650

27-
However, task can fail. We don’t want to see this happen, but things go wrong. Fortunately, managers can fix this. When a task fails, the worker will report the failure to the manager, and manager can take one of the following actions:
51+
There will also be cases where a task just simply cannot be solved by
52+
agents. Under this circumstance, to prevent the workforce from being stuck
53+
in a infinite agent creation loop, the workforce will be halted if one task
54+
has been failed for a certain number of times (3 by default).
2855

29-
1. decompose the task into smaller ones and assign them again
30-
2. create a new worker that is capable of doing the task
56+
### A Simple Example of the Workflow
3157

32-
For now, if the task has already been decomposed a lot of times, the manager will take the new worker creation action; if not, the manager will simply take the decomposition action.
58+
Here is a diagram illustrating the workflow with a simple example.
3359

34-
When all the subtasks are finished, their results will be composed into a single, comprehensive result and then get updated into the main task instance and returned to the user.
60+
![Workforce Example](https://lh3.googleusercontent.com/pw/AP1GczMFbGi7pInBgiXoPbS8lOfIuGijWoo3EeRlz0OWPe7im1FWYXnD1xnbQpEbD_p4DVHtpWhQQHicGaEc1RaoyaEqg9396oGNPQYi4XQ8U3SBRxQV53KSrqzcE9RBMkGv7PgMMxXWVEiWA5rVe6oE9C8=w1315-h1324-s-no?authuser=0)
3561

36-
### A Diagram with Simple Example
62+
## Get Started
3763

38-
[Here](https://photos.app.goo.gl/dmFEiqyaidGVu5RXA) is a diagram illustrating the workflow with a simple example.
64+
In this section, we will show you how to create a workforce instance, add
65+
worker nodes to the workforce, and finally, how to start the workforce to
66+
solve tasks.
3967

40-
## How to use Workforce: A Step-by-Step Guide
68+
### Create a Workforce Instance
4169

42-
On this part, we will give you a step-by-step guide on how to use workforce to solve a task. You can see the full example used [here](https://github.com/camel-ai/camel/blob/master/examples/workforce/role_playing_with_agents.py).
43-
44-
### Configuration of Worker Nodes
45-
46-
A lot of the chores lie in the configurations of the worker nodes: we leave the full configuration freedom of each worker node to users, and we believe this is necessary to meet the desired performance and flexibility.
47-
48-
Therefore, inevitably there would be a lot of configurations that need to be done - and it takes up about 80 percent of the code. From this example, we can see that we first created two agents taking different roles
70+
To start using Workforce, you need to first create a workforce instance, and
71+
then add worker nodes to the workforce. Here is an example of how you can do
72+
this:
4973

5074
```python
51-
guide_sysmsg = BaseMessage.make_assistant_message(
52-
role_name="tour guide",
53-
content="You have to lead everyone to have fun",
54-
)
55-
56-
planner_sysmsg = BaseMessage.make_assistant_message(
57-
role_name="planner",
58-
content="good at tour plan.",
59-
)
75+
from camel.workforce import Workforce
6076

61-
guide_agent = ChatAgent(guide_sysmsg)
62-
planner_agent = ChatAgent(planner_sysmsg)
77+
# Create a workforce instance
78+
workforce = Workforce("A Simple Workforce")
6379
```
6480

65-
Then we wrapped them as two worker nodes with descriptions
81+
Now we get a workforce instance with description "A Simple Workforce".
82+
However, there is no worker node in the workforce yet.
6683

67-
```python
68-
guide_worker_node = SingleAgentNode('tour guide', guide_agent)
69-
planner_worker_node = SingleAgentNode('planner', planner_agent)
70-
```
84+
> **Note: How to further customize the workforce**
85+
>
86+
> You can quickly create a workforce instance with default configurations
87+
> by just providing the description of the workforce. However, you can also
88+
> configure the workforce with more details, such as providing a list of
89+
> worker nodes directly instead of adding them one by one, or configuring
90+
> the coordinator agent and task planner agent by passing the configurations
91+
> to the workforce instance.
92+
93+
### Add Worker Nodes
94+
95+
After creating the workforce instance, you can add worker nodes to the
96+
workforce. To add a worker node, you need to first create worker agents
97+
that actually do the work.
7198

72-
Similarly, we also created some configurations for a `RolePlaying`.
99+
Suppose we have already created an `ChatAgent` that can do web searches
100+
called `search_agent`. Now we can add this worker agent to the workforce.
73101

74102
```python
75-
function_list = [
76-
*SEARCH_FUNCS,
77-
*WEATHER_FUNCS,
78-
*MAP_FUNCS,
79-
]
80-
user_model_config = ChatGPTConfig(temperature=0.0)
81-
assistant_model_config = ChatGPTConfig(
82-
tools=function_list,
83-
temperature=0.0,
84-
)
85-
model_platform = ModelPlatformType.OPENAI
86-
model_type = ModelType.GPT_4O_MINI
87-
assistant_role_name = "Searcher"
88-
user_role_name = "Professor"
89-
assistant_agent_kwargs = dict(
90-
model=ModelFactory.create(
91-
model_platform=model_platform,
92-
model_type=model_type,
93-
model_config_dict=assistant_model_config.as_dict(),
94-
),
95-
tools=function_list,
96-
)
97-
user_agent_kwargs = dict(
98-
model=ModelFactory.create(
99-
model_platform=model_platform,
100-
model_type=model_type,
101-
model_config_dict=user_model_config.as_dict(),
102-
),
103+
# Add the worker agent to the workforce
104+
workforce.add_single_agent_worker(
105+
"An agent that can do web searches",
106+
worker=search_agent,
103107
)
104108
```
105109

106-
And send these configurations into a worker node that uses `RolePlaying`.
110+
The adding function follows the fluent interface design pattern, so you can
111+
add multiple worker agents to the workforce in one line, like the following:
107112

108113
```python
109-
research_rp_worker_node = RolePlayingNode(
110-
'research Group',
111-
assistant_role_name,
112-
user_role_name,
113-
assistant_agent_kwargs,
114-
user_agent_kwargs,
115-
1,
114+
workforce.add_single_agent_worker(
115+
"An agent that can do web searches",
116+
worker=search_agent,
117+
).add_single_agent_worker(
118+
"Another agent",
119+
worker=another_agent,
120+
).add_single_agent_worker(
121+
"Yet another agent",
122+
worker=yet_another_agent,
116123
)
117124
```
118125

119-
> Note here, we didn’t directly create a `RolePlaying` instance and wrap it inside a worker node but passed its configurations into a worker node. This is because `RolePlaying` is designed to be recreated for each task, therefore the instantiation will be managed by the worker node itself, which is different from the `SingleAgentNode`.
126+
Now we have some worker agents in the workforce. It's time to create a task and
127+
let the workforce solve it.
120128

121-
If you make it here, congratulations! You have finished the configuration, and it’s the first and biggest step. Finishing this means you are almost done.
129+
> **Note: The description is NOT trivial**
130+
>
131+
> When adding an agent to the workforce as a worker node, the first argument
132+
> is the description of the worker node. Though it seems trivial, it is
133+
> actually very important. The description will be used by the coordinator
134+
> agent as the basis to assign tasks to the worker nodes. Therefore, it is
135+
> recommended to provide a clear and concise description of the worker node.
122136
123-
### Create Task
137+
### Start the Workforce
124138

125-
The task is what a workforce will solve. To create a task, simply pass in the content and the initial id.
139+
After adding worker nodes to the workforce, you can start the workforce to
140+
solve tasks. First we can define a task:
126141

127142
```python
128-
human_task = Task(
129-
content="research history of Paris and plan a tour.",
130-
id='0',
131-
)
132-
```
133-
134-
### Create Manager Node
143+
from camel.tasks import Task
135144

136-
To make these worker nodes collaborate with each other, we need to create a manager node to coordinate them by passing in these worker nodes as the `children`.
137-
138-
```python
139-
root_node = ManagerNode(
140-
description='a travel group',
141-
children=[
142-
guide_worker_node,
143-
planner_worker_node,
144-
research_rp_worker_node,
145-
],
145+
# the id of the task can be any string to mark the task
146+
task = Task(
147+
content="Make a travel plan for a 3-day trip to Paris.",
148+
id="0",
146149
)
147150
```
148151

149-
> Note that, inside the manager node there will also be two agents, `coordinator_agent` and `task_planner` who will help on the coordination. To configure these, pass `coordinator_agent_kwargs` and `task_agent_kwargs` into `ManagerNode`. Check the API docs for more information.
150-
151-
### Create Workforce & Process Task
152-
153-
Because we only have one layer in the current design of the workforce, this manager node also works as the root of the workforce.
154-
155-
We can create a workforce by passing the root node, and then call `process_task()` to start the workforce to work on the task.
152+
Then we can start the workforce with the task:
156153

157154
```python
158-
workforce = Workforce(root_node)
159-
task = workforce.process_task(human_task)
155+
task = workforce.process_task(task)
160156
```
161157

162-
Finally, we can get the result of the task by checking `task.result`.
158+
The final result of the task will be stored in the `result` attribute of the
159+
task object. You can check the result by:
163160

164161
```python
165-
print('Final Result of Origin task:\n', task.result)
162+
print(task.result)
166163
```
167-
168-
Here is one example of the output:
169-
170-
```markdown
171-
>>>
172-
Here is the finalized tour plan for your visit to historical sites in Paris, ensuring all logistics are accounted for:
173-
174-
**Tour Itinerary:**
175-
176-
**8:30 AM - 9:30 AM: Eiffel Tower**
177-
- Start your day early at the Eiffel Tower. Allocate about 1 hour to explore the area and take photos. Consider pre-booking tickets to avoid long queues.
178-
179-
**10:00 AM - 10:30 AM: Arc de Triomphe**
180-
- Travel to the Arc de Triomphe (approximately 30 minutes by walking or metro). Spend about 30 minutes here to admire the architecture and take in the views from the top if you choose to climb.
181-
182-
**11:00 AM - 12:30 PM: Montmartre (Basilica of the Sacré-Cœur)**
183-
- Head to Montmartre (about 30 minutes travel time). Spend around 1.5 hours exploring the Basilica and the charming streets of this historic district.
184-
185-
**1:00 PM - 2:00 PM: Lunch**
186-
- Enjoy lunch at a nearby café in Montmartre or head towards the Panthéon area.
187-
188-
**2:30 PM - 3:30 PM: Panthéon**
189-
- After lunch, visit the Panthéon (approximately 30 minutes travel time). Allocate about 1 hour to explore this mausoleum and its impressive architecture.
190-
191-
**4:00 PM - 5:00 PM: Sainte-Chapelle**
192-
- Travel to Sainte-Chapelle (about 15 minutes). Spend around 1 hour admiring the stunning stained glass windows.
193-
194-
**5:15 PM - 6:15 PM: Notre-Dame Cathedral**
195-
- Walk to Notre-Dame Cathedral (approximately 5 minutes). Spend about 1 hour here. Note that access may be limited due to restoration work.
196-
197-
**6:30 PM - 7:00 PM: Place de la Bastille**
198-
- Head to Place de la Bastille (about 15 minutes). Spend around 30 minutes exploring the square and its significance.
199-
200-
**7:15 PM - 8:00 PM: Les Invalides**
201-
- Travel to Les Invalides (approximately 20 minutes). Allocate about 45 minutes to explore the complex and visit Napoleon's tomb.
202-
203-
**8:30 PM - 10:00 PM: The Louvre Museum**
204-
- Head to The Louvre Museum (about 20 minutes). Spend around 1.5 hours exploring the museum. If possible, book a timed entry ticket to avoid long waits.
205-
206-
**10:30 PM - 11:45 PM: Palace of Versailles**
207-
- End your day with a visit to the Palace of Versailles. Note that this may require a separate trip, as it is located outside of central Paris. Allocate sufficient time for travel (approximately 1 hour) and plan to arrive before closing.
208-
209-
**Transportation:**
210-
- Use a combination of walking and public transport (metro and buses) for efficient travel between sites. Consider purchasing a day pass for unlimited travel on public transport.
211-
212-
**Additional Notes:**
213-
- Check the opening hours and any potential closures in advance to ensure a smooth experience.
214-
- Pre-book tickets for popular sites to avoid long queues.
215-
216-
This itinerary allows you to efficiently visit each site while enjoying the rich history and culture of Paris.
217-
```

0 commit comments

Comments
 (0)