chore: import upstream snapshot with attribution

python/semantic_kernel/agents/strategies/selection/kernel_function_selection_strategy.py

@@ -0,0 +1,116 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+import sys
+
+if sys.version_info >= (3, 12):
+    from typing import override  # pragma: no cover
+else:
+    from typing_extensions import override  # pragma: no cover
+
+from collections.abc import Callable
+from inspect import isawaitable
+from typing import TYPE_CHECKING, ClassVar
+
+from pydantic import Field
+
+from semantic_kernel.agents.strategies.selection.selection_strategy import SelectionStrategy
+from semantic_kernel.contents.chat_message_content import ChatMessageContent
+from semantic_kernel.contents.history_reducer.chat_history_reducer import ChatHistoryReducer
+from semantic_kernel.exceptions.agent_exceptions import AgentExecutionException
+from semantic_kernel.functions.kernel_arguments import KernelArguments
+from semantic_kernel.functions.kernel_function import KernelFunction
+from semantic_kernel.kernel import Kernel
+from semantic_kernel.utils.feature_stage_decorator import experimental
+
+if TYPE_CHECKING:
+    from semantic_kernel.agents import Agent
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+@experimental
+class KernelFunctionSelectionStrategy(SelectionStrategy):
+    """Determines agent selection based on the evaluation of a Kernel Function."""
+
+    DEFAULT_AGENT_VARIABLE_NAME: ClassVar[str] = "_agent_"
+    DEFAULT_HISTORY_VARIABLE_NAME: ClassVar[str] = "_history_"
+
+    agent_variable_name: str | None = Field(default=DEFAULT_AGENT_VARIABLE_NAME)
+    history_variable_name: str | None = Field(default=DEFAULT_HISTORY_VARIABLE_NAME)
+    arguments: KernelArguments | None = None
+    function: KernelFunction
+    kernel: Kernel
+    result_parser: Callable[..., str] = Field(default_factory=lambda: (lambda: ""))
+    history_reducer: ChatHistoryReducer | None = None
+
+    @override
+    async def select_agent(self, agents: list["Agent"], history: list[ChatMessageContent]) -> "Agent":
+        """Select the next agent to interact with.
+
+        Args:
+            agents: The list of agents to select from.
+            history: The history of messages in the conversation.
+
+        Returns:
+            The next agent to interact with.
+
+        Raises:
+            AgentExecutionException: If the strategy fails to execute the function or select the next agent
+        """
+        if self.history_reducer is not None:
+            self.history_reducer.messages = history
+            reduced_history = await self.history_reducer.reduce()
+            if reduced_history is not None:
+                history = reduced_history.messages
+
+        original_arguments = self.arguments or KernelArguments()
+        execution_settings = original_arguments.execution_settings or {}
+
+        messages = [message.to_dict(role_key="role", content_key="content") for message in history]
+
+        filtered_arguments = {
+            self.agent_variable_name: ",".join(agent.name for agent in agents),
+            self.history_variable_name: messages,
+        }
+
+        extracted_settings = {key: setting.model_dump() for key, setting in execution_settings.items()}
+
+        combined_arguments = {
+            **original_arguments,
+            **extracted_settings,
+            **{k: v for k, v in filtered_arguments.items()},
+        }
+
+        arguments = KernelArguments(
+            **combined_arguments,
+        )
+
+        logger.info(
+            f"Kernel Function Selection Strategy next method called, "
+            f"invoking function: {self.function.plugin_name}, {self.function.name}",
+        )
+
+        try:
+            result = await self.function.invoke(kernel=self.kernel, arguments=arguments)
+        except Exception as ex:
+            logger.error("Kernel Function Selection Strategy next method failed", exc_info=ex)
+            raise AgentExecutionException("Agent Failure - Strategy failed to execute function.") from ex
+
+        logger.info(
+            f"Kernel Function Selection Strategy next method completed: "
+            f"{self.function.plugin_name}, {self.function.name}, result: {result.value if result else None}",
+        )
+
+        agent_name = self.result_parser(result)
+        if isawaitable(agent_name):
+            agent_name = await agent_name
+
+        if agent_name is None:
+            raise AgentExecutionException("Agent Failure - Strategy unable to determine next agent.")
+
+        agent_turn = next((agent for agent in agents if agent.name == agent_name), None)
+        if agent_turn is None:
+            raise AgentExecutionException(f"Agent Failure - Strategy unable to select next agent: {agent_name}")
+
+        return agent_turn

