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

autogen/agentchat/group/handoffs.py

@@ -0,0 +1,244 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Optional, Union, overload
+
+from pydantic import BaseModel, Field
+
+from .on_condition import OnCondition
+from .on_context_condition import OnContextCondition
+from .targets.transition_target import TransitionTarget
+
+__all__ = ["Handoffs"]
+
+
+class Handoffs(BaseModel):
+    """
+    Container for all handoff transition conditions of a ConversableAgent.
+
+    Three types of conditions can be added, each with a different order and time of use:
+    1. OnContextConditions (evaluated without an LLM)
+    2. OnConditions (evaluated with an LLM)
+    3. After work TransitionTarget (if no other transition is triggered)
+
+    Supports method chaining:
+    agent.handoffs.add_context_conditions([condition1]) \
+                   .add_llm_condition(condition2) \
+                   .set_after_work(after_work)
+    """
+
+    context_conditions: list[OnContextCondition] = Field(default_factory=list)
+    llm_conditions: list[OnCondition] = Field(default_factory=list)
+    after_work: Optional[TransitionTarget] = None
+
+    def add_context_condition(self, condition: OnContextCondition) -> "Handoffs":
+        """
+        Add a single context condition.
+
+        Args:
+            condition: The OnContextCondition to add
+
+        Returns:
+            Self for method chaining
+        """
+        # Validate that it is an OnContextCondition
+        if not isinstance(condition, OnContextCondition):
+            raise TypeError(f"Expected an OnContextCondition instance, got {type(condition).__name__}")
+
+        self.context_conditions.append(condition)
+        return self
+
+    def add_context_conditions(self, conditions: list[OnContextCondition]) -> "Handoffs":
+        """
+        Add multiple context conditions.
+
+        Args:
+            conditions: List of OnContextConditions to add
+
+        Returns:
+            Self for method chaining
+        """
+        # Validate that it is a list of OnContextConditions
+        if not all(isinstance(condition, OnContextCondition) for condition in conditions):
+            raise TypeError("All conditions must be of type OnContextCondition")
+
+        self.context_conditions.extend(conditions)
+        return self
+
+    def add_llm_condition(self, condition: OnCondition) -> "Handoffs":
+        """
+        Add a single LLM condition.
+
+        Args:
+            condition: The OnCondition to add
+
+        Returns:
+            Self for method chaining
+        """
+        # Validate that it is an OnCondition
+        if not isinstance(condition, OnCondition):
+            raise TypeError(f"Expected an OnCondition instance, got {type(condition).__name__}")
+
+        self.llm_conditions.append(condition)
+        return self
+
+    def add_llm_conditions(self, conditions: list[OnCondition]) -> "Handoffs":
+        """
+        Add multiple LLM conditions.
+
+        Args:
+            conditions: List of OnConditions to add
+
+        Returns:
+            Self for method chaining
+        """
+        # Validate that it is a list of OnConditions
+        if not all(isinstance(condition, OnCondition) for condition in conditions):
+            raise TypeError("All conditions must be of type OnCondition")
+
+        self.llm_conditions.extend(conditions)
+        return self
+
+    def set_after_work(self, target: TransitionTarget) -> "Handoffs":
+        """
+        Set the after work target (only one allowed).
+
+        Args:
+            target: The after work TransitionTarget to set
+
+        Returns:
+            Self for method chaining
+        """
+        if not isinstance(target, TransitionTarget):
+            raise TypeError(f"Expected a TransitionTarget instance, got {type(target).__name__}")
+
+        self.after_work = target
+        return self
+
+    @overload
+    def add(self, condition: OnContextCondition) -> "Handoffs": ...
+
+    @overload
+    def add(self, condition: OnCondition) -> "Handoffs": ...
+
+    def add(self, condition: Union[OnContextCondition, OnCondition]) -> "Handoffs":
+        """
+        Add a single condition (OnContextCondition or OnCondition).
+
+        Args:
+            condition: The condition to add (OnContextCondition or OnCondition)
+
+        Raises:
+            TypeError: If the condition type is not supported
+
+        Returns:
+            Self for method chaining
+        """
+        # This add method is a helper method designed to make it easier for
+        # adding handoffs without worrying about the specific type.
+        if isinstance(condition, OnContextCondition):
+            return self.add_context_condition(condition)
+        elif isinstance(condition, OnCondition):
+            return self.add_llm_condition(condition)
+        else:
+            raise TypeError(f"Unsupported condition type: {type(condition).__name__}")
+
+    def add_many(self, conditions: list[Union[OnContextCondition, OnCondition]]) -> "Handoffs":
+        """
+        Add multiple conditions of any supported types (OnContextCondition and OnCondition).
+
+        Args:
+            conditions: List of conditions to add
+
+        Raises:
+            TypeError: If an unsupported condition type is provided
+
+        Returns:
+            Self for method chaining
+        """
+        # This add_many method is a helper method designed to make it easier for
+        # adding handoffs without worrying about the specific type.
+        context_conditions = []
+        llm_conditions = []
+
+        for condition in conditions:
+            if isinstance(condition, OnContextCondition):
+                context_conditions.append(condition)
+            elif isinstance(condition, OnCondition):
+                llm_conditions.append(condition)
+            else:
+                raise TypeError(f"Unsupported condition type: {type(condition).__name__}")
+
+        if context_conditions:
+            self.add_context_conditions(context_conditions)
+        if llm_conditions:
+            self.add_llm_conditions(llm_conditions)
+
+        return self
+
+    def clear(self) -> "Handoffs":
+        """
+        Clear all handoff conditions.
+
+        Returns:
+            Self for method chaining
+        """
+        self.context_conditions.clear()
+        self.llm_conditions.clear()
+        self.after_work = None
+        return self
+
+    def get_llm_conditions_by_target_type(self, target_type: type) -> list[OnCondition]:
+        """
+        Get OnConditions for a specific target type.
+
+        Args:
+            target_type: The type of condition to retrieve
+
+        Returns:
+            List of conditions of the specified type, or None if none exist
+        """
+        return [on_condition for on_condition in self.llm_conditions if on_condition.has_target_type(target_type)]
+
+    def get_context_conditions_by_target_type(self, target_type: type) -> list[OnContextCondition]:
+        """
+        Get OnContextConditions for a specific target type.
+
+        Args:
+            target_type: The type of condition to retrieve
+
+        Returns:
+            List of conditions of the specified type, or None if none exist
+        """
+        return [
+            on_context_condition
+            for on_context_condition in self.context_conditions
+            if on_context_condition.has_target_type(target_type)
+        ]
+
+    def get_llm_conditions_requiring_wrapping(self) -> list[OnCondition]:
+        """
+        Get LLM conditions that have targets that require wrapping.
+
+        Returns:
+            List of LLM conditions that require wrapping
+        """
+        return [condition for condition in self.llm_conditions if condition.target_requires_wrapping()]
+
+    def get_context_conditions_requiring_wrapping(self) -> list[OnContextCondition]:
+        """
+        Get context conditions that have targets that require wrapping.
+
+        Returns:
+            List of context conditions that require wrapping
+        """
+        return [condition for condition in self.context_conditions if condition.target_requires_wrapping()]
+
+    def set_llm_function_names(self) -> None:
+        """
+        Set the LLM function names for all LLM conditions, creating unique names for each function.
+        """
+        for i, condition in enumerate(self.llm_conditions):
+            # Function names are made unique and allow multiple OnCondition's to the same agent
+            condition.llm_function_name = f"transfer_to_{condition.target.normalized_name()}_{i + 1}"

