[Docs] Improved Conversation Patterns documentation

.secrets.baseline

@@ -2899,11 +2899,11 @@
         "is_secret": false
       }
     ],
-    "website/docs/user-guide/basic-concepts/llm-configuration.mdx": [
+    "website/docs/user-guide/basic-concepts/llm-configuration/llm-configuration.mdx": [
       {
         "type": "Secret Keyword",
-        "filename": "website/docs/user-guide/basic-concepts/llm-configuration.mdx",
-        "hashed_secret": "cf4a956e75901c220c0f5fbaec41987fc6177345",
+        "filename": "website/docs/user-guide/basic-concepts/llm-configuration/llm-configuration.mdx",
+        "hashed_secret": "1e3667aaaaa887721550cf5cc8a0c5c5760810ed",
         "is_verified": false,
         "line_number": 54,
         "is_secret": false
@@ -3116,5 +3116,5 @@
       }
     ]
   },
-  "generated_at": "2025-02-18T08:58:38Z"
+  "generated_at": "2025-02-18T14:15:34Z"
 }

autogen/agentchat/groupchat.py

@@ -665,6 +665,11 @@
         # Override the selector's config if one was passed as a parameter to this class
         speaker_selection_llm_config = self.select_speaker_auto_llm_config or selector.llm_config
 
