ag2 0.10.2__py3-none-any.whl

autogen/remote/agent_service.py

@@ -0,0 +1,197 @@
+# 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 AskUserTarget, TransitionTarget
+from autogen.events.agent_events import TerminationAndHumanReplyNoInputEvent, TerminationEvent, UsingAutoReplyEvent
+from autogen.events.base_event import BaseEvent
+from autogen.io.base import AsyncIOStreamProtocol
+
+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
+
+            stream = HITLStream()
+            await self.agent.a_check_termination_and_human_reply(messages, iostream=stream)
+            if stream.is_input_required:
+                return ResponseMessage(
+                    messages=local_history,
+                    context=context_variables.data or None,
+                    input_required=stream.input_prompt,
+                )
+
+            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, return_to_user = 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 return_to_user:
+                return ResponseMessage(
+                    messages=local_history,
+                    context=context_variables.data or None,
+                    input_required="Please, provide additional information:\n",
+                )
+
+            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, bool]:
+        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, False
+
+            if "tool_responses" in tool_result:
+                # TODO: catch handoffs
+                for tool_response in tool_result["tool_responses"]:
+                    content = tool_response["content"]
+
+                    if isinstance(content, AskUserTarget):
+                        return tool_result, updated_context_variables, True
+
+                    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.context_variables:
+                            updated_context_variables = content.context_variables
+                            tool_response["content"] = content.message
+
+                        if isinstance(content.target, AskUserTarget):
+                            return tool_result, updated_context_variables, True
+
+                        if content.target:
+                            warnings.warn(
+                                f"Tool {self.agent.name} returned a target, which is not supported in remote mode"
+                            )
+
+        return tool_result, updated_context_variables, False
+
+
+class HITLStream(AsyncIOStreamProtocol):
+    def __init__(self) -> None:
+        self.input_prompt = ""
+
+    @property
+    def is_input_required(self) -> bool:
+        return bool(self.input_prompt)
+
+    async def input(self, prompt: str = "", *, password: bool = False) -> str:
+        self.input_prompt = prompt
+        return ""
+
+    def print(self, *objects: Any, sep: str = " ", end: str = "\n", flush: bool = False) -> None:
+        raise NotImplementedError("HITLStream does not support printing")
+
+    def send(self, message: BaseEvent) -> None:
+        if isinstance(
+            message,
+            (
+                UsingAutoReplyEvent,
+                TerminationAndHumanReplyNoInputEvent,
+                TerminationEvent,
+            ),
+        ):
+            return
+
+        raise NotImplementedError("HITLStream does not support sending messages")

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")

autogen/remote/httpx_client_factory.py

