ag2 0.10.2__py3-none-any.whl

autogen/agentchat/group/multi_agent_chat.py

@@ -0,0 +1,291 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import asyncio
+import threading
+from typing import TYPE_CHECKING, Any
+
+from ...doc_utils import export_module
+from ...events.agent_events import ErrorEvent, RunCompletionEvent
+from ...io.base import IOStream
+from ...io.run_response import AsyncRunResponse, AsyncRunResponseProtocol, RunResponse, RunResponseProtocol
+from ...io.thread_io_stream import AsyncThreadIOStream, ThreadIOStream
+from ...llm_config import LLMConfig
+from ..chat import ChatResult
+from .context_variables import ContextVariables
+from .group_utils import cleanup_temp_user_messages
+
+if TYPE_CHECKING:
+    from ..agent import Agent
+    from .patterns.pattern import Pattern
+
+__all__ = [
+    "a_initiate_group_chat",
+    "a_run_group_chat",
+    "initiate_group_chat",
+    "run_group_chat",
+]
+
+
+@export_module("autogen")
+def initiate_group_chat(
+    pattern: "Pattern",
+    messages: list[dict[str, Any]] | str,
+    max_rounds: int = 20,
+    safeguard_policy: dict[str, Any] | str | None = None,
+    safeguard_llm_config: LLMConfig | None = None,
+    mask_llm_config: LLMConfig | None = None,
+) -> tuple[ChatResult, ContextVariables, "Agent"]:
+    """Initialize and run a group chat using a pattern for configuration.
+
+    Args:
+        pattern: Pattern object that encapsulates the chat configuration.
+        messages: Initial message(s).
+        max_rounds: Maximum number of conversation rounds.
+        safeguard_policy: Optional safeguard policy dict or path to JSON file.
+        safeguard_llm_config: Optional LLM configuration for safeguard checks.
+        mask_llm_config: Optional LLM configuration for masking.
+
+    Returns:
+        ChatResult:         Conversations chat history.
+        ContextVariables:   Updated Context variables.
+        "ConversableAgent":   Last speaker.
+    """
+    # Let the pattern prepare the group chat and all its components
+    # Only passing the necessary parameters that aren't already in the pattern
+    (
+        _,  # agents,
+        _,  # wrapped_agents,
+        _,  # user_agent,
+        context_variables,
+        _,  # initial_agent,
+        _,  # group_after_work,
+        _,  # tool_execution,
+        _,  # groupchat,
+        manager,
+        processed_messages,
+        last_agent,
+        _,  # group_agent_names,
+        _,  # temp_user_list,
+    ) = pattern.prepare_group_chat(
+        max_rounds=max_rounds,
+        messages=messages,
+    )
+
+    # Apply safeguards if provided
+    if safeguard_policy:
+        from .safeguards import apply_safeguard_policy
+
+        apply_safeguard_policy(
+            groupchat_manager=manager,
+            policy=safeguard_policy,
+            safeguard_llm_config=safeguard_llm_config,
+            mask_llm_config=mask_llm_config,
+        )
+
+    # Start or resume the conversation
+    if len(processed_messages) > 1:
+        last_agent, last_message = manager.resume(messages=processed_messages)
+        clear_history = False
+    else:
+        last_message = processed_messages[0]
+        clear_history = True
+
+    if last_agent is None:
+        raise ValueError("No agent selected to start the conversation")
+
+    chat_result = last_agent.initiate_chat(
+        manager,
+        message=last_message,
+        clear_history=clear_history,
+        summary_method=pattern.summary_method,
+    )
+
+    cleanup_temp_user_messages(chat_result)
+
+    return chat_result, context_variables, manager.last_speaker
+
+
+@export_module("autogen.agentchat")
+async def a_initiate_group_chat(
+    pattern: "Pattern",
+    messages: list[dict[str, Any]] | str,
+    max_rounds: int = 20,
+    safeguard_policy: dict[str, Any] | str | None = None,
+    safeguard_llm_config: LLMConfig | None = None,
+    mask_llm_config: LLMConfig | None = None,
+) -> tuple[ChatResult, ContextVariables, "Agent"]:
+    """Initialize and run a group chat using a pattern for configuration, asynchronously.
+
+    Args:
+        pattern: Pattern object that encapsulates the chat configuration.
+        messages: Initial message(s).
+        max_rounds: Maximum number of conversation rounds.
+        safeguard_policy: Optional safeguard policy dict or path to JSON file.
+        safeguard_llm_config: Optional LLM configuration for safeguard checks.
+        mask_llm_config: Optional LLM configuration for masking.
+
+    Returns:
+        ChatResult:         Conversations chat history.
+        ContextVariables:   Updated Context variables.
+        "ConversableAgent":   Last speaker.
+    """
+    # Let the pattern prepare the group chat and all its components
+    # Only passing the necessary parameters that aren't already in the pattern
+    (
+        _,  # agents,
+        _,  # wrapped_agents,
+        _,  # user_agent,
+        context_variables,
+        _,  # initial_agent,
+        _,  # group_after_work,
+        _,  # tool_execution,
+        _,  # groupchat,
+        manager,
+        processed_messages,
+        last_agent,
+        _,  # group_agent_names,
+        _,  # temp_user_list,
+    ) = pattern.prepare_group_chat(
+        max_rounds=max_rounds,
+        messages=messages,
+    )
+
+    # Apply safeguards if provided
+    if safeguard_policy:
+        from .safeguards import apply_safeguard_policy
+
+        apply_safeguard_policy(
+            groupchat_manager=manager,
+            policy=safeguard_policy,
+            safeguard_llm_config=safeguard_llm_config,
+            mask_llm_config=mask_llm_config,
+        )
+
+    # Start or resume the conversation
+    if len(processed_messages) > 1:
+        last_agent, last_message = await manager.a_resume(messages=processed_messages)
+        clear_history = False
+    else:
+        last_message = processed_messages[0]
+        clear_history = True
+
+    if last_agent is None:
+        raise ValueError("No agent selected to start the conversation")
+
+    chat_result = await last_agent.a_initiate_chat(
+        manager,
+        message=last_message,  # type: ignore[arg-type]
+        clear_history=clear_history,
+        summary_method=pattern.summary_method,
+    )
+
+    cleanup_temp_user_messages(chat_result)
+
+    return chat_result, context_variables, manager.last_speaker
+
+
+@export_module("autogen.agentchat")
+def run_group_chat(
+    pattern: "Pattern",
+    messages: list[dict[str, Any]] | str,
+    max_rounds: int = 20,
+    safeguard_policy: dict[str, Any] | str | None = None,
+    safeguard_llm_config: LLMConfig | None = None,
+    mask_llm_config: LLMConfig | None = None,
+) -> RunResponseProtocol:
+    iostream = ThreadIOStream()
+    # todo: add agents
+    response = RunResponse(iostream, agents=[])
+
+    def _initiate_group_chat(
+        pattern: "Pattern" = pattern,
+        messages: list[dict[str, Any]] | str = messages,
+        max_rounds: int = max_rounds,
+        safeguard_policy: dict[str, Any] | str | None = safeguard_policy,
+        safeguard_llm_config: LLMConfig | None = safeguard_llm_config,
+        mask_llm_config: LLMConfig | None = mask_llm_config,
+        iostream: ThreadIOStream = iostream,
+        response: RunResponse = response,
+    ) -> None:
+        with IOStream.set_default(iostream):
+            try:
+                chat_result, context_vars, agent = initiate_group_chat(
+                    pattern=pattern,
+                    messages=messages,
+                    max_rounds=max_rounds,
+                    safeguard_policy=safeguard_policy,
+                    safeguard_llm_config=safeguard_llm_config,
+                    mask_llm_config=mask_llm_config,
+                )
+
+                IOStream.get_default().send(
+                    RunCompletionEvent(  # type: ignore[call-arg]
+                        history=chat_result.chat_history,
+                        summary=chat_result.summary,
+                        cost=chat_result.cost,
+                        last_speaker=agent.name,
+                        context_variables=context_vars,
+                    )
+                )
+            except Exception as e:
+                response.iostream.send(ErrorEvent(error=e))  # type: ignore[call-arg]
+
+    threading.Thread(
+        target=_initiate_group_chat,
+    ).start()
+
+    return response
+
+
+@export_module("autogen.agentchat")
+async def a_run_group_chat(
+    pattern: "Pattern",
+    messages: list[dict[str, Any]] | str,
+    max_rounds: int = 20,
+    safeguard_policy: dict[str, Any] | str | None = None,
+    safeguard_llm_config: LLMConfig | None = None,
+    mask_llm_config: LLMConfig | None = None,
+) -> AsyncRunResponseProtocol:
+    iostream = AsyncThreadIOStream()
+    # todo: add agents
+    response = AsyncRunResponse(iostream, agents=[])
+
+    async def _initiate_group_chat(
+        pattern: "Pattern" = pattern,
+        messages: list[dict[str, Any]] | str = messages,
+        max_rounds: int = max_rounds,
+        safeguard_policy: dict[str, Any] | str | None = safeguard_policy,
+        safeguard_llm_config: LLMConfig | None = safeguard_llm_config,
+        mask_llm_config: LLMConfig | None = mask_llm_config,
+        iostream: AsyncThreadIOStream = iostream,
+        response: AsyncRunResponse = response,
+    ) -> None:
+        with IOStream.set_default(iostream):
+            try:
+                chat_result, context_vars, agent = await a_initiate_group_chat(
+                    pattern=pattern,
+                    messages=messages,
+                    max_rounds=max_rounds,
+                    safeguard_policy=safeguard_policy,
+                    safeguard_llm_config=safeguard_llm_config,
+                    mask_llm_config=mask_llm_config,
+                )
+
+                IOStream.get_default().send(
+                    RunCompletionEvent(  # type: ignore[call-arg]
+                        history=chat_result.chat_history,
+                        summary=chat_result.summary,
+                        cost=chat_result.cost,
+                        last_speaker=agent.name,
+                        context_variables=context_vars,
+                    )
+                )
+            except Exception as e:
+                response.iostream.send(ErrorEvent(error=e))  # type: ignore[call-arg]
+
+    task = asyncio.create_task(_initiate_group_chat())
+    # prevent the task from being garbage collected
+    response._task_ref = task  # type: ignore[attr-defined]
+    return response

