đ« 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: add doc for workforce (#786)
Isaac Jind89931686dc3
diff --git a/docs/key_modules/workforce.md b/docs/key_modules/workforce.mdnew file mode 100644index 000000000..a7c9c0b98--- /dev/null+++ b/docs/key_modules/workforce.md@@ -0,0 +1,219 @@+# Workforce++> 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.++> *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+).*++## Architecture++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.++> For now, CAMEL only supports the mode with one manager as root and multiple workers as direct leaf nodes of the root.++All manager and worker nodes share a single channel, where they can post and receive tasks, broadcast task results, etc.++## Workflow++In this section we are going to talk about how workforce works under the hood, briefly.++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.++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.++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.++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.++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:++1. decompose the task into smaller ones and assign them again+2. create a new worker that is capable of doing the task++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.++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.++### A Diagram with Simple Example++Here is a diagram illustrating the workflow with a simple example:++++## How to use Workforce: A Step-by-Step Guide++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).++### Configuration of Worker Nodes++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.++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++```python+guide_sysmsg = BaseMessage.make_assistant_message(+ role_name="tour guide",+ content="You have to lead everyone to have fun",+)++planner_sysmsg = BaseMessage.make_assistant_message(+ role_name="planner",+ content="good at tour plan.",+)++guide_agent = ChatAgent(guide_sysmsg)+planner_agent = ChatAgent(planner_sysmsg)+```++Then we wrapped them as two worker nodes with descriptions++```python+guide_worker_node = SingleAgentNode('tour guide', guide_agent)+planner_worker_node = SingleAgentNode('planner', planner_agent)+```++Similarly, we also created some configurations for a `RolePlaying`.++```python+function_list = [+ *SEARCH_FUNCS,+ *WEATHER_FUNCS,+ *MAP_FUNCS,+]+user_model_config = ChatGPTConfig(temperature=0.0)+assistant_model_config = ChatGPTConfig(+ tools=function_list,+ temperature=0.0,+)+model_platform = ModelPlatformType.OPENAI+model_type = ModelType.GPT_4O_MINI+assistant_role_name = "Searcher"+user_role_name = "Professor"+assistant_agent_kwargs = dict(+ model=ModelFactory.create(+ model_platform=model_platform,+ model_type=model_type,+ model_config_dict=assistant_model_config.as_dict(),+ ),+ tools=function_list,+)+user_agent_kwargs = dict(+ model=ModelFactory.create(+ model_platform=model_platform,+ model_type=model_type,+ model_config_dict=user_model_config.as_dict(),+ ),+)+```++And send these configurations into a worker node that uses `RolePlaying`.++```python+research_rp_worker_node = RolePlayingNode(+ 'research Group',+ assistant_role_name,+ user_role_name,+ assistant_agent_kwargs,+ user_agent_kwargs,+ 1,+)+```++> 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`.++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.++### Create Task++The task is what a workforce will solve. To create a task, simply pass in the content and the initial id.++```python+human_task = Task(+ content="research history of Paris and plan a tour.",+ id='0',+)+```++### Create Manager Node++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`.++```python+root_node = ManagerNode(+ description='a travel group',+ children=[+ guide_worker_node,+ planner_worker_node,+ research_rp_worker_node,+ ],+)+```++> 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.++### Create Workforce & Process Task++Because we only have one layer in the current design of the workforce, this manager node also works as the root of the workforce.++We can create a workforce by passing the root node, and then call `process_task()` to start the workforce to work on the task.++```python+workforce = Workforce(root_node)+task = workforce.process_task(human_task)+```++Finally, we can get the result of the task by checking `task.result`.++```python+print('Final Result of Origin task:\n', task.result)+```++Here is one example of the output:++```markdown+>>>+Here is the finalized tour plan for your visit to historical sites in Paris, ensuring all logistics are accounted for:++**Tour Itinerary:**++**8:30 AM - 9:30 AM: Eiffel Tower**+- 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.++**10:00 AM - 10:30 AM: Arc de Triomphe**+- 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.++**11:00 AM - 12:30 PM: Montmartre (Basilica of the SacrĂ©-CĆur)**+- Head to Montmartre (about 30 minutes travel time). Spend around 1.5 hours exploring the Basilica and the charming streets of this historic district.++**1:00 PM - 2:00 PM: Lunch**+- Enjoy lunch at a nearby cafĂ© in Montmartre or head towards the PanthĂ©on area.++**2:30 PM - 3:30 PM: PanthĂ©on**+- After lunch, visit the PanthĂ©on (approximately 30 minutes travel time). Allocate about 1 hour to explore this mausoleum and its impressive architecture.++**4:00 PM - 5:00 PM: Sainte-Chapelle**+- Travel to Sainte-Chapelle (about 15 minutes). Spend around 1 hour admiring the stunning stained glass windows.++**5:15 PM - 6:15 PM: Notre-Dame Cathedral**+- Walk to Notre-Dame Cathedral (approximately 5 minutes). Spend about 1 hour here. Note that access may be limited due to restoration work.++**6:30 PM - 7:00 PM: Place de la Bastille**+- Head to Place de la Bastille (about 15 minutes). Spend around 30 minutes exploring the square and its significance.++**7:15 PM - 8:00 PM: Les Invalides**+- Travel to Les Invalides (approximately 20 minutes). Allocate about 45 minutes to explore the complex and visit Napoleon's tomb.++**8:30 PM - 10:00 PM: The Louvre Museum**+- 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.++**10:30 PM - 11:45 PM: Palace of Versailles**+- 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.++**Transportation:**+- 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.++**Additional Notes:**+- Check the opening hours and any potential closures in advance to ensure a smooth experience.+- Pre-book tickets for popular sites to avoid long queues.++This itinerary allows you to efficiently visit each site while enjoying the rich history and culture of Paris.+```\ No newline at end of filediff --git a/poetry.lock b/poetry.lockindex 5eca7fd70..e11071eee 100644--- a/poetry.lock+++ b/poetry.lock@@ -446,13 +446,13 @@ files = [[[package]]name = "azure-core"-version = "1.30.2"+version = "1.31.0"description = "Microsoft Azure Core Library for Python"optional = truepython-versions = ">=3.8"files = [- {file = "azure-core-1.30.2.tar.gz", hash = "sha256:a14dc210efcd608821aa472d9fb8e8d035d29b68993819147bc290a8ac224472"},- {file = "azure_core-1.30.2-py3-none-any.whl", hash = "sha256:cf019c1ca832e96274ae85abd3d9f752397194d9fea3b41487290562ac8abe4a"},+ {file = "azure_core-1.31.0-py3-none-any.whl", hash = "sha256:22954de3777e0250029360ef31d80448ef1be13b80a459bff80ba7073379e2cd"},+ {file = "azure_core-1.31.0.tar.gz", hash = "sha256:656a0dd61e1869b1506b7c6a3b31d62f15984b1a573d6326f6aa2f3e4123284b"},][package.dependencies]@@ -546,13 +546,13 @@ lxml = ["lxml"][[package]]name = "botocore"-version = "1.35.17"+version = "1.35.18"description = "Low-level, data-driven core of boto 3."optional = truepython-versions = ">=3.8"files = [- {file = "botocore-1.35.17-py3-none-any.whl", hash = "sha256:a93f773ca93139529b5d36730b382dbee63ab4c7f26129aa5c84835255ca999d"},- {file = "botocore-1.35.17.tar.gz", hash = "sha256:0d35d03ea647b5d464c7f77bdab6fb23ae5d49752b13cf97ab84444518c7b1bd"},+ {file = "botocore-1.35.18-py3-none-any.whl", hash = "sha256:1027083aeb1fe74057273410fd768e018e22f85adfbd717b5a69f578f7812b80"},+ {file = "botocore-1.35.18.tar.gz", hash = "sha256:e59da8b91ab06683d2725b6cbbb0383b30c68a241c3c63363f4c5bff59b3c0c0"},][package.dependencies]@@ -3239,13 +3239,13 @@ files = [[[package]]name = "litellm"-version = "1.44.25"+version = "1.45.0"description = "Library to easily interface with LLM API providers"optional = truepython-versions = "!=2.7.*,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,>=3.8"files = [- {file = "litellm-1.44.25-py3-none-any.whl", hash = "sha256:c5bae63f2d6683c6c7dba0fdb313e5a0b60b3c70cc67e588a64a87ebdf01eede"},- {file = "litellm-1.44.25.tar.gz", hash = "sha256:8ff8326a5f33183684819eba88d89ecbecedbb19c35baea6a3b84bf1c0795e5e"},+ {file = "litellm-1.45.0-py3-none-any.whl", hash = "sha256:87d712beabc6cbf24437557186c5b266729f3139bf7dd2e54573e1e9845b905a"},+ {file = "litellm-1.45.0.tar.gz", hash = "sha256:21285496e72b9b16ff9d3d1332965c3d1a9b0ae8dbb26f27a7080af28a117174"},][package.dependencies]@@ -3254,7 +3254,7 @@ click = "*"importlib-metadata = ">=6.8.0"jinja2 = ">=3.1.2,<4.0.0"jsonschema = ">=4.22.0,<5.0.0"-openai = ">=1.40.0"+openai = ">=1.45.0"pydantic = ">=2.0.0,<3.0.0"python-dotenv = ">=0.2.0"requests = ">=2.31.0,<3.0.0"@@ -3888,13 +3888,13 @@ files = [[[package]]name = "narwhals"-version = "1.7.0"+version = "1.8.0"description = "Extremely lightweight compatibility layer between dataframe libraries"optional = falsepython-versions = ">=3.8"files = [- {file = "narwhals-1.7.0-py3-none-any.whl", hash = "sha256:40d8c0457743540276d6e8b2add31affa1c8936035d378838000c281d8f5921f"},- {file = "narwhals-1.7.0.tar.gz", hash = "sha256:2d769c9dd23bd355632a813eb65d5cae6bad595c4058387acfb7fa86db50a0e9"},+ {file = "narwhals-1.8.0-py3-none-any.whl", hash = "sha256:73bde7b1721e1d95f749f6aacec12bc616fcccae5a926064d641c93e133fd548"},+ {file = "narwhals-1.8.0.tar.gz", hash = "sha256:b1572b8781273e5712ee76144b9b6f412f2b71f39d63053853322cc98201eeaa"},][package.extras]@@ -8746,13 +8746,13 @@ multidict = ">=4.0"[[package]]name = "zipp"-version = "3.20.1"+version = "3.20.2"description = "Backport of pathlib-compatible object wrapper for zip files"optional = truepython-versions = ">=3.8"files = [- {file = "zipp-3.20.1-py3-none-any.whl", hash = "sha256:9960cd8967c8f85a56f920d5d507274e74f9ff813a0ab8889a5b5be2daf44064"},- {file = "zipp-3.20.1.tar.gz", hash = "sha256:c22b14cc4763c5a5b04134207736c107db42e9d3ef2d9779d465f5f1bcba572b"},+ {file = "zipp-3.20.2-py3-none-any.whl", hash = "sha256:a817ac80d6cf4b23bf7f2828b7cabf326f15a001bea8b1f9b49631780ba28350"},+ {file = "zipp-3.20.2.tar.gz", hash = "sha256:bc9eb26f4506fda01b81bcde0ca78103b6e62f991b381fec825435c836edbc29"},][package.extras]diff --git a/test/workforce/test_signle_agent.py b/test/workforce/test_single_agent.pysimilarity index 100%rename from test/workforce/test_signle_agent.pyrename to test/workforce/test_single_agent.py