@@ -0,0 +1,131 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import ssl
+import typing
+from typing import Protocol
+
+from httpx._client import AsyncClient, Client, EventHook
+from httpx._config import DEFAULT_LIMITS, DEFAULT_MAX_REDIRECTS, DEFAULT_TIMEOUT_CONFIG, Limits
+from httpx._transports.base import AsyncBaseTransport
+from httpx._types import AuthTypes, CertTypes, CookieTypes, HeaderTypes, ProxyTypes, QueryParamTypes, TimeoutTypes
+from httpx._urls import URL
+
+from autogen.doc_utils import export_module
+
+
+class ClientFactory(Protocol):
+    def __call__(self) -> AsyncClient: ...
+
+    def make_sync(self) -> Client: ...
+
+
+@export_module("autogen.a2a")
+class HttpxClientFactory(ClientFactory):
+    """
+    An asynchronous HTTP client factory, with connection pooling, HTTP/2, redirects,
+    cookie persistence, etc.
+
+    It can be shared between tasks.
+
+    Usage:
+
+    ```python
+    >>> factory = HttpxClientFactory()
+    >>> async with factory() as client:
+    >>>     response = await client.get('https://example.org')
+    ```
+
+    **Parameters:**
+
+    * **auth** - *(optional)* An authentication class to use when sending
+    requests.
+    * **params** - *(optional)* Query parameters to include in request URLs, as
+    a string, dictionary, or sequence of two-tuples.
+    * **headers** - *(optional)* Dictionary of HTTP headers to include when
+    sending requests.
+    * **cookies** - *(optional)* Dictionary of Cookie items to include when
+    sending requests.
+    * **verify** - *(optional)* Either `True` to use an SSL context with the
+    default CA bundle, `False` to disable verification, or an instance of
+    `ssl.SSLContext` to use a custom context.
+    * **http2** - *(optional)* A boolean indicating if HTTP/2 support should be
+    enabled. Defaults to `False`.
+    * **proxy** - *(optional)* A proxy URL where all the traffic should be routed.
+    * **timeout** - *(optional)* The timeout configuration to use when sending
+    requests.
+    * **limits** - *(optional)* The limits configuration to use.
+    * **max_redirects** - *(optional)* The maximum number of redirect responses
+    that should be followed.
+    * **base_url** - *(optional)* A URL to use as the base when building
+    request URLs.
+    * **transport** - *(optional)* A transport class to use for sending requests
+    over the network.
+    * **trust_env** - *(optional)* Enables or disables usage of environment
+    variables for configuration.
+    * **default_encoding** - *(optional)* The default encoding to use for decoding
+    response text, if no charset information is included in a response Content-Type
+    header. Set to a callable for automatic character set detection. Default: "utf-8".
+    """
+
+    def __init__(
+        self,
+        *,
+        auth: AuthTypes | None = None,
+        params: QueryParamTypes | None = None,
+        headers: HeaderTypes | None = None,
+        cookies: CookieTypes | None = None,
+        verify: ssl.SSLContext | str | bool = True,
+        cert: CertTypes | None = None,
+        http1: bool = True,
+        http2: bool = False,
+        proxy: ProxyTypes | None = None,
+        mounts: None | (typing.Mapping[str, AsyncBaseTransport | None]) = None,
+        timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
+        follow_redirects: bool = False,
+        limits: Limits = DEFAULT_LIMITS,
+        max_redirects: int = DEFAULT_MAX_REDIRECTS,
+        event_hooks: None | (typing.Mapping[str, list[EventHook]]) = None,
+        base_url: URL | str = "",
+        transport: AsyncBaseTransport | None = None,
+        trust_env: bool = True,
+        default_encoding: str | typing.Callable[[bytes], str] = "utf-8",
+        **kwargs: typing.Any,
+    ) -> None:
+        self.options = {
+            "auth": auth,
+            "params": params,
+            "headers": headers,
+            "cookies": cookies,
+            "verify": verify,
+            "cert": cert,
+            "http1": http1,
+            "http2": http2,
+            "proxy": proxy,
+            "mounts": mounts,
+            "timeout": timeout,
+            "follow_redirects": follow_redirects,
+            "limits": limits,
+            "max_redirects": max_redirects,
+            "event_hooks": event_hooks,
+            "base_url": base_url,
+            "transport": transport,
+            "trust_env": trust_env,
+            "default_encoding": default_encoding,
+            **kwargs,
+        }
+
+    def __call__(self) -> AsyncClient:
+        return AsyncClient(**self.options)
+
+    def make_sync(self) -> Client:
+        return Client(**self.options)
+
+
+class EmptyClientFactory(ClientFactory):
+    def __call__(self) -> AsyncClient:
+        return AsyncClient(timeout=30.0)
+
+    def make_sync(self) -> Client:
+        return Client(timeout=30.0)

autogen/remote/protocol.py

@@ -0,0 +1,37 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+from typing import Any, Protocol
+
+from pydantic import BaseModel, Field
+
+
+class AgentBusMessage(BaseModel):
+    messages: list[dict[str, Any]] = Field(default_factory=list)
+    context: dict[str, Any] | None = None
+
+
+class RequestMessage(AgentBusMessage):
+    client_tools: list[dict[str, Any]] = Field(default_factory=list)
+
+    @property
+    def client_tool_names(self) -> set[str]:
+        return get_tool_names(self.client_tools)
+
+
+class ResponseMessage(AgentBusMessage):
+    input_required: str | None = None
+
+
+class RemoteService(Protocol):
+    """Interface to make AgentBus compatible with non AG2 systems."""
+
+    name: str
+
+    async def __call__(self, state: RequestMessage) -> ResponseMessage | None:
+        """Executable that consumes Conversation State and returns a new state."""
+        ...
+
+
+def get_tool_names(tools: list[dict[str, Any]]) -> set[str]:
+    return set(filter(bool, (tool.get("function", {}).get("name", "") for tool in tools)))

autogen/remote/retry.py