autogen/agentchat/group/on_condition.py

@@ -0,0 +1,55 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+from pydantic import BaseModel
+
+from ...doc_utils import export_module
+from .available_condition import AvailableCondition
+from .llm_condition import LLMCondition
+from .targets.transition_target import TransitionTarget
+
+__all__ = [
+    "OnCondition",
+]
+
+
+@export_module("autogen")
+class OnCondition(BaseModel):  # noqa: N801
+    """Defines a condition for transitioning to another agent or nested chats.\n
+    \n
+        This is for LLM-based condition evaluation where these conditions are translated into tools and attached to the agent.\n
+    \n
+        These are evaluated after the OnCondition conditions but before the after work condition.\n
+    \n
+        Args:\n
+            target (TransitionTarget): The transition (essentially an agent) to hand off to.\n
+            condition (LLMCondition): The condition for transitioning to the target agent, evaluated by the LLM.\n
+            available (AvailableCondition): Optional condition to determine if this OnCondition is included for the LLM to evaluate based on context variables using classes like StringAvailableCondition and ContextExpressionAvailableCondition.\n
+            llm_function_name (Optional[str]): The name of the LLM function to use for this condition.\n
+    """
+
+    target: TransitionTarget
+    condition: LLMCondition
+    available: AvailableCondition | None = None
+    llm_function_name: str | None = None
+
+    def has_target_type(self, target_type: type) -> bool:
+        """Check if the target type matches the specified type.
+
+        Args:
+            target_type (type): The target type to check against, which should be a subclass of TransitionTarget
+
+        Returns:
+            bool: True if the target type matches, False otherwise
+        """
+        return isinstance(self.target, target_type)
+
+    def target_requires_wrapping(self) -> bool:
+        """Check if the target requires wrapping in an agent.
+
+        Returns:
+            bool: True if the target requires wrapping, False otherwise
+        """
+        return self.target.needs_agent_wrapper()