autogen/agentchat/group/llm_condition.py

@@ -0,0 +1,93 @@
+# 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
+
+from pydantic import BaseModel
+
+from .context_str import ContextStr
+
+if TYPE_CHECKING:
+    # Avoid circular import
+    from ..conversable_agent import ConversableAgent
+
+__all__ = ["ContextStrLLMCondition", "LLMCondition", "StringLLMCondition"]
+
+
+class LLMCondition(BaseModel):
+    """Protocol for conditions evaluated by an LLM."""
+
+    def get_prompt(self, agent: "ConversableAgent", messages: list[dict[str, Any]]) -> str:
+        """Get the prompt text for LLM evaluation.
+
+        Args:
+            agent: The agent evaluating the condition
+            messages: The conversation history
+
+        Returns:
+            The prompt text to be evaluated by the LLM
+        """
+        raise NotImplementedError("Requires subclasses to implement.")
+
+
+class StringLLMCondition(LLMCondition):
+    """Simple string-based LLM condition.
+
+    This condition provides a static string prompt to be evaluated by an LLM.
+    """
+
+    prompt: str
+
+    def __init__(self, prompt: str, **data: Any) -> None:
+        """Initialize with a prompt string as a positional parameter.
+
+        Args:
+            prompt: The static prompt string to evaluate
+            data: Additional data for the parent class
+        """
+        super().__init__(prompt=prompt, **data)
+
+    def get_prompt(self, agent: "ConversableAgent", messages: list[dict[str, Any]]) -> str:
+        """Return the static prompt string.
+
+        Args:
+            agent: The agent evaluating the condition (not used)
+            messages: The conversation history (not used)
+
+        Returns:
+            The static prompt string
+        """
+        return self.prompt
+
+
+class ContextStrLLMCondition(LLMCondition):
+    """Context variable-based LLM condition.
+
+    This condition uses a ContextStr object with context variable placeholders that
+    will be substituted before being evaluated by an LLM.
+    """
+
+    context_str: ContextStr
+
+    def __init__(self, context_str: ContextStr, **data: Any) -> None:
+        """Initialize with a context string as a positional parameter.
+
+        Args:
+            context_str: The ContextStr object with variable placeholders
+            data: Additional data for the parent class
+        """
+        super().__init__(context_str=context_str, **data)
+
+    def get_prompt(self, agent: "ConversableAgent", messages: list[dict[str, Any]]) -> str:
+        """Return the prompt with context variables substituted.
+
+        Args:
+            agent: The agent evaluating the condition (provides context variables)
+            messages: The conversation history (not used)
+
+        Returns:
+            The prompt with context variables substituted
+        """
+        result = self.context_str.format(agent.context_variables)
+        return result if result is not None else ""

