ag2 0.9.9__py3-none-any.whl → 0.10.0__py3-none-any.whl

autogen/oai/openai_utils.py

@@ -7,7 +7,6 @@
 
 import importlib
 import importlib.metadata
-import inspect
 import json
 import logging
 import os
@@ -22,6 +21,10 @@ from typing import TYPE_CHECKING, Any, Union
 from dotenv import find_dotenv, load_dotenv
 from packaging.version import parse
 from pydantic_core import to_jsonable_python
+from typing_extensions import deprecated
+
+from ..llm_config.utils import config_list_from_json as latest_config_list_from_json
+from ..llm_config.utils import filter_config as latest_filter
 
 if TYPE_CHECKING:
     from openai import OpenAI
@@ -472,6 +475,11 @@ def config_list_gpt4_gpt35(
 
 
 @export_module("autogen")
+@deprecated(
+    "`autogen.filter_config(...)` is deprecated. "
+    'Please use the "autogen.LLMConfig.from_json(path="OAI_CONFIG_LIST").where(model="gpt-4o")" method instead. '
+    "Scheduled for removal in 0.11.0 version."
+)
 def filter_config(
     config_list: list[dict[str, Any]],
     filter_dict: dict[str, list[str | None] | set[str | None]] | None,
@@ -489,7 +497,9 @@ def filter_config(
 
         filter_dict (dict, optional): A dictionary specifying filter criteria where:
             - Keys are field names to check in each configuration dictionary
-            - Values are lists/sets of acceptable values for that field
+            - Values can be:
+                * a single string value (e.g., {"model": "gpt-4o"})
+                * a list or set of acceptable values for that field (e.g., {"model": ["gpt-4o", "gpt-4o-mini"]})
             - A configuration matches if ALL filter keys are satisfied AND for each key,
               the config's field value matches at least one acceptable value
             - If a filter value includes None, configurations missing that field will match
@@ -517,22 +527,27 @@ def filter_config(
             {"model": "gpt-4", "tags": ["premium", "latest"]},
         ]
 
-        # Example 1: Single criterion - matches any model in the list
+        # Example 1: Single criterion with single string
+        filter_dict = {"model": "gpt-4o"}
+        result = filter_config(configs, filter_dict)
+        # Returns: [{"model": "gpt-4o", "api_type": "openai"}] if present
+
+        # Example 2: Single criterion - matches any model in the list
         filter_dict = {"model": ["gpt-4", "gpt-4o"]}
         result = filter_config(configs, filter_dict)
         # Returns: [{"model": "gpt-4", "api_type": "openai"}, {"model": "gpt-4", "tags": ["premium", "latest"]}]
 
-        # Example 2: Multiple criteria - must satisfy ALL conditions
+        # Example 3: Multiple criteria - must satisfy ALL the conditions
         filter_dict = {"model": ["gpt-3.5-turbo"], "api_type": ["azure"]}
         result = filter_config(configs, filter_dict)
         # Returns: [{"model": "gpt-3.5-turbo", "api_type": "azure", "api_version": "2024-02-01"}]
 
-        # Example 3: Tag filtering with list intersection
+        # Example 4: Tag filtering with list intersection
         filter_dict = {"tags": ["premium"]}
         result = filter_config(configs, filter_dict)
         # Returns: [{"model": "gpt-4", "tags": ["premium", "latest"]}]
 
-        # Example 4: Exclude matching configurations
+        # Example 5: Exclude matching configurations
         filter_dict = {"api_type": ["openai"]}
         result = filter_config(configs, filter_dict, exclude=True)
         # Returns configs that do NOT have api_type="openai"
@@ -543,92 +558,22 @@ def filter_config(
           it is considered a non-match and is excluded from the result.
 
     """
-    if inspect.stack()[1].function != "where":
-        warnings.warn(
-            "filter_config is deprecated and will be removed in a future release. "
-            'Please use the "autogen.LLMConfig.from_json(path="OAI_CONFIG_LIST").where(model="gpt-4o")" method instead.',
-            DeprecationWarning,
-        )
-
-    if filter_dict:
-        return [
-            item
-            for item in config_list
-            if all(_satisfies_criteria(item.get(key), values) != exclude for key, values in filter_dict.items())
-        ]
-    return config_list
-
-
-def _satisfies_criteria(config_value: Any, criteria_values: Any) -> bool:
-    """Check if a configuration field value satisfies the filter criteria.
-
-    This helper function implements the matching logic between a single configuration
-    field value and the acceptable values specified in the filter criteria. It handles
-    both scalar and list-type configuration values with appropriate matching strategies.
-
-    Args:
-        config_value (Any): The value from a configuration dictionary field.
-                           Can be None, a scalar value, or a list of values.
-        criteria_values (Any): The acceptable values from the filter dictionary.
-                              Can be a single value or a list/set of acceptable values.
-
-    Returns:
-        bool: True if the config_value satisfies the criteria, False otherwise.
-
-    Matching Logic:
-        - **None config values**: Always return False (missing fields don't match)
-        - **List config values**:
-            - If criteria is a list: Match if there's any intersection (set overlap)
-            - If criteria is scalar: Match if the scalar is contained in the config list
-        - **Scalar config values**:
-            - If criteria is a list: Match if the config value is in the criteria list
-            - If criteria is scalar: Match if the values are exactly equal
-
-    Examples:
-        ```python
-        # List config value with list criteria (intersection matching)
-        _satisfies_criteria(["gpt-4", "gpt-3.5"], ["gpt-4", "claude"])  # True (gpt-4 intersects)
-        _satisfies_criteria(["tag1", "tag2"], ["tag3", "tag4"])  # False (no intersection)
-
-        # List config value with scalar criteria (containment matching)
-        _satisfies_criteria(["premium", "latest"], "premium")  # True (premium is in list)
-        _satisfies_criteria(["tag1", "tag2"], "tag3")  # False (tag3 not in list)
-
-        # Scalar config value with list criteria (membership matching)
-        _satisfies_criteria("gpt-4", ["gpt-4", "gpt-3.5"])  # True (gpt-4 in criteria)
-        _satisfies_criteria("claude", ["gpt-4", "gpt-3.5"])  # False (claude not in criteria)
-
-        # Scalar config value with scalar criteria (equality matching)
-        _satisfies_criteria("openai", "openai")  # True (exact match)
-        _satisfies_criteria("openai", "azure")  # False (different values)
-
-        # None config values (missing fields)
-        _satisfies_criteria(None, ["gpt-4"])  # False (missing field)
-        _satisfies_criteria(None, "gpt-4")  # False (missing field)
-        ```
+    warnings.warn(
+        "`autogen.filter_config(...)` is deprecated. "
+        'Please use the "autogen.LLMConfig.from_json(path="OAI_CONFIG_LIST").where(model="gpt-4o")" method instead. '
+        "Scheduled for removal in 0.11.0 version.",
+        DeprecationWarning,
+    )
 
-    Note:
-        This is an internal helper function used by `filter_config()`. The function
-        assumes that both parameters can be of various types and handles type
-        checking internally to determine the appropriate matching strategy.
-    """
-    if config_value is None:
-        return False
-
-    if isinstance(config_value, list):
-        if isinstance(criteria_values, list):
-            return bool(set(config_value) & set(criteria_values))  # Non-empty intersection
-        else:
-            return criteria_values in config_value
-    else:
-        # In filter_dict, filter could be either a list of values or a single value.
-        # For example, filter_dict = {"model": ["gpt-3.5-turbo"]} or {"model": "gpt-3.5-turbo"}
-        if isinstance(criteria_values, list):
-            return config_value in criteria_values
-        return bool(config_value == criteria_values)
+    return latest_filter(config_list=config_list, filter_dict=filter_dict, exclude=exclude)
 
 
 @export_module("autogen")
+@deprecated(
+    "`autogen.config_list_from_json(...)` is deprecated. "
+    'Please use the "autogen.LLMConfig.from_json(path="OAI_CONFIG_LIST")" method instead. '
+    "Scheduled for removal in 0.11.0 version."
+)
 def config_list_from_json(
     env_or_file: str,
     file_location: str | None = "",
@@ -669,34 +614,18 @@ def config_list_from_json(
     Raises:
         FileNotFoundError: if env_or_file is neither found as an environment variable nor a file
     """
-    if inspect.stack()[1].function != "from_json":
-        warnings.warn(
-            "config_list_from_json is deprecated and will be removed in a future release. "
-            'Please use the "autogen.LLMConfig.from_json(path="OAI_CONFIG_LIST")" method instead.',
-            DeprecationWarning,
-        )
-
-    env_str = os.environ.get(env_or_file)
-
-    if env_str:
-        # The environment variable exists. We should use information from it.
-        if os.path.exists(env_str):
-            # It is a file location, and we need to load the json from the file.
-            with open(env_str) as file:
-                json_str = file.read()
-        else:
-            # Else, it should be a JSON string by itself.
-            json_str = env_str
-        config_list = json.loads(json_str)
-    else:
-        # The environment variable does not exist.
-        # So, `env_or_file` is a filename. We should use the file location.
-        config_list_path = os.path.join(file_location, env_or_file) if file_location is not None else env_or_file
-
-        with open(config_list_path) as json_file:
-            config_list = json.load(json_file)
+    warnings.warn(
+        "`autogen.config_list_from_json(...)` is deprecated. "
+        'Please use the "autogen.LLMConfig.from_json(path="OAI_CONFIG_LIST")" method instead. '
+        "Scheduled for removal in 0.11.0 version.",
+        DeprecationWarning,
+    )
 
-    return filter_config(config_list, filter_dict)
+    return latest_config_list_from_json(
+        env_or_file=env_or_file,
+        file_location=file_location,
+        filter_dict=filter_dict,
+    )
 
 
 def get_config(

autogen/remote/__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
+
+try:
+    import httpx  # noqa: F401
+except ImportError as e:
+    raise ImportError("httpx is not installed. Please install it with:\npip install httpx") from e
+
+from .agent import HTTPRemoteAgent
+from .httpx_client_factory import HttpxClientFactory
+from .runtime import HTTPAgentBus
+
+__all__ = (
+    "HTTPAgentBus",
+    "HTTPRemoteAgent",
+    "HttpxClientFactory",
+)

autogen/remote/agent.py

@@ -0,0 +1,199 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+from typing import Any
+
+import httpx
+
+from autogen import ConversableAgent
+from autogen.agentchat.group import ContextVariables
+from autogen.oai.client import OpenAIWrapper
+
+from .errors import RemoteAgentError, RemoteAgentNotFoundError
+from .httpx_client_factory import ClientFactory, EmptyClientFactory
+from .protocol import RequestMessage, ResponseMessage
+from .retry import NoRetryPolicy, RetryPolicy
+
+
+class HTTPRemoteAgent(ConversableAgent):
+    """A remote agent that communicates with other agents via HTTP long-polling.
+
+    This agent forwards messages to a remote endpoint and handles the response
+    through HTTP requests. It supports both synchronous and asynchronous operations.
+
+    Example:
+        >>> remote_agent = HTTPRemoteAgent(url="http://api.example.com/agents", name="my_remote_agent")
+    """
+
+    def __init__(
+        self,
+        url: str,
+        name: str,
+        *,
+        silent: bool = False,
+        client: ClientFactory | None = None,
+        retry_policy: RetryPolicy | None = None,
+    ) -> None:
+        """Initialize the HTTPRemoteAgent.
+
+        Args:
+            url (str): The base URL of the remote agent service.
+            name (str): The name of this agent.
+            silent (bool): If True, suppresses logging output.
+            client (ClientFactory | None): HTTP client factory. If None, uses EmptyClientFactory.
+            retry_policy (RetryPolicy | None): Retry policy for HTTP requests. If None, uses NoRetryPolicy.
+        """
+
+        self.url = url
+        self.retry_policy: RetryPolicy = retry_policy or NoRetryPolicy
+
+        self._httpx_client_factory = client or EmptyClientFactory()
+
+        super().__init__(name, silent=silent)
+
+        self.__llm_config: dict[str, Any] = {}
+
+        self.replace_reply_func(
+            ConversableAgent.generate_oai_reply,
+            HTTPRemoteAgent.generate_remote_reply,
+        )
+        self.replace_reply_func(
+            ConversableAgent.a_generate_oai_reply,
+            HTTPRemoteAgent.a_generate_remote_reply,
+        )
+
+    def generate_remote_reply(
+        self,
+        messages: list[dict[str, Any]] | None = None,
+        sender: ConversableAgent | None = None,
+        config: OpenAIWrapper | None = None,
+    ) -> tuple[bool, dict[str, Any] | None]:
+        if messages is None:
+            messages = self._oai_messages[sender]
+
+        retry_policy = self.retry_policy()
+
+        task_id: Any = None
+        with self._httpx_client_factory.make_sync() as client:
+            while True:
+                with retry_policy:
+                    if task_id is None:
+                        # initiate remote procedure
+                        task_id = self._process_create_remote_task_response(
+                            client.post(
+                                f"{self.url}/{self.name}",
+                                content=RequestMessage(
+                                    messages=messages,
+                                    context=self.context_variables.data,
+                                    client_tools=self.__llm_config.get("tools", []),
+                                ).model_dump_json(),
+                            )
+                        )
+
+                    reply_response = client.get(f"{self.url}/{self.name}/{task_id}")
+
+                    if reply_response.status_code in (200, 204):  # valid answer codes
+                        break
+
+                    if reply_response.status_code == 425:  # task still in progress
+                        continue
+
+                    if reply_response.status_code == 404:
+                        task_id = None  # recreate task due remote agent lost it
+                        continue
+
+                    raise RemoteAgentError(f"Remote client error: {reply_response}, {reply_response.content!r}")
+
+        if reply := self._process_remote_reply(reply_response):
+            if sender:
+                context_variables = ContextVariables(reply.context)
+                sender.context_variables.update(context_variables.to_dict())
+            # TODO: support multiple messages response for remote chat history
+            return True, reply.messages[-1]
+
+        return True, None
+
+    async def a_generate_remote_reply(
+        self,
+        messages: list[dict[str, Any]] | None = None,
+        sender: ConversableAgent | None = None,
+        config: OpenAIWrapper | None = None,
+    ) -> tuple[bool, dict[str, Any] | None]:
+        if messages is None:
+            messages = self._oai_messages[sender]
+
+        retry_policy = self.retry_policy()
+
+        task_id: Any = None
+        async with self._httpx_client_factory() as client:
+            while True:
+                with retry_policy:
+                    if task_id is None:
+                        # initiate remote procedure
+                        task_id = self._process_create_remote_task_response(
+                            await client.post(
+                                f"{self.url}/{self.name}",
+                                content=RequestMessage(
+                                    messages=messages,
+                                    context=self.context_variables.data,
+                                    client_tools=self.__llm_config.get("tools", []),
+                                ).model_dump_json(),
+                            )
+                        )
+
+                    reply_response = await client.get(f"{self.url}/{self.name}/{task_id}")
+
+                    if reply_response.status_code in (200, 204):  # valid answer codes
+                        break
+
+                    if reply_response.status_code == 425:  # task still in progress
+                        continue
+
+                    if reply_response.status_code == 404:
+                        task_id = None  # recreate task due remote agent lost it
+                        continue
+
+                    raise RemoteAgentError(f"Remote client error: {reply_response}, {reply_response.content!r}")
+
+        if reply := self._process_remote_reply(reply_response):
+            if sender:
+                context_variables = ContextVariables(reply.context)
+                sender.context_variables.update(context_variables.to_dict())
+            # TODO: support multiple messages response for remote chat history
+            return True, reply.messages[-1]
+
+        return True, None
+
+    def _process_create_remote_task_response(self, response: httpx.Response) -> Any:
+        if response.status_code == 404:
+            raise RemoteAgentNotFoundError(self.name)
+
+        if response.status_code != 202:
+            raise RemoteAgentError(f"Remote client error: {response}, {response.content!r}")
+
+        return response.json()
+
+    def _process_remote_reply(self, reply_response: httpx.Response) -> ResponseMessage | None:
+        if reply_response.status_code == 204:
+            return None
+
+        try:
+            serialized_message = ResponseMessage.model_validate_json(reply_response.content)
+
+        except Exception as e:
+            raise RemoteAgentError(f"Remote client error: {reply_response}, {reply_response.content!r}") from e
+
+        return serialized_message
+
+    def update_tool_signature(
+        self,
+        tool_sig: str | dict[str, Any],
+        is_remove: bool,
+        silent_override: bool = False,
+    ) -> None:
+        self.__llm_config = self._update_tool_config(
+            self.__llm_config,
+            tool_sig=tool_sig,
+            is_remove=is_remove,
+            silent_override=silent_override,
+        )

autogen/remote/agent_service.py

@@ -0,0 +1,142 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import warnings
+from typing import Any, Literal, cast
+
+from autogen.agentchat import ConversableAgent
+from autogen.agentchat.conversable_agent import normilize_message_to_oai
+from autogen.agentchat.group.context_variables import ContextVariables
+from autogen.agentchat.group.group_tool_executor import GroupToolExecutor
+from autogen.agentchat.group.reply_result import ReplyResult
+from autogen.agentchat.group.targets.transition_target import TransitionTarget
+
+from .protocol import RemoteService, RequestMessage, ResponseMessage, get_tool_names
+
+
+class AgentService(RemoteService):
+    def __init__(self, agent: ConversableAgent) -> None:
+        self.name = agent.name
+        self.agent = agent
+
+    async def __call__(self, state: RequestMessage) -> ResponseMessage | None:
+        out_message: dict[str, Any] | None
+        if guardrail_result := self.agent.run_input_guardrails(state.messages):
+            # input guardrail activated by initial messages
+            _, out_message = normilize_message_to_oai(guardrail_result.reply, self.agent.name, role="assistant")
+            return ResponseMessage(messages=[out_message], context=state.context)
+
+        context_variables = ContextVariables(state.context)
+        tool_executor = self._make_tool_executor(context_variables)
+
+        local_history: list[dict[str, Any]] = []
+        while True:
+            messages = state.messages + local_history
+
+            # TODO: catch ask user input event
+            is_final, _ = await self.agent.a_check_termination_and_human_reply(messages)
+            if is_final:
+                break
+
+            reply = await self.agent.a_generate_reply(
+                messages,
+                exclude=(
+                    ConversableAgent.check_termination_and_human_reply,
+                    ConversableAgent.a_check_termination_and_human_reply,
+                    ConversableAgent.generate_oai_reply,
+                    ConversableAgent.a_generate_oai_reply,
+                ),
+            )
+
+            if not reply:
+                _, reply = await self.agent.a_generate_oai_reply(
+                    messages,
+                    tools=state.client_tools,
+                )
+
+            should_continue, out_message = self._add_message_to_local_history(reply, role="assistant")
+            if out_message:
+                local_history.append(out_message)
+            if not should_continue:
+                break
+            out_message = cast(dict[str, Any], out_message)
+
+            called_tools = get_tool_names(out_message.get("tool_calls", []))
+            if state.client_tool_names.intersection(called_tools):
+                break  # return client tool execution command back to client
+
+            tool_result, updated_context_variables = self._try_execute_local_tool(tool_executor, out_message)
+
+            if updated_context_variables:
+                context_variables.update(updated_context_variables.to_dict())
+
+            should_continue, out_message = self._add_message_to_local_history(tool_result, role="tool")
+            if out_message:
+                local_history.append(out_message)
+            if not should_continue:
+                break
+
+        if not local_history:
+            return None
+
+        return ResponseMessage(messages=local_history, context=context_variables.data or None)
+
+    def _add_message_to_local_history(
+        self, message: str | dict[str, Any] | None, role: str
+    ) -> tuple[Literal[True], dict[str, Any]] | tuple[Literal[False], dict[str, Any] | None]:
+        if message is None:
+            return False, None  # output message is empty, interrupt the loop
+
+        if guardrail_result := self.agent.run_output_guardrails(message):
+            _, out_message = normilize_message_to_oai(guardrail_result.reply, self.agent.name, role=role)
+            return False, out_message  # output guardrail activated, interrupt the loop
+
+        valid, out_message = normilize_message_to_oai(message, self.agent.name, role=role)
+        if not valid:
+            return False, None  # tool result is not valid OAI message, interrupt the loop
+
+        return True, out_message
+
+    def _make_tool_executor(self, context_variables: ContextVariables) -> GroupToolExecutor:
+        tool_executor = GroupToolExecutor()
+        for tool in self.agent.tools:
+            # TODO: inject ChatContext to tool
+            new_tool = tool_executor.make_tool_copy_with_context_variables(tool, context_variables) or tool
+            tool_executor.register_for_execution(serialize=False, silent_override=True)(new_tool)
+        return tool_executor
+
+    def _try_execute_local_tool(
+        self,
+        tool_executor: GroupToolExecutor,
+        tool_message: dict[str, Any],
+    ) -> tuple[dict[str, Any] | None, ContextVariables | None]:
+        tool_result: dict[str, Any] | None = None
+        updated_context_variables: ContextVariables | None = None
+
+        if "tool_calls" in tool_message:
+            _, tool_result = tool_executor.generate_tool_calls_reply([tool_message])
+            if tool_result is None:
+                return tool_result, updated_context_variables
+
+            if "tool_responses" in tool_result:
+                # TODO: catch handoffs
+                for tool_response in tool_result["tool_responses"]:
+                    content = tool_response["content"]
+
+                    if isinstance(content, TransitionTarget):
+                        warnings.warn(
+                            f"Tool {self.agent.name} returned a target, which is not supported in remote mode"
+                        )
+
+                    elif isinstance(content, ReplyResult):
+                        if content.target:
+                            warnings.warn(
+                                f"Tool {self.agent.name} returned a target, which is not supported in remote mode"
+                            )
+
+                        if content.context_variables:
+                            updated_context_variables = content.context_variables
+                            tool_response["content"] = content.message
+
+        return tool_result, updated_context_variables

autogen/remote/errors.py

@@ -0,0 +1,17 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+class RemoteAgentError(Exception):
+    """Base class for remote agent errors"""
+
+    pass
+
+
+class RemoteAgentNotFoundError(RemoteAgentError):
+    """Raised when a remote agent is not found"""
+
+    def __init__(self, agent_name: str) -> None:
+        self.agent_name = agent_name
+        super().__init__(f"Remote agent `{agent_name}` not found")