autogen/agentchat/group/on_context_condition.py

@@ -0,0 +1,51 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+from pydantic import BaseModel
+
+from .available_condition import AvailableCondition
+from .context_condition import ContextCondition
+from .targets.transition_target import TransitionTarget
+
+__all__ = [
+    "OnContextCondition",
+]
+
+
+class OnContextCondition(BaseModel):  # noqa: N801
+    """Defines a condition for transitioning to another agent or nested chats using context variables and the ContextExpression class.
+
+    This is for context variable-based condition evaluation (does not use the agent's LLM).
+
+    These are evaluated before the OnCondition and after work conditions.
+
+    Args:
+        target (TransitionTarget): The transition (essentially an agent) to hand off to.
+        condition (Optional[ContextCondition]): The context variable based condition for transitioning to the target agent. If None, the condition always evaluates to True.
+        available (AvailableCondition): Optional condition to determine if this OnCondition is included for the LLM to evaluate based on context variables using classes like StringAvailableCondition and ContextExpressionAvailableCondition.
+    """
+
+    target: TransitionTarget
+    condition: ContextCondition | None = None
+    available: AvailableCondition | None = None
+
+    def has_target_type(self, target_type: type) -> bool:
+        """Check if the target type matches the specified type.
+
+        Args:
+            target_type (type): The target type to check against. Should be a subclass of TransitionTarget.
+
+        Returns:
+            bool: True if the target type matches, False otherwise
+        """
+        return isinstance(self.target, target_type)
+
+    def target_requires_wrapping(self) -> bool:
+        """Check if the target requires wrapping in an agent.
+
+        Returns:
+            bool: True if the target requires wrapping, False otherwise
+        """
+        return self.target.needs_agent_wrapper()

