ag2 0.9.1__py3-none-any.whl → 0.9.1.post0__py3-none-any.whl

autogen/agentchat/group/patterns/random.py

@@ -0,0 +1,106 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import TYPE_CHECKING, Any, Optional, Tuple, Union
+
+from ..context_variables import ContextVariables
+from ..targets.transition_target import RandomAgentTarget, 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 RandomPattern(Pattern):
+    """RandomPattern implements a random agent selection process."""
+
+    def _generate_handoffs(
+        self,
+        initial_agent: "ConversableAgent",
+        agents: list["ConversableAgent"],
+        user_agent: Optional["ConversableAgent"],
+    ) -> None:
+        """Generate handoffs between agents in a random fashion."""
+        agent_list = agents + ([user_agent] if user_agent is not None else [])
+
+        for agent in agent_list:
+            # Get the list of agents except itself
+            other_agents = [a for a in agent_list if a != agent]
+
+            # Create a random after work
+            agent.handoffs.set_after_work(target=RandomAgentTarget(agents=other_agents))
+
+    def prepare_group_chat(
+        self,
+        max_rounds: int,
+        messages: Union[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.
+        """
+        # Use the parent class's implementation to prepare the agents and group chat
+        (
+            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,
+        ) = super().prepare_group_chat(
+            max_rounds=max_rounds,
+            messages=messages,
+        )
+
+        # Create the random handoffs between agents
+        self._generate_handoffs(initial_agent=initial_agent, agents=agents, user_agent=user_agent)
+
+        # 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,
+        )

autogen/agentchat/group/patterns/round_robin.py

@@ -0,0 +1,117 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import TYPE_CHECKING, Any, Optional, Tuple, Union
+
+from ..context_variables import ContextVariables
+from ..targets.transition_target import AgentTarget, 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 RoundRobinPattern(Pattern):
+    """RoundRobinPattern implements a round robin with handoffs between agents."""
+
+    def _generate_handoffs(
+        self,
+        initial_agent: "ConversableAgent",
+        agents: list["ConversableAgent"],
+        user_agent: Optional["ConversableAgent"],
+    ) -> None:
+        """Generate handoffs between agents in a round-robin fashion."""
+        # Create a list of the agents and the user_agent but put the initial_agent first
+        agent_list = [initial_agent]
+
+        # Add the rest of the agents, excluding the initial_agent and user_agent
+        for agent in agents:
+            if agent != initial_agent and (user_agent is None or agent != user_agent):
+                agent_list.append(agent)
+
+        # Add the user_agent last if it exists
+        if user_agent is not None:
+            agent_list.append(user_agent)
+
+        # Create handoffs in a round-robin fashion
+        for i, agent in enumerate(agent_list):
+            # Last agent hands off to the first agent
+            # Otherwise agent hands off to the next one
+            handoff_target = agent_list[0] if i == len(agent_list) - 1 else agent_list[i + 1]
+
+            agent.handoffs.set_after_work(target=AgentTarget(agent=handoff_target))
+
+    def prepare_group_chat(
+        self,
+        max_rounds: int,
+        messages: Union[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.
+        """
+        # Use the parent class's implementation to prepare the agents and group chat
+        (
+            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,
+        ) = super().prepare_group_chat(
+            max_rounds=max_rounds,
+            messages=messages,
+        )
+
+        # Create the handoffs between agents
+        self._generate_handoffs(initial_agent=initial_agent, agents=agents, user_agent=user_agent)
+
+        # 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,
+        )

autogen/agentchat/group/reply_result.py

@@ -0,0 +1,26 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+__all__ = ["ReplyResult"]
+
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+from .context_variables import ContextVariables
+from .targets.transition_target import TransitionTarget
+
+
+class ReplyResult(BaseModel):
+    """Result of a tool call that is used to provide the return message and the target to transition to."""
+
+    message: str
+    target: Optional[TransitionTarget] = None
+    context_variables: Optional[ContextVariables] = None
+
+    def __str__(self) -> str:
+        """The string representation for ReplyResult will be just the message."""
+        return self.message

autogen/agentchat/group/speaker_selection_result.py

@@ -0,0 +1,41 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import TYPE_CHECKING, Optional, Union
+
+from pydantic import BaseModel
+
+from ..agent import Agent
+
+if TYPE_CHECKING:
+    # Avoid circular import
+    from ..groupchat import GroupChat
+
+
+class SpeakerSelectionResult(BaseModel):
+    """Represents a speaker selection result that will be returned to GroupChat._prepare_and_select_agents to determine the next speaker.
+
+    This class can return an Agent, a None to end the conversation, or a string for a speaker selection method.
+    """
+
+    terminate: Optional[bool] = None
+    agent_name: Optional[str] = None
+    speaker_selection_method: Optional[str] = None
+
+    def get_speaker_selection_result(self, groupchat: "GroupChat") -> Optional[Union[Agent, str]]:
+        """Get the speaker selection result. If None, the conversation will end."""
+        if self.agent_name is not None:
+            # Find the agent by name in the groupchat
+            for agent in groupchat.agents:
+                if agent.name == self.agent_name:
+                    return agent
+            raise ValueError(f"Agent '{self.agent_name}' not found in groupchat.")
+        elif self.speaker_selection_method is not None:
+            return self.speaker_selection_method
+        elif self.terminate is not None and self.terminate:
+            return None
+        else:
+            raise ValueError(
+                "Unable to establish speaker selection result. No terminate, agent, or speaker selection method provided."
+            )

autogen/agentchat/group/targets/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+#

autogen/agentchat/group/targets/group_chat_target.py

@@ -0,0 +1,132 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import TYPE_CHECKING, Any, Optional, Union
+
+from pydantic import BaseModel
+
+from ....doc_utils import export_module
+from ...agent import Agent
+from ..speaker_selection_result import SpeakerSelectionResult
+from .transition_target import AgentTarget, TransitionTarget
+from .transition_utils import __AGENT_WRAPPER_PREFIX__
+
+if TYPE_CHECKING:
+    from ...conversable_agent import ConversableAgent
+    from ...groupchat import GroupChat
+    from ..patterns.pattern import Pattern
+
+
+__all__ = ["GroupChatConfig", "GroupChatTarget"]
+
+
+@export_module("autogen.agentchat.group")
+class GroupChatConfig(BaseModel):
+    """Configuration for a group chat transition target.
+
+    Note: If context_variables are not passed in, the outer context variables will be passed in"""
+
+    pattern: "Pattern"
+    messages: Union[list[dict[str, Any]], str]
+    max_rounds: int = 20
+
+
+@export_module("autogen.agentchat.group")
+class GroupChatTarget(TransitionTarget):
+    """Target that represents a group chat."""
+
+    group_chat_config: GroupChatConfig
+
+    def can_resolve_for_speaker_selection(self) -> bool:
+        """Check if the target can resolve for speaker selection. For GroupChatTarget the chat must be encapsulated into an agent."""
+        return False
+
+    def resolve(
+        self,
+        groupchat: "GroupChat",
+        current_agent: "ConversableAgent",
+        user_agent: Optional["ConversableAgent"],
+    ) -> SpeakerSelectionResult:
+        """Resolve to the nested chat configuration."""
+        raise NotImplementedError(
+            "GroupChatTarget does not support the resolve method. An agent should be used to encapsulate this nested chat and then the target changed to an AgentTarget."
+        )
+
+    def display_name(self) -> str:
+        """Get the display name for the target."""
+        return "a group chat"
+
+    def normalized_name(self) -> str:
+        """Get a normalized name for the target that has no spaces, used for function calling."""
+        return "group_chat"
+
+    def __str__(self) -> str:
+        """String representation for AgentTarget, can be shown as a function call message."""
+        return "Transfer to group chat"
+
+    def needs_agent_wrapper(self) -> bool:
+        """Check if the target needs to be wrapped in an agent. GroupChatTarget must be wrapped in an agent."""
+        return True
+
+    def create_wrapper_agent(self, parent_agent: "ConversableAgent", index: int) -> "ConversableAgent":
+        """Create a wrapper agent for the group chat."""
+        from autogen.agentchat import initiate_group_chat
+
+        from ...conversable_agent import ConversableAgent  # to avoid circular import
+
+        # Create the wrapper agent with a name that identifies it as a wrapped group chat
+        group_chat_agent = ConversableAgent(
+            name=f"{__AGENT_WRAPPER_PREFIX__}group_{parent_agent.name}_{index + 1}",
+            # Copy LLM config from parent agent to ensure it can generate replies if needed
+            llm_config=parent_agent.llm_config,
+        )
+
+        # Store the config directly on the agent
+        group_chat_agent._group_chat_config = self.group_chat_config  # type: ignore[attr-defined]
+
+        # Define the reply function that will run the group chat
+        def group_chat_reply(
+            agent: "ConversableAgent",
+            messages: Optional[list[dict[str, Any]]] = None,
+            sender: Optional["Agent"] = None,
+            config: Optional[Any] = None,
+        ) -> tuple[bool, Optional[dict[str, Any]]]:
+            """Run the inner group chat and return its results as a reply."""
+            # Get the configuration stored directly on the agent
+            group_config = agent._group_chat_config  # type: ignore[attr-defined]
+
+            # Pull through the second last message from the outer chat (the last message will be the handoff message)
+            # This may need work to make sure we get the right message(s) from the outer chat
+            message = (
+                messages[-2]["content"]
+                if messages and len(messages) >= 2 and "content" in messages[-2]
+                else "No message to pass through."
+            )
+
+            try:
+                # Run the group chat with direct agent references from the config
+                result, _, _ = initiate_group_chat(
+                    pattern=group_config.pattern,
+                    messages=message,
+                    max_rounds=group_config.max_rounds,
+                )
+
+                # Return the summary from the chat result summary
+                return True, {"content": result.summary}
+
+            except Exception as e:
+                # Handle any errors during execution
+                return True, {"content": f"Error running group chat: {str(e)}"}
+
+        # Register the reply function with the wrapper agent
+        group_chat_agent.register_reply(
+            trigger=[ConversableAgent, None],
+            reply_func=group_chat_reply,
+            remove_other_reply_funcs=True,  # Use only this reply function
+        )
+
+        # After the group chat completes, transition back to the parent agent
+        group_chat_agent.handoffs.set_after_work(AgentTarget(parent_agent))
+
+        return group_chat_agent

autogen/agentchat/group/targets/group_manager_target.py

@@ -0,0 +1,151 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import TYPE_CHECKING, Any, Optional, Type, Union
+
+from pydantic import BaseModel, field_validator
+
+from ....doc_utils import export_module
+from ..context_str import ContextStr
+from ..group_tool_executor import GroupToolExecutor
+from ..speaker_selection_result import SpeakerSelectionResult
+from .transition_target import TransitionTarget
+from .transition_utils import __AGENT_WRAPPER_PREFIX__
+
+if TYPE_CHECKING:
+    # Avoid circular import
+    from ...conversable_agent import ConversableAgent
+    from ...groupchat import GroupChat
+
+__all__ = ["GroupManagerTarget"]
+
+
+def prepare_groupchat_auto_speaker(
+    groupchat: "GroupChat",
+    last_group_agent: "ConversableAgent",
+    group_chat_manager_selection_msg: Optional[Any],
+) -> None:
+    """Prepare the group chat for auto speaker selection, includes updating or restore the groupchat speaker selection message.
+
+    Tool Executor and wrapped agents will be removed from the available agents list.
+
+    Args:
+        groupchat (GroupChat): GroupChat instance.
+        last_group_agent ("ConversableAgent"): The last group agent for which the LLM config is used
+        group_chat_manager_selection_msg (GroupManagerSelectionMessage): Optional message to use for the agent selection (in internal group chat).
+    """
+    from ...groupchat import SELECT_SPEAKER_PROMPT_TEMPLATE
+
+    def substitute_agentlist(template: str) -> str:
+        # Run through group chat's string substitution first for {agentlist}
+        # We need to do this so that the next substitution doesn't fail with agentlist
+        # and we can remove the tool executor and wrapped chats from the available agents list
+        agent_list = [
+            agent
+            for agent in groupchat.agents
+            if not isinstance(agent, GroupToolExecutor) and not agent.name.startswith(__AGENT_WRAPPER_PREFIX__)
+        ]
+
+        groupchat.select_speaker_prompt_template = template
+        return groupchat.select_speaker_prompt(agent_list)
+
+    # Use the default speaker selection prompt if one is not specified, otherwise use the specified one
+    groupchat.select_speaker_prompt_template = substitute_agentlist(
+        SELECT_SPEAKER_PROMPT_TEMPLATE
+        if group_chat_manager_selection_msg is None
+        else group_chat_manager_selection_msg.get_message(last_group_agent)
+    )
+
+
+# GroupManagerSelectionMessage protocol and implementations
+@export_module("autogen.agentchat.group")
+class GroupManagerSelectionMessage(BaseModel):
+    """Base class for all GroupManager selection message types."""
+
+    def get_message(self, agent: "ConversableAgent") -> str:
+        """Get the formatted message."""
+        raise NotImplementedError("Requires subclasses to implement.")
+
+
+@export_module("autogen.agentchat.group")
+class GroupManagerSelectionMessageString(GroupManagerSelectionMessage):
+    """Selection message that uses a plain string template."""
+
+    message: str
+
+    def get_message(self, agent: "ConversableAgent") -> str:
+        """Get the message string."""
+        return self.message
+
+
+@export_module("autogen.agentchat.group")
+class GroupManagerSelectionMessageContextStr(GroupManagerSelectionMessage):
+    """Selection message that uses a ContextStr template."""
+
+    context_str_template: str
+
+    # We will replace {agentlist} with another term and return it later for use with the internal group chat auto speaker selection
+    # Otherwise our format will fail
+    @field_validator("context_str_template", mode="before")
+    def _replace_agentlist_placeholder(cls: Type["GroupManagerSelectionMessageContextStr"], v: Any) -> Union[str, Any]:  # noqa: N805
+        """Replace {agentlist} placeholder before validation/assignment."""
+        if isinstance(v, str):
+            if "{agentlist}" in v:
+                return v.replace("{agentlist}", "<<agent_list>>")  # Perform the replacement
+            else:
+                return v  # If no replacement is needed, return the original value
+        return ""
+
+    def get_message(self, agent: "ConversableAgent") -> str:
+        """Get the formatted message with context variables substituted."""
+        context_str = ContextStr(template=self.context_str_template)
+        format_result = context_str.format(agent.context_variables)
+        if format_result is None:
+            return ""
+
+        return format_result.replace(
+            "<<agent_list>>", "{agentlist}"
+        )  # Restore agentlist so it can be substituted by the internal group chat auto speaker selection
+
+
+class GroupManagerTarget(TransitionTarget):
+    """Target that represents an agent by name."""
+
+    selection_message: Optional[GroupManagerSelectionMessage] = None
+
+    def can_resolve_for_speaker_selection(self) -> bool:
+        """Check if the target can resolve for speaker selection."""
+        return True
+
+    def resolve(
+        self,
+        groupchat: "GroupChat",
+        current_agent: "ConversableAgent",
+        user_agent: Optional["ConversableAgent"],
+    ) -> SpeakerSelectionResult:
+        """Resolve to the speaker selection for the group."""
+        if self.selection_message is not None:
+            prepare_groupchat_auto_speaker(groupchat, current_agent, self.selection_message)
+
+        return SpeakerSelectionResult(speaker_selection_method="auto")
+
+    def display_name(self) -> str:
+        """Get the display name for the target."""
+        return "the group manager"
+
+    def normalized_name(self) -> str:
+        """Get a normalized name for the target that has no spaces, used for function calling"""
+        return self.display_name()
+
+    def __str__(self) -> str:
+        """String representation for AgentTarget, can be shown as a function call message."""
+        return "Transfer to the group manager"
+
+    def needs_agent_wrapper(self) -> bool:
+        """Check if the target needs to be wrapped in an agent."""
+        return False
+
+    def create_wrapper_agent(self, parent_agent: "ConversableAgent", index: int) -> "ConversableAgent":
+        """Create a wrapper agent for the target if needed."""
+        raise NotImplementedError("GroupManagerTarget does not require wrapping in an agent.")