@@ -0,0 +1,102 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+import time
+from types import TracebackType
+from typing import Protocol
+
+import anyio
+
+
+class RetryPolicyManager(Protocol):
+    def __enter__(self) -> None:
+        pass
+
+    async def __aenter__(self) -> None:
+        pass
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
+    ) -> None | bool:
+        pass
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
+    ) -> None | bool:
+        pass
+
+
+class RetryPolicy(Protocol):
+    def __call__(self) -> RetryPolicyManager: ...
+
+
+class SleepRetryPolicy(RetryPolicy):
+    def __init__(self, retry_interval: float = 10.0, retry_count: int = 3) -> None:
+        self.retry_interval = retry_interval
+        self.retry_count = retry_count
+
+    def __call__(self) -> RetryPolicyManager:
+        return _SleepRetryPolicy(self.retry_interval, self.retry_count)
+
+
+class _SleepRetryPolicy(RetryPolicyManager):
+    def __init__(self, retry_interval: float = 10.0, retry_count: int = 3) -> None:
+        self.retry_interval = retry_interval
+        self.retry_count = retry_count
+        self.errors_count = 0
+
+    def __enter__(self) -> None:
+        pass
+
+    async def __aenter__(self) -> None:
+        pass
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None | bool:
+        if exc_type is not None:
+            self.errors_count += 1
+            should_suppress = self.errors_count < self.retry_count
+            time.sleep(self.retry_interval)
+            return should_suppress
+        return None
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None | bool:
+        if exc_type is not None:
+            self.errors_count += 1
+            should_suppress = self.errors_count < self.retry_count
+            await anyio.sleep(self.retry_interval)
+            return should_suppress
+        return None
+
+
+class NoRetryPolicy(RetryPolicyManager):
+    def __enter__(self) -> None:
+        pass
+
+    async def __aenter__(self) -> None:
+        pass
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None | bool:
+        pass
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None | bool:
+        pass

autogen/remote/runtime.py

@@ -0,0 +1,96 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import asyncio
+from collections.abc import Awaitable, Callable, Iterable, MutableMapping
+from itertools import chain
+from typing import Any
+from uuid import UUID, uuid4
+
+from fastapi import FastAPI, HTTPException, Response, status
+
+from autogen.agentchat import ConversableAgent
+
+from .agent_service import AgentService
+from .protocol import RemoteService, RequestMessage, ResponseMessage
+
+
+class HTTPAgentBus:
+    def __init__(
+        self,
+        agents: Iterable[ConversableAgent] = (),
+        *,
+        long_polling_interval: float = 10.0,
+        additional_services: Iterable[RemoteService] = (),
+    ) -> None:
+        """Create HTTPAgentBus runtime.
+
+        Makes the passed agents capable of processing remote calls.
+
+        Args:
+            agents: Agents to register as remote services.
+            long_polling_interval: Timeout to respond on task status calls for long-living executions.
+                Should be less than clients' HTTP request timeout.
+            additional_services: Additional services to register.
+        """
+        self.app = FastAPI()
+
+        for service in chain(map(AgentService, agents), additional_services):
+            register_agent_endpoints(
+                app=self.app,
+                service=service,
+                long_polling_interval=long_polling_interval,
+            )
+
+    async def __call__(
+        self,
+        scope: MutableMapping[str, Any],
+        receive: Callable[[], Awaitable[MutableMapping[str, Any]]],
+        send: Callable[[MutableMapping[str, Any]], Awaitable[None]],
+    ) -> None:
+        """ASGI interface."""
+        await self.app(scope, receive, send)
+
+
+def register_agent_endpoints(
+    app: FastAPI,
+    service: RemoteService,
+    long_polling_interval: float,
+) -> None:
+    tasks: dict[UUID, asyncio.Task[ResponseMessage | None]] = {}
+
+    @app.get(f"/{service.name}" + "/{task_id}", response_model=ResponseMessage | None)
+    async def remote_call_result(task_id: UUID) -> Response | ResponseMessage | None:
+        if task_id not in tasks:
+            raise HTTPException(
+                detail=f"`{task_id}` task not found",
+                status_code=status.HTTP_404_NOT_FOUND,
+            )
+
+        task = tasks[task_id]
+
+        await asyncio.wait(
+            (task, asyncio.create_task(asyncio.sleep(long_polling_interval))),
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+
+        if not task.done():
+            return Response(status_code=status.HTTP_425_TOO_EARLY)
+
+        try:
+            reply = task.result()  # Task inner errors raising here
+        finally:
+            # TODO: how to clear hanged tasks?
+            tasks.pop(task_id, None)
+
+        if reply is None:
+            return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+        return reply
+
+    @app.post(f"/{service.name}", status_code=status.HTTP_202_ACCEPTED)
+    async def remote_call_starter(state: RequestMessage) -> UUID:
+        task, task_id = asyncio.create_task(service(state)), uuid4()
+        tasks[task_id] = task
+        return task_id