autogen/agentchat/group/patterns/__init__.py

@@ -0,0 +1,18 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+from .auto import AutoPattern
+from .manual import ManualPattern
+from .pattern import DefaultPattern
+from .random import RandomPattern
+from .round_robin import RoundRobinPattern
+
+__all__ = [
+    "AutoPattern",
+    "DefaultPattern",
+    "ManualPattern",
+    "RandomPattern",
+    "RoundRobinPattern",
+]

autogen/agentchat/group/patterns/auto.py

@@ -0,0 +1,160 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Optional
+
+from ..context_variables import ContextVariables
+from ..targets.group_manager_target import GroupManagerSelectionMessage, GroupManagerTarget
+from ..targets.transition_target import TransitionTarget
+from .pattern import Pattern
+
+if TYPE_CHECKING:
+    from ...conversable_agent import ConversableAgent
+    from ...groupchat import GroupChat, GroupChatManager
+    from ..group_tool_executor import GroupToolExecutor
+
+
+class AutoPattern(Pattern):
+    """AutoPattern implements a flexible pattern where agents are selected based on their expertise.
+
+    In this pattern, a group manager automatically selects the next agent to speak based on the context
+    of the conversation and agent descriptions. The after_work is always set to "group_manager" as
+    this is the defining characteristic of this pattern.
+    """
+
+    def __init__(
+        self,
+        initial_agent: "ConversableAgent",
+        agents: list["ConversableAgent"],
+        user_agent: Optional["ConversableAgent"] = None,
+        group_manager_args: dict[str, Any] | None = None,
+        context_variables: ContextVariables | None = None,
+        selection_message: GroupManagerSelectionMessage | None = None,
+        exclude_transit_message: bool = True,
+        summary_method: str | Callable[..., Any] | None = "last_msg",
+    ):
+        """Initialize the AutoPattern.
+
+        The after_work is always set to group_manager selection, which is the defining
+        characteristic of this pattern. You can customize the selection message used
+        by the group manager when selecting the next agent.
+
+        Args:
+            initial_agent: The first agent to speak in the group chat.
+            agents: List of all agents participating in the chat.
+            user_agent: Optional user proxy agent.
+            group_manager_args: Optional arguments for the GroupChatManager.
+            context_variables: Initial context variables for the chat.
+            selection_message: Custom message to use when the group manager is selecting agents.
+            exclude_transit_message: Whether to exclude transit messages from the conversation.
+            summary_method: Method for summarizing the conversation.
+        """
+        # Create the group_manager after_work with the provided selection message
+        group_manager_after_work = GroupManagerTarget(selection_message=selection_message)
+
+        super().__init__(
+            initial_agent=initial_agent,
+            agents=agents,
+            user_agent=user_agent,
+            group_manager_args=group_manager_args,
+            context_variables=context_variables,
+            group_after_work=group_manager_after_work,
+            exclude_transit_message=exclude_transit_message,
+            summary_method=summary_method,
+        )
+
+        # Store the selection message for potential use
+        self.selection_message = selection_message
+
+    def prepare_group_chat(
+        self,
+        max_rounds: int,
+        messages: list[dict[str, Any]] | str,
+    ) -> tuple[
+        list["ConversableAgent"],
+        list["ConversableAgent"],
+        Optional["ConversableAgent"],
+        ContextVariables,
+        "ConversableAgent",
+        TransitionTarget,
+        "GroupToolExecutor",
+        "GroupChat",
+        "GroupChatManager",
+        list[dict[str, Any]],
+        Any,
+        list[str],
+        list[Any],
+    ]:
+        """Prepare the group chat for organic agent selection.
+
+        Ensures that:
+        1. The group manager has a valid LLM config
+        2. All agents have appropriate descriptions for the group manager to use
+
+        Args:
+            max_rounds: Maximum number of conversation rounds.
+            messages: Initial message(s) to start the conversation.
+
+        Returns:
+            Tuple containing all necessary components for the group chat.
+        """
+        # Validate that group_manager_args has an LLM config which is required for this pattern
+        if not self.group_manager_args.get("llm_config", False):
+            # Check if any agent has an LLM config we can use
+            has_llm_config = any(getattr(agent, "llm_config", False) for agent in self.agents)
+
+            if not has_llm_config:
+                raise ValueError(
+                    "AutoPattern requires the group_manager_args to include an llm_config, "
+                    "or at least one agent to have an llm_config"
+                )
+
+        # Check that all agents have descriptions for effective group manager selection
+        for agent in self.agents:
+            if not hasattr(agent, "description") or not agent.description:
+                agent.description = f"Agent {agent.name}"
+
+        # Use the parent class's implementation to prepare the agents and group chat
+        components = super().prepare_group_chat(
+            max_rounds=max_rounds,
+            messages=messages,
+        )
+
+        # Extract the group_after_work and the rest of the components
+        (
+            agents,
+            wrapped_agents,
+            user_agent,
+            context_variables,
+            initial_agent,
+            _,
+            tool_executor,
+            groupchat,
+            manager,
+            processed_messages,
+            last_agent,
+            group_agent_names,
+            temp_user_list,
+        ) = components
+
+        # Ensure we're using the group_manager after_work
+        group_after_work = self.group_after_work
+
+        # Return all components with our group_after_work
+        return (
+            agents,
+            wrapped_agents,
+            user_agent,
+            context_variables,
+            initial_agent,
+            group_after_work,
+            tool_executor,
+            groupchat,
+            manager,
+            processed_messages,
+            last_agent,
+            group_agent_names,
+            temp_user_list,
+        )