ag2 0.10.2__py3-none-any.whl

autogen/agentchat/group/targets/function_target.py

@@ -0,0 +1,245 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Field
+
+from ...agent import Agent
+from ..context_variables import ContextVariables
+from ..speaker_selection_result import SpeakerSelectionResult
+from .transition_target import AgentNameTarget, AgentTarget, RevertToUserTarget, StayTarget, TransitionTarget
+
+if TYPE_CHECKING:
+    from ...conversable_agent import ConversableAgent
+    from ...groupchat import GroupChat
+
+__all__ = ["FunctionTarget", "FunctionTargetMessage", "FunctionTargetResult", "broadcast"]
+
+
+class FunctionTargetMessage(BaseModel):
+    """Message and target that can be sent as part of the FunctionTargetResult.
+
+    Attributes:
+        content: The content of the message to be sent.
+        msg_target: The agent to whom the message is to be sent.
+    """
+
+    content: str
+    msg_target: Agent
+
+    class Config:
+        arbitrary_types_allowed = True
+
+
+class FunctionTargetResult(BaseModel):
+    """Result of a function handoff that is used to provide the return message and the target to transition to.
+
+    Attributes:
+        messages: Optional list of messages to be broadcast to specific agents, or a single string message.
+        context_variables: Optional updated context variables that will be applied to the group chat context variables.
+        target: The next target to transition to.
+    """
+
+    messages: list[FunctionTargetMessage] | str | None = None
+    context_variables: ContextVariables | None = None
+    target: TransitionTarget
+
+
+def construct_broadcast_messages_list(
+    messages: list[FunctionTargetMessage] | str,
+    group_chat: GroupChat,
+    current_agent: ConversableAgent,
+    target: TransitionTarget,
+    user_agent: ConversableAgent | None = None,
+) -> list[FunctionTargetMessage]:
+    """Construct a list of FunctionTargetMessage from input messages and target."""
+    if isinstance(messages, str):
+        if isinstance(target, (AgentTarget, AgentNameTarget)):
+            next_target = target.agent_name
+            for agent in group_chat.agents:
+                if agent.name == next_target:
+                    messages_list = [FunctionTargetMessage(content=messages, msg_target=agent)]
+                    break
+            else:
+                raise ValueError(f"No agent found with in the group chat matching the target agent name {next_target}.")
+        elif isinstance(target, RevertToUserTarget) and user_agent is not None:
+            messages_list = [FunctionTargetMessage(content=messages, msg_target=user_agent)]
+        elif isinstance(target, StayTarget):
+            messages_list = [FunctionTargetMessage(content=messages, msg_target=current_agent)]
+        else:
+            # Default to current agent if no target is not agent-based is found
+            messages_list = [FunctionTargetMessage(content=messages, msg_target=current_agent)]
+    else:
+        messages_list = messages
+    return messages_list
+
+
+def broadcast(
+    messages: list[FunctionTargetMessage] | str,
+    group_chat: GroupChat,
+    current_agent: ConversableAgent,
+    fn_name: str,
+    target: TransitionTarget,
+    user_agent: ConversableAgent | None = None,
+) -> None:
+    """Broadcast message(s) to their target agent."""
+    messages_list = construct_broadcast_messages_list(messages, group_chat, current_agent, target, user_agent)
+
+    for message in messages_list:
+        content = message.content
+        broadcast = {
+            "role": "system",
+            "name": f"{fn_name}",
+            "content": f"[FUNCTION_HANDOFF] - Reply from function {fn_name}: \n\n {content}",
+        }
+        if hasattr(current_agent, "_group_manager") and current_agent._group_manager is not None:
+            current_agent._group_manager.send(
+                broadcast,
+                message.msg_target,
+                request_reply=False,
+                silent=False,
+            )
+        else:
+            raise ValueError("Current agent must have a group manager to broadcast messages.")
+
+
+def validate_fn_sig(
+    incoming_fn: Callable[..., FunctionTargetResult],
+    extra_args: dict[str, Any],
+) -> None:
+    """
+    Validate a user-defined afterwork_function signature.
+
+    Rules:
+    1. Must have at least two positional parameters (whatever their names).
+    2. All provided extra_args must exist in the function signature (unless **kwargs is present).
+    3. All additional required (non-default) params beyond the first two must be satisfied via extra_args.
+    """
+    sig = inspect.signature(incoming_fn)
+    params = list(sig.parameters.values())
+
+    # 1️⃣ Must have at least two positional parameters (whatever names)
+    if len(params) < 2:
+        raise ValueError(
+            f"Function '{incoming_fn.__name__}' must accept at least two positional parameters: "
+            f"(output, ctx). Current: {[p.name for p in params]}"
+        )
+
+    # 2️⃣ Detect **kwargs
+    has_kwargs = any(p.kind == inspect.Parameter.VAR_KEYWORD for p in params)
+
+    # Build list of extra (non-core) params after the first two
+    extra_params = [
+        p for p in params[2:] if p.kind not in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD)
+    ]
+
+    # 3️⃣ If **kwargs not present, check for invalid extra_args
+    if not has_kwargs:
+        valid_names = {p.name for p in params}
+        invalid_keys = [k for k in extra_args if k not in valid_names]
+        if invalid_keys:
+            raise ValueError(
+                f"Invalid extra_args for function '{incoming_fn.__name__}': {invalid_keys}. "
+                f"Allowed parameters are: {[p.name for p in params]}."
+            )
+
+    # 4️⃣ Check for missing required params (no defaults) among the extra ones
+    missing_keys = [p.name for p in extra_params if p.default is p.empty and p.name not in extra_args]
+
+    if missing_keys:
+        raise ValueError(
+            f"Missing required extra_args for function '{incoming_fn.__name__}': {missing_keys}. "
+            f"You must supply them via `extra_args`."
+        )
+
+
+class FunctionTarget(TransitionTarget):
+    """Transition target that invokes a tool function with (prev_output, context).
+
+    The function must return a FunctionTargetResult object that includes the next target to transition to.
+    """
+
+    fn_name: str = Field(...)
+    fn: Callable[..., FunctionTargetResult] = Field(..., repr=False)
+    extra_args: dict[str, Any] = Field(default_factory=dict)
+
+    def __init__(
+        self,
+        incoming_fn: Callable[..., FunctionTargetResult],
+        *,
+        extra_args: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if callable(incoming_fn):
+            extra_args = extra_args or {}
+
+            validate_fn_sig(incoming_fn, extra_args)
+
+            super().__init__(fn_name=incoming_fn.__name__, fn=incoming_fn, extra_args=extra_args, **kwargs)
+        else:
+            raise ValueError(
+                "FunctionTarget must be initialized with a callable function as the first argument or 'fn' keyword argument."
+            )
+
+    def can_resolve_for_speaker_selection(self) -> bool:
+        return False
+
+    def resolve(
+        self,
+        groupchat: GroupChat,
+        current_agent: ConversableAgent,
+        user_agent: ConversableAgent | None,
+    ) -> SpeakerSelectionResult:
+        """Invoke the function, update context variables (optional), broadcast messages (optional), and return the next target to transition to."""
+        last_message = (
+            groupchat.messages[-1]["content"] if groupchat.messages and "content" in groupchat.messages[-1] else ""
+        )
+
+        # Run the function to get the FunctionTargetResult
+        function_target_result = self.fn(
+            last_message,
+            current_agent.context_variables,
+            **self.extra_args,
+        )
+
+        if not isinstance(function_target_result, FunctionTargetResult):
+            raise ValueError("FunctionTarget function must return a FunctionTargetResult object.")
+
+        if function_target_result.context_variables:
+            # Update the group's Context Variables if the function returned any
+            current_agent.context_variables.update(function_target_result.context_variables.to_dict())
+
+        if function_target_result.messages:
+            # If we have messages, we need to broadcast them to the appropriate agent based on the target
+            broadcast(
+                function_target_result.messages,
+                groupchat,
+                current_agent,
+                self.fn_name,
+                function_target_result.target,
+                user_agent,
+            )
+
+        # Resolve and return the next target
+        return function_target_result.target.resolve(groupchat, current_agent, user_agent)
+
+    def display_name(self) -> str:
+        return self.fn_name
+
+    def normalized_name(self) -> str:
+        return self.fn_name.replace(" ", "_")
+
+    def __str__(self) -> str:
+        return f"Transfer to tool {self.fn_name}"
+
+    def needs_agent_wrapper(self) -> bool:
+        return False
+
+    def create_wrapper_agent(self, parent_agent: ConversableAgent, index: int) -> ConversableAgent:
+        raise NotImplementedError("FunctionTarget is executed inline and needs no wrapper")

autogen/agentchat/group/targets/group_chat_target.py

@@ -0,0 +1,133 @@
+# 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
+
+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: 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: list[dict[str, Any]] | None = None,
+            sender: Optional["Agent"] = None,
+            config: Any | None = None,
+        ) -> tuple[bool, dict[str, Any] | None]:
+            """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
+
+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: Any | None,
+) -> 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) -> 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: GroupManagerSelectionMessage | None = 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.")