+        if speaker_selection_llm_config is False:
+            raise ValueError(
+                "The group chat's internal speaker selection agent does not have an LLM configuration. Please provide a valid LLM config to the group chat's GroupChatManager or set it with the select_speaker_auto_llm_config parameter."
+            )
+
         # Agent for selecting a single agent name from the response
         speaker_selection_agent = ConversableAgent(
             "speaker_selection_agent",

website/_blogs/2023-10-18-RetrieveChat/index.mdx

@@ -152,9 +152,9 @@ compute embeddings. It's possible that you want to use OpenAI, Cohere, HuggingFa
 from chromadb.utils import embedding_functions
 
 openai_ef = embedding_functions.OpenAIEmbeddingFunction(
-                api_key="YOUR_API_KEY",
-                model_name="text-embedding-ada-002"
-            )
+    api_key="YOUR_API_KEY",
+    model_name="text-embedding-ada-002"
+)
 
 ragproxyagent = RetrieveUserProxyAgent(
     name="ragproxyagent",

website/docs/user-guide/advanced-concepts/custom-group-chat.mdx → website/docs/user-guide/advanced-concepts/groupchat/custom-group-chat.mdx

@@ -1,6 +1,6 @@
 ---
-title: Customized Group Chat flows
-sidebarTitle: Custom Group Chat
+title: Customized GroupChat flows
+sidebarTitle: Custom GroupChat
 ---
 
 <Tip>

website/docs/user-guide/basic-concepts/groupchat.mdx → website/docs/user-guide/advanced-concepts/groupchat/groupchat.mdx

@@ -1,5 +1,6 @@
 ---
 title: GroupChat
+sidebarTitle: Overview
 ---
 
 `GroupChat` has four built-in conversation patterns:

website/docs/user-guide/advanced-concepts/swarm/use-case.mdx

@@ -19,7 +19,7 @@ It's useful to draw your agents, flows, context variables, and tools and then cr
 
 This is the scenario we will run through, with customers able to enquire about their orders. However, we will make sure that they are authenticated to do so.
 
-![Swarm Enhanced Demonstration](./assets/swarm-enhanced-01.png)
+![Swarm Enhanced Demonstration](../assets/swarm-enhanced-01.png)
 
 Key aspects of this swarm are:
 
@@ -767,13 +767,13 @@ Using the three enhanced features of AG2's Swarm, we were able to control the fl
 Here's the flow above.
 
 At the beginning, we weren't logged in and there was only one path.
-![Swarm Enhanced Demonstration](./assets/swarm-enhanced-02.png)
+![Swarm Enhanced Demonstration](../assets/swarm-enhanced-02.png)
 
 After we logged in, we needed to get the order id.
-![Swarm Enhanced Demonstration](./assets/swarm-enhanced-03.png)
+![Swarm Enhanced Demonstration](../assets/swarm-enhanced-03.png)
 
 With the order id, we can handle order enquiries and retrieve order details.
-![Swarm Enhanced Demonstration](./assets/swarm-enhanced-04.png)
+![Swarm Enhanced Demonstration](../assets/swarm-enhanced-04.png)
 
 ### More Swarm examples
 - [Introduction to Swarm notebook](/docs/use-cases/notebooks/notebooks/agentchat_swarm)

website/docs/user-guide/basic-concepts/llm-configuration.mdx → website/docs/user-guide/basic-concepts/llm-configuration/llm-configuration.mdx

@@ -1,5 +1,5 @@
 ---
-title: LLM configuration
+title: LLMs
 ---
 
 Your AG2 agents are likely to need an LLM and you can configure one, or more, for each agent.
@@ -51,12 +51,12 @@ Set it in your terminal/command prompt:
 <Tabs>
   <Tab title="macOS / Linux">
     ```bash
-    export OPENAI_API_KEY="your_api_key_here"
+    export OPENAI_API_KEY="YOUR_API_KEY"
     ```
   </Tab>
   <Tab title="Windows">
     ```bash
-    setx OPENAI_API_KEY "your_api_key_here"
+    setx OPENAI_API_KEY "YOUR_API_KEY"
     ```
   </Tab>
 </Tabs>

website/docs/user-guide/basic-concepts/orchestration/nested-chat.mdx

@@ -0,0 +1,29 @@
+---
+Title: Nested chat
+---
+
+A powerful method to encapsulate a single workflow into an agent is through AG2's nested chats.
+
+Nested chats is powered by the nested chats handler, which is a pluggable component of [`ConversableAgent`](/docs/api-reference/autogen/ConversableAgent). The figure below illustrates how the nested chats handler triggers a sequence of nested chats when a message is received.
+
+![nested_chat](../assets/nested-chats.png)
+
+When a message comes in and passes the human-in-the-loop component, the nested chats handler checks if the message should trigger a nested chat based on conditions specified by the user.
+
+If the conditions are met, the nested chats handler starts a sequence of nested chats specified using the sequential chats pattern.
+
+In each of the nested chats, the sender agent is always the same agent that triggered the nested chats.
+
+In the end, the nested chat handler uses the results of the nested chats to produce a response to the original message (by default a summary of the last chat).
+
+Here is an example of a nested chat where a single agent, `lead_teacher_agent` encapsulates a workflow involving five other agents. This inner workflow includes two-agent chats and a group chat.
+
+The end result is that when this agent is called to reply in a chat it will, internally, run through a workflow using the nested chats and a fully considered lesson plan will be returned as its reply.
+
+import Example from "/snippets/python-examples/nestedchat.mdx";
+
+<Example/>
+
+Nested chat is a useful conversation pattern that allows you to package complex workflows into a single agent.
+
+For further information on setting up a nested chat, see the [`register_nested_chats`](/docs/api-reference/autogen/ConversableAgent#register-nested-chats) API reference and this [notebook](/docs/use-cases/notebooks/notebooks/agentchat_nested_chats_chess).

website/docs/user-guide/basic-concepts/orchestration/orchestrations.mdx

@@ -0,0 +1,22 @@
+---
+title: Orchestrating agents
+sidebarTitle: Overview
+---
+
+Many hands make for light work and orchestrating workflows containing many agents is a strength of the AG2 framework.
+
+1. **Two-agent chat**: The simplest form of conversation pattern where two agents chat back-and-forth with each other. This has been demonstrated in the previous examples.
+
+2. **Sequential chat**: A sequence of chats, each between two agents, chained together by a carryover mechanism (which brings the summary of the previous chat to the context of the next chat). Useful for simple sequential workflows.
+
+3. **Group chat**: A chat with more than two agents with options on how agents are selected. See [GroupChat Overview](/docs/user-guide/advanced-concepts/groupchat/groupchat) for further details.
+
+4. **Nested chat**: A mechanism to package a workflow into a single agent/chat for reuse in a workflow.
+
+5. **Swarm**: A pattern based on agents with handoffs. There's a shared context and each agent has tools and the ability to transfer control to other agents. The [original swarm concept](https://github.com/openai/swarm) was created by OpenAI.
+
+Continue on to explore these.
+
+<Note>
+We'll refer to *conversation patterns* throughout the documentation - they are simply a structured way of organizing the flow between agents.
+</Note>

website/docs/user-guide/basic-concepts/orchestration/sequential-chat.mdx

@@ -0,0 +1,37 @@
+---
+Title: Sequential chat
+---
+
+As a sequence of chats between two agents chained together by a mechanism called *carryover*, the sequential chat pattern is useful for complex tasks that can be broken down into interdependent sub-tasks.
+
+The figure below illustrates how this pattern works.
+
+![initiate_chats](../assets/sequential-two-agent-chat.png)
+
+In this pattern, a pair of agents start a two-agent chat, then the summary of the conversation becomes a *carryover* for the next two-agent chat. The next chat passes the carryover to the `carryover` parameter of the context to generate its initial message.
+
+Carryover accumulates as the conversation moves forward, so each subsequent chat starts with all the carryovers from previous chats.
+
+The figure above shows distinct recipient agents for all the chats, however, the recipient agents in the sequence are allowed to repeat.
+
+To illustrate this pattern, let's create a sequential workflow to create our lesson plan for the fourth grade class.
+
+A teacher agent will engage three agents sequentially:
+
+1. A curriculum designer will select a topic given the subject from the teacher
+2. A lesson planner will design the lesson with two iterations given feedback from the teacher
+3. A formatter will format the lesson
+
+import Example from "/snippets/python-examples/sequentialchat.mdx";
+
+<Example/>
+
+The sequential chat is triggered by the teacher agent's [`initiate_chats`](/docs/api-reference/autogen/ConversableAgent#initiate-chats) method, which takes a list of dictionaries where each dictionary represents a chat between the teacher and the `recipient` agent.
+
+The maximum number of turns in each chat can be controlled with the `max_turns` key. Each chat can also terminate before the `max_turns`, see the [Ending a Chat](/basic-concepts/orchestration/ending-a-chat) topic for further information.
+
+The result of the [`initiate_chats`](/docs/api-reference/autogen/ConversableAgent#initiate-chats) method returns a list of [`ChatResult`](/docs/api-reference/autogen/ChatResult) objects, one for each chat in the sequence.
+
+### Different senders
+
+In the above example, the teacher agent was the sender in each chat, however you can use the high-level [`initiate_chats`](/docs/api-reference/autogen/initiate_chats) function to start a sequence of two-agent chats with different sender agents. See this [notebook](/docs/use-cases/notebooks/notebooks/agentchats_sequential_chats#example-1-solve-tasks-with-a-series-of-chats) for an example.

website/docs/user-guide/basic-concepts/orchestration/swarm.mdx

@@ -0,0 +1,112 @@
+---
+title: Swarm
+---
+
+Swarms are a versatile pattern that provide flows between agents that are determined at the swarm or agent-level. The control of the flow is managed through various mechanisms, including hand-offs, post-tool transitions, post-work transitions, or an internal group chat manager, all of which determine the next agent (or end the swarm).
+
+The simplest swarm comprises of a group of agents and utilizes the swarm's internal manager (a [`GroupChatManager`](/docs/api-reference/autogen/GroupChatManager)) to decide, based on the conversation messages and the agent's descriptions, who should be the next agent.
+
+Here's an example.
+
+```python
+from autogen import ConversableAgent, AfterWorkOption, initiate_swarm_chat
+
+llm_config = {"api_type": "openai", "model": "gpt-4o-mini"}
+
+# 1. Create our agents
+planner_message = """You are a classroom lesson planner.
+Given a topic, write a lesson plan for a fourth grade class.
+If you are given revision feedback, update your lesson plan and record it.
+Use the following format:
+<title>Lesson plan title</title>
+<learning_objectives>Key learning objectives</learning_objectives>
+<script>How to introduce the topic to the kids</script>
+"""
+
+lesson_planner = ConversableAgent(
+    name="planner_agent", llm_config=llm_config, system_message=planner_message
+)
+
+reviewer_message = """You are a classroom lesson reviewer.
+You compare the lesson plan to the fourth grade curriculum
+and provide a maximum of 3 recommended changes for each review.
+Make sure you provide recommendations each time the plan is updated.
+"""
+
+lesson_reviewer = ConversableAgent(
+    name="reviewer_agent", llm_config=llm_config, system_message=reviewer_message
+)
+
+teacher_message = """You are a classroom teacher.
+You decide topics for lessons and work with a lesson planner.
+and reviewer to create and finalise lesson plans.
+"""
+
+teacher = ConversableAgent(
+    name="teacher_agent",
+    llm_config=llm_config,
+    system_message=teacher_message,
+)
+
+# 2. Initiate the swarm chat using a swarm manager who will
+# select agents automatically
+result, _, _ = initiate_swarm_chat(
+    initial_agent=teacher,
+    agents=[lesson_planner, lesson_reviewer, teacher],
+    messages="Today, let's introduce our kids to the solar system.",
+    max_rounds=10,
+    swarm_manager_args={"llm_config": llm_config},
+    after_work=AfterWorkOption.SWARM_MANAGER
+)
+```
+
+In this case, we create three agents, each with a detailed system message that will aid our swarm manager in working out the next best agent. There will also be a user agent (you) that may be transitioned to if the swarm manager thinks it needs further information or has finished.
+
+Let's examine the code:
+
+1. Create our three agents
+
+2. Initiate the chat
+
+    - All our agents are passed in to `agents`
+    - Our starting message is set in `messages`
+    - As we're using our swarm manager to select agents, we need to give them an LLM configuration, so we pass it in `swarm_manager_args`
+    - When each agent has spoken it will utilise the swarm's [`AfterWork`](/docs/api-reference/autogen/AfterWork) setting, in this case [`AfterWorkOption.SWARM_MANAGER`](/docs/api-reference/autogen/AfterWorkOption) set with the `after_work` parameter, indicating that the swarm manager is responsible for selecting the next agent.
+
+In this example, the swarm manager's LLM is solely responsible for deciding the next agent at each turn.
+
+### Controlling swarm transitions
+
+To gain more control over the transitions between agents, utilise hand-offs and after work transitions.
+
+When designing your swarm, think about your agents in a diagram with the lines between agents being your hand-offs. Each line will have a condition statement which an LLM will evaluate. Control stays with an agent while they execute their tools and once they've finished with their tools the conditions to transition will be evaluated.
+
+One of the unique aspects of a swarm is a shared context. ConversableAgents have a context dictionary but in a swarm that context is made common across all agents, allowing a state of the workflow to be maintained and viewed by all agents. This context can also be used within the hand off condition statements, providing more control of transitions.
+
+AG2's swarm has a number of unique capabilities, find out more in our [Swarm deep-dive](/docs/user-guide/advanced-concepts/swarm-deep-dive).
+
+Here's our lesson planner workflow using AG2's Swarm.
+
+import Example from "/snippets/python-examples/swarm.mdx";
+
+<Example/>
+
+
+1. Our shared context, available in function calls and on agents.
+
+2. Functions that represent the work the agents carry out, these the update shared context and, optionally, managed transitions.
+
+3. Agents setup with their tools, `functions`, and a system message and LLM configuration.
+
+4. The important hand-offs, defining the conditions for which to transfer to other agents and what to do after their work is finished (equivalent to no longer calling tools). Transfer conditions can be turned on/off using the `available` parameter.
+
+5. Kick off the swarm with our agents and shared context. Similar to `initiate_chat`, `initiate_swarm_chat` returns the chat result (messages and summary) and the final shared context.
+
+    ```console
+    Number of reviews: 2
+    Reviews remaining: 0
+    Final Lesson Plan:
+    <title>Exploring the Solar System</title>
+    <learning_objectives>Students will be able to identify and describe the planets in the Solar System, understand the concept of orbits, and recognize the sun as the center of our Solar System.</learning_objectives>
+    <script>Using a large poster of the Solar System, I will introduce the planets one by one, discussing key characteristics such as size, color, and distance from the sun. I will engage the students by asking questions about their favorite planets and what they know about them. We will do a quick demo using a simple model to show how planets orbit around the sun. Students will create their own solar system models in small groups with various materials to understand the scale and distance better, fostering teamwork. We will incorporate a multimedia presentation to visualize the orbits and relative sizes of the planets. Finally, a short assessment will be conducted at the end of the lesson to gauge students' understanding, using quizzes or presentations of their models.</script>
+    ```