python/semantic_kernel/agents/strategies/selection/selection_strategy.py

@@ -0,0 +1,57 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from abc import ABC
+from typing import TYPE_CHECKING
+
+from semantic_kernel.agents import Agent
+from semantic_kernel.exceptions.agent_exceptions import AgentExecutionException
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+from semantic_kernel.utils.feature_stage_decorator import experimental
+
+if TYPE_CHECKING:
+    from semantic_kernel.contents.chat_message_content import ChatMessageContent
+
+
+@experimental
+class SelectionStrategy(KernelBaseModel, ABC):
+    """Base strategy class for selecting the next agent in a chat."""
+
+    has_selected: bool = False
+    initial_agent: Agent | None = None
+
+    async def next(
+        self,
+        agents: list[Agent],
+        history: list["ChatMessageContent"],
+    ) -> Agent:
+        """Select the next agent to interact with.
+
+        Args:
+            agents: The list of agents to select from.
+            history: The history of messages in the conversation.
+
+        Returns:
+            The agent who takes the next turn.
+        """
+        if not agents and self.initial_agent is None:
+            raise AgentExecutionException("Agent Failure - No agents present to select.")
+
+        # If it's the first selection and we have an initial agent, use it
+        if not self.has_selected and self.initial_agent is not None:
+            agent = self.initial_agent
+        else:
+            agent = await self.select_agent(agents, history)
+
+        self.has_selected = True
+        return agent
+
+    async def select_agent(
+        self,
+        agents: list[Agent],
+        history: list["ChatMessageContent"],
+    ) -> Agent:
+        """Determines which agent goes next. Override for custom logic.
+
+        By default, this fallback returns the first agent in the list.
+        """
+        return agents[0]

python/semantic_kernel/agents/strategies/selection/sequential_selection_strategy.py

@@ -0,0 +1,80 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+import sys
+
+if sys.version_info >= (3, 12):
+    from typing import override  # pragma: no cover
+else:
+    from typing_extensions import override  # pragma: no cover
+
+from typing import TYPE_CHECKING
+
+from pydantic import PrivateAttr
+
+from semantic_kernel.agents.strategies.selection.selection_strategy import SelectionStrategy
+from semantic_kernel.utils.feature_stage_decorator import experimental
+
+if TYPE_CHECKING:
+    from semantic_kernel.agents import Agent
+    from semantic_kernel.contents.chat_message_content import ChatMessageContent
+
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+@experimental
+class SequentialSelectionStrategy(SelectionStrategy):
+    """Round-robin turn-taking strategy. Agent order is based on the order in which they joined."""
+
+    _index: int = PrivateAttr(default=-1)
+
+    def reset(self) -> None:
+        """Reset selection to the initial/first agent."""
+        self._index = -1
+
+    def _increment_index(self, agent_count: int) -> None:
+        """Increment the index in a circular manner."""
+        self._index = (self._index + 1) % agent_count
+
+    @override
+    async def select_agent(
+        self,
+        agents: list["Agent"],
+        history: list["ChatMessageContent"],
+    ) -> "Agent":
+        """Select the next agent in a round-robin fashion.
+
+        Args:
+            agents: The list of agents to select from.
+            history: The history of messages in the conversation.
+
+        Returns:
+            The agent who takes the next turn.
+        """
+        if self._index >= len(agents):
+            self._index = -1
+
+        if (
+            self.has_selected
+            and self.initial_agent is not None
+            and len(agents) > 0
+            and agents[0] == self.initial_agent
+            and self._index < 0
+        ):
+            # Avoid selecting the same agent twice in a row
+            self._increment_index(len(agents))
+
+        # Main index increment
+        self._increment_index(len(agents))
+
+        # Pick the agent
+        agent = agents[self._index]
+
+        logger.info(
+            "Selected agent at index %d (ID: %s, name: %s)",
+            self._index,
+            agent.id,
+            agent.name,
+        )
+        return agent