autogen/agentchat/group/multi_agent_chat.py

@@ -0,0 +1,237 @@
+# 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, Union
+
+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 ..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: Union[list[dict[str, Any]], str],
+    max_rounds: int = 20,
+) -> 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.
+
+    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,
+    )
+
+    # 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: Union[list[dict[str, Any]], str],
+    max_rounds: int = 20,
+) -> 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.
+
+    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,
+    )
+
+    # 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: Union[list[dict[str, Any]], str],
+    max_rounds: int = 20,
+) -> RunResponseProtocol:
+    iostream = ThreadIOStream()
+    # todo: add agents
+    response = RunResponse(iostream, agents=[])
+
+    def _initiate_group_chat(
+        pattern: "Pattern" = pattern,
+        messages: Union[list[dict[str, Any]], str] = messages,
+        max_rounds: int = max_rounds,
+        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,
+                )
+
+                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: Union[list[dict[str, Any]], str],
+    max_rounds: int = 20,
+) -> AsyncRunResponseProtocol:
+    iostream = AsyncThreadIOStream()
+    # todo: add agents
+    response = AsyncRunResponse(iostream, agents=[])
+
+    async def _initiate_group_chat(
+        pattern: "Pattern" = pattern,
+        messages: Union[list[dict[str, Any]], str] = messages,
+        max_rounds: int = max_rounds,
+        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,
+                )
+
+                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]
+
+    asyncio.create_task(_initiate_group_chat())
+
+    return response

autogen/agentchat/group/on_condition.py

@@ -0,0 +1,58 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Optional
+
+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.
+
+    This is for LLM-based condition evaluation where these conditions are translated into tools and attached to the agent.
+
+    These are evaluated after the OnCondition conditions but before the after work condition.
+
+    Args:
+        target (TransitionTarget): The transition (essentially an agent) to hand off to.
+        condition (LLMCondition): The condition for transitioning to the target agent, evaluated by the LLM.
+        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.
+        llm_function_name (Optional[str]): The name of the LLM function to use for this condition.
+    """
+
+    target: TransitionTarget
+    condition: LLMCondition
+    available: Optional[AvailableCondition] = None
+    llm_function_name: Optional[str] = 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,54 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Optional
+
+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 (ContextCondition): The context variable based condition for transitioning to the target agent.
+        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
+    available: Optional[AvailableCondition] = 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()