ag2 0.10.2__py3-none-any.whl

autogen/a2a/client.py

@@ -0,0 +1,357 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import asyncio
+import logging
+from collections.abc import Sequence
+from pprint import pformat
+from typing import Any, cast
+from uuid import uuid4
+
+import httpx
+from a2a.client import A2ACardResolver, A2AClientHTTPError, Client, ClientCallInterceptor, ClientConfig, ClientEvent
+from a2a.client import ClientFactory as A2AClientFactory
+from a2a.types import AgentCard, Message, Task, TaskIdParams, TaskQueryParams, TaskState
+from a2a.utils.constants import AGENT_CARD_WELL_KNOWN_PATH, EXTENDED_AGENT_CARD_PATH, PREV_AGENT_CARD_WELL_KNOWN_PATH
+from typing_extensions import Self
+
+from autogen import ConversableAgent
+from autogen.agentchat.group import ContextVariables
+from autogen.doc_utils import export_module
+from autogen.events.agent_events import TerminationEvent
+from autogen.io.base import IOStream
+from autogen.oai.client import OpenAIWrapper
+from autogen.remote.httpx_client_factory import ClientFactory, EmptyClientFactory
+from autogen.remote.protocol import RequestMessage, ResponseMessage
+
+from .errors import A2aAgentNotFoundError, A2aClientError
+from .utils import (
+    request_message_to_a2a,
+    response_message_from_a2a_message,
+    response_message_from_a2a_task,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@export_module("autogen.a2a")
+class A2aRemoteAgent(ConversableAgent):
+    """`a2a-sdk`-based client for handling asynchronous communication with an A2A server.
+
+    It has fully-compatible with original `ConversableAgent` API, so you can easily integrate
+    remote A2A agents to existing collaborations.
+
+    Args:
+        url: The URL of the A2A server to connect to.
+        name: A unique identifier for this client instance.
+        silent: whether to print the message sent. If None, will use the value of silent in each function.
+        client: An optional HTTPX client instance factory.
+        client_config: A2A Client configuration options.
+        max_reconnects: Maximum number of reconnection attempts before giving up.
+        polling_interval: Time in seconds between polling operations. Works for A2A Servers doesn't support streaming.
+        interceptors: A list of interceptors to use for the client.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        name: str,
+        *,
+        silent: bool | None = None,
+        client: ClientFactory | None = None,
+        client_config: ClientConfig | None = None,
+        interceptors: Sequence[ClientCallInterceptor] = (),
+        max_reconnects: int = 3,
+        polling_interval: float = 0.5,
+    ) -> None:
+        self.url = url  # make it public for backward compatibility
+
+        self._httpx_client_factory = client or EmptyClientFactory()
+        self._card_resolver = A2ACardResolver(
+            httpx_client=self._httpx_client_factory(),
+            base_url=url,
+        )
+
+        self._max_reconnects = max_reconnects
+        self._polling_interval = polling_interval
+
+        super().__init__(name, silent=silent)
+
+        self.__llm_config: dict[str, Any] = {}
+
+        self._client_config = client_config or ClientConfig()
+        self._interceptors = list(interceptors)
+        self._agent_card: AgentCard | None = None
+
+        self.replace_reply_func(
+            ConversableAgent.generate_oai_reply,
+            A2aRemoteAgent.generate_remote_reply,
+        )
+        self.replace_reply_func(
+            ConversableAgent.a_generate_oai_reply,
+            A2aRemoteAgent.a_generate_remote_reply,
+        )
+
+    @classmethod
+    def from_card(
+        cls,
+        card: AgentCard,
+        *,
+        silent: bool | None = None,
+        client: ClientFactory | None = None,
+        client_config: ClientConfig | None = None,
+        max_reconnects: int = 3,
+        polling_interval: float = 0.5,
+        interceptors: Sequence[ClientCallInterceptor] = (),
+    ) -> Self:
+        """Creates an A2aRemoteAgent instance from an existing AgentCard.
+
+        This method allows you to instantiate an A2aRemoteAgent directly using a pre-existing
+        AgentCard, such as one retrieved from a discovery service or constructed manually.
+        The resulting agent will use the data from the given card and avoid redundant card
+        fetching. The agent's registryURL is set to "UNKNOWN" since it is assumed to be derived
+        from the card.
+
+        Args:
+            card: The agent card containing metadata and configuration for the remote agent.
+            silent: whether to print the message sent. If None, will use the value of silent in each function.
+            client: An optional HTTPX client instance factory.
+            client_config: A2A Client configuration options.
+            max_reconnects: Maximum number of reconnection attempts before giving up.
+            polling_interval: Time in seconds between polling operations. Works for A2A Servers doesn't support streaming.
+            interceptors: A list of interceptors to use for the client.
+
+        Returns:
+            Self: An instance of the A2aRemoteAgent configured with the provided card.
+        """
+        instance = cls(
+            url="UNKNOWN",
+            name=card.name,
+            silent=silent,
+            client=client,
+            client_config=client_config,
+            max_reconnects=max_reconnects,
+            polling_interval=polling_interval,
+            interceptors=interceptors,
+        )
+        instance._agent_card = card
+        return instance
+
+    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]:
+        raise NotImplementedError(f"{self.__class__.__name__} does not support synchronous reply generation")
+
+    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]
+
+        if not self._agent_card:
+            self._agent_card = await self._get_agent_card()
+
+        context_id = uuid4().hex
+
+        self._client_config.httpx_client = self._httpx_client_factory()
+        async with self._client_config.httpx_client:
+            agent_client = A2AClientFactory(self._client_config).create(
+                self._agent_card,
+                interceptors=self._interceptors,
+            )
+
+            while True:
+                initial_message = request_message_to_a2a(
+                    request_message=RequestMessage(
+                        messages=messages,
+                        context=self.context_variables.data,
+                        client_tools=self.__llm_config.get("tools", []),
+                    ),
+                    context_id=context_id,
+                )
+
+                if self._agent_card.capabilities.streaming:
+                    reply = await self._ask_streaming(agent_client, initial_message)
+                else:
+                    reply = await self._ask_polling(agent_client, initial_message)
+
+                if not reply:
+                    return True, None
+
+                messages = reply.messages
+                if reply.input_required is not None:
+                    user_input = await self.a_get_human_input(prompt=f"Input for `{self.name}`\n{reply.input_required}")
+
+                    if user_input == "exit":
+                        IOStream.get_default().send(
+                            TerminationEvent(
+                                termination_reason="User requested to end the conversation",
+                                sender=self,
+                                recipient=sender,
+                            )
+                        )
+                        return True, None
+
+                    messages.append({"content": user_input, "role": "user"})
+                    continue
+
+                if sender and reply.context:
+                    context_variables = ContextVariables(reply.context)
+                    self.context_variables.update(context_variables.to_dict())
+                    sender.context_variables.update(context_variables.to_dict())
+
+                return True, reply.messages[-1]
+
+    async def _ask_streaming(self, client: Client, message: Message) -> ResponseMessage | None:
+        connection_attemps = 1
+        try:
+            async for event in client.send_message(message):
+                result, task = self._process_event(event)
+                if not task:
+                    return result
+        except httpx.ConnectError as e:
+            if task and connection_attemps < self._max_reconnects:
+                pass
+
+            if not self._agent_card:
+                raise A2aClientError("Failed to connect to the agent: agent card not found") from e
+            raise A2aClientError(f"Failed to connect to the agent: {pformat(self._agent_card.model_dump())}") from e
+
+        task = cast(Task, task)
+        while connection_attemps < self._max_reconnects:
+            try:
+                async for event in client.resubscribe(TaskIdParams(id=task.id)):
+                    result, task = self._process_event(event)
+                    if not task:
+                        return result
+
+            except httpx.ConnectError as e:
+                connection_attemps += 1
+                if connection_attemps < self._max_reconnects:
+                    pass
+
+                if not self._agent_card:
+                    raise A2aClientError("Failed to connect to the agent: agent card not found") from e
+                raise A2aClientError(f"Failed to connect to the agent: {pformat(self._agent_card.model_dump())}") from e
+
+        return None
+
+    async def _ask_polling(self, client: Client, message: Message) -> ResponseMessage | None:
+        try:
+            async for event in client.send_message(message):
+                result, started_task = self._process_event(event)
+                if not started_task:
+                    return result
+                break
+        except httpx.ConnectError as e:
+            if not self._agent_card:
+                raise A2aClientError("Failed to connect to the agent: agent card not found") from e
+            raise A2aClientError(f"Failed to connect to the agent: {pformat(self._agent_card.model_dump())}") from e
+
+        started_task, connection_attemps = cast(Task, started_task), 0
+        while connection_attemps < self._max_reconnects:
+            while True:
+                try:
+                    task = await client.get_task(TaskQueryParams(id=started_task.id))
+
+                except httpx.ConnectError as e:
+                    connection_attemps += 1
+                    if connection_attemps < self._max_reconnects:
+                        pass
+
+                    if not self._agent_card:
+                        raise A2aClientError("Failed to connect to the agent: agent card not found") from e
+                    raise A2aClientError(
+                        f"Failed to connect to the agent: {pformat(self._agent_card.model_dump())}"
+                    ) from e
+
+                else:
+                    if _is_task_completed(task):
+                        return response_message_from_a2a_task(task)
+
+                    await asyncio.sleep(self._polling_interval)
+
+        return None
+
+    def _process_event(self, event: ClientEvent | Message) -> tuple[ResponseMessage | None, Task | None]:
+        if isinstance(event, Message):
+            return response_message_from_a2a_message(event), None
+
+        task, _ = event
+        if _is_task_completed(task):
+            return response_message_from_a2a_task(task), None
+
+        return None, task
+
+    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,
+        )
+
+    async def _get_agent_card(
+        self,
+        auth_http_kwargs: dict[str, Any] | None = None,
+    ) -> AgentCard:
+        card: AgentCard | None = None
+
+        try:
+            logger.info(
+                f"Attempting to fetch public agent card from: {self._card_resolver.base_url}{AGENT_CARD_WELL_KNOWN_PATH}"
+            )
+
+            try:
+                card = await self._card_resolver.get_agent_card(relative_card_path=AGENT_CARD_WELL_KNOWN_PATH)
+            except A2AClientHTTPError as e_public:
+                if e_public.status_code == 404:
+                    logger.info(
+                        f"Attempting to fetch public agent card from: {self._card_resolver.base_url}{PREV_AGENT_CARD_WELL_KNOWN_PATH}"
+                    )
+                    card = await self._card_resolver.get_agent_card(relative_card_path=PREV_AGENT_CARD_WELL_KNOWN_PATH)
+                else:
+                    raise e_public
+
+            if card.supports_authenticated_extended_card:
+                try:
+                    card = await self._card_resolver.get_agent_card(
+                        relative_card_path=EXTENDED_AGENT_CARD_PATH,
+                        http_kwargs=auth_http_kwargs,
+                    )
+                except Exception as e_extended:
+                    logger.warning(
+                        f"Failed to fetch extended agent card: {e_extended}. Will proceed with public card.",
+                        exc_info=True,
+                    )
+
+        except Exception as e:
+            raise A2aAgentNotFoundError(f"{self.name}: {self._card_resolver.base_url}") from e
+
+        return card
+
+
+def _is_task_completed(task: Task) -> bool:
+    if task.status.state is TaskState.failed:
+        raise A2aClientError(f"Task failed: {pformat(task.model_dump())}")
+
+    if task.status.state is TaskState.rejected:
+        raise A2aClientError(f"Task rejected: {pformat(task.model_dump())}")
+
+    return task.status.state in (
+        TaskState.completed,
+        TaskState.canceled,
+        TaskState.input_required,
+    )

autogen/a2a/errors.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
+
+
+from autogen.remote.errors import RemoteAgentError, RemoteAgentNotFoundError
+
+
+class A2aClientError(RemoteAgentError):
+    """Base class for A2A agent errors"""
+
+    pass
+
+
+class A2aAgentNotFoundError(A2aClientError, RemoteAgentNotFoundError):
+    """Raised when a A2A agent is not found"""
+
+    pass

autogen/a2a/httpx_client_factory.py

@@ -0,0 +1,79 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+from uuid import uuid4
+
+from a2a.types import AgentCapabilities, AgentCard, DataPart, Message, Part, Role, SendMessageSuccessResponse, TextPart
+from a2a.utils.constants import AGENT_CARD_WELL_KNOWN_PATH, EXTENDED_AGENT_CARD_PATH, PREV_AGENT_CARD_WELL_KNOWN_PATH
+from httpx import MockTransport, Request, Response
+
+from autogen.doc_utils import export_module
+from autogen.remote.httpx_client_factory import HttpxClientFactory
+
+
+@export_module("autogen.a2a")
+def MockClient(  # noqa: N802
+    response_message: str | dict[str, Any] | TextPart | DataPart | Part,
+) -> HttpxClientFactory:
+    """Create a mock HTTP client for testing A2A agent interactions.
+
+    This function creates a mock HTTP client that simulates responses from an A2A agent server.
+    It handles both agent card requests and message sending requests with configurable responses.
+
+    Args:
+        response_message: The message to return in response to SendMessage requests.
+
+    Returns:
+        An HttpxClientFactory configured with a mock transport that handles requests
+        to agent card endpoints and message sending endpoints.
+
+    Example:
+        >>> client = MockClient("Hello, world!")
+        >>> agent = A2aRemoteAgent(name="remote", url="http://fake", client=client)
+    """
+    if isinstance(response_message, Part):
+        parts = [response_message]
+    elif isinstance(response_message, (DataPart, TextPart)):
+        parts = [Part(root=response_message)]
+    elif isinstance(response_message, str):
+        parts = [Part(root=DataPart(data={"role": "assistant", "content": response_message}))]
+    elif isinstance(response_message, dict):
+        parts = [Part(root=DataPart(data={"role": "assistant", **response_message}))]
+    else:
+        raise ValueError(f"Invalid message type: {type(response_message)}")
+
+    async def mock_handler(request: Request) -> Response:
+        if (
+            request.url.path == AGENT_CARD_WELL_KNOWN_PATH
+            or request.url.path == EXTENDED_AGENT_CARD_PATH
+            or request.url.path == PREV_AGENT_CARD_WELL_KNOWN_PATH
+        ):
+            return Response(
+                status_code=200,
+                content=AgentCard(
+                    capabilities=AgentCapabilities(streaming=False),
+                    default_input_modes=["text"],
+                    default_output_modes=["text"],
+                    name="mock_agent",
+                    description="mock_agent",
+                    url="http://localhost:8000",
+                    supports_authenticated_extended_card=False,
+                    version="0.1.0",
+                    skills=[],
+                ).model_dump_json(),
+            )
+
+        return Response(
+            status_code=200,
+            content=SendMessageSuccessResponse(
+                result=Message(
+                    message_id=str(uuid4()),
+                    role=Role.agent,
+                    parts=parts,
+                ),
+            ).model_dump_json(),
+        )
+
+    return HttpxClientFactory(transport=MockTransport(handler=mock_handler))

autogen/a2a/server.py

@@ -0,0 +1,221 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import warnings
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+from a2a.types import AgentCapabilities, AgentCard, AgentSkill
+from pydantic import Field
+
+from autogen import ConversableAgent
+from autogen.doc_utils import export_module
+
+from .agent_executor import AutogenAgentExecutor
+
+if TYPE_CHECKING:
+    from a2a.server.agent_execution import RequestContextBuilder
+    from a2a.server.apps import CallContextBuilder
+    from a2a.server.context import ServerCallContext
+    from a2a.server.events import QueueManager
+    from a2a.server.request_handlers import RequestHandler
+    from a2a.server.tasks import PushNotificationConfigStore, PushNotificationSender, TaskStore
+    from starlette.applications import Starlette
+
+    from autogen import ConversableAgent
+
+
+@export_module("autogen.a2a")
+class CardSettings(AgentCard):
+    """Original A2A AgentCard object inheritor making some fields optional."""
+
+    name: str | None = None  # type: ignore[assignment]
+    """
+    A human-readable name for the agent. Uses original agent name if not set.
+    """
+
+    description: str | None = None  # type: ignore[assignment]
+    """
+    A human-readable description of the agent, assisting users and other agents
+    in understanding its purpose. Uses original agent description if not set.
+    """
+
+    url: str | None = None  # type: ignore[assignment]
+    """
+    The preferred endpoint URL for interacting with the agent.
+    This URL MUST support the transport specified by 'preferredTransport'.
+    Uses original A2aAgentServer url if not set.
+    """
+
+    version: str = "0.1.0"
+    """
+    The agent's own version number. The format is defined by the provider.
+    """
+
+    default_input_modes: list[str] = Field(default_factory=lambda: ["text"])
+    """
+    Default set of supported input MIME types for all skills, which can be
+    overridden on a per-skill basis.
+    """
+
+    default_output_modes: list[str] = Field(default_factory=lambda: ["text"])
+    """
+    Default set of supported output MIME types for all skills, which can be
+    overridden on a per-skill basis.
+    """
+
+    capabilities: AgentCapabilities = Field(default_factory=lambda: AgentCapabilities(streaming=True))
+    """
+    A declaration of optional capabilities supported by the agent.
+    """
+
+    skills: list[AgentSkill] = Field(default_factory=list)
+    """
+    The set of skills, or distinct capabilities, that the agent can perform.
+    """
+
+
+@export_module("autogen.a2a")
+class A2aAgentServer:
+    """A server wrapper for running an AG2 agent via the A2A protocol.
+
+    This class provides functionality to wrap an AG2 ConversableAgent into an A2A server
+    that can be used to interact with the agent through A2A requests.
+    """
+
+    def __init__(
+        self,
+        agent: "ConversableAgent",
+        *,
+        url: str | None = "http://localhost:8000",
+        agent_card: CardSettings | None = None,
+        card_modifier: Callable[["AgentCard"], "AgentCard"] | None = None,
+        extended_agent_card: CardSettings | None = None,
+        extended_card_modifier: Callable[["AgentCard", "ServerCallContext"], "AgentCard"] | None = None,
+    ) -> None:
+        """Initialize the A2aAgentServer.
+
+        Args:
+            agent: The Autogen ConversableAgent to serve.
+            url: The base URL for the A2A server.
+            agent_card: Configuration for the base agent card.
+            card_modifier: Function to modify the base agent card.
+            extended_agent_card: Configuration for the extended agent card.
+            extended_card_modifier: Function to modify the extended agent card.
+        """
+        self.agent = agent
+
+        if not agent_card:
+            agent_card = CardSettings()
+
+        if agent_card.url and url != "http://localhost:8000":
+            warnings.warn(
+                (
+                    "You can't use `agent_card.url` and `url` options in the same time. "
+                    f"`agent_card.url` has a higher priority, so `{agent_card.url}` will be used."
+                ),
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
+        self.card = AgentCard.model_validate({
+            # use agent options by default
+            "name": agent.name,
+            "description": agent.description,
+            "url": url,
+            "supports_authenticated_extended_card": extended_agent_card is not None,
+            # exclude name and description if not provided
+            **agent_card.model_dump(exclude_none=True),
+        })
+
+        self.extended_agent_card: AgentCard | None = None
+        if extended_agent_card:
+            if extended_agent_card.url and url != "http://localhost:8000":
+                warnings.warn(
+                    (
+                        "You can't use `extended_agent_card.url` and `url` options in the same time. "
+                        f"`agent_card.url` has a higher priority, so `{extended_agent_card.url}` will be used."
+                    ),
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+
+            self.extended_agent_card = AgentCard.model_validate({
+                "name": agent.name,
+                "description": agent.description,
+                "url": url,
+                **extended_agent_card.model_dump(exclude_none=True),
+            })
+
+        self.card_modifier = card_modifier
+        self.extended_card_modifier = extended_card_modifier
+
+    @property
+    def executor(self) -> AutogenAgentExecutor:
+        """Get the A2A agent executor."""
+        return AutogenAgentExecutor(self.agent)
+
+    def build_request_handler(
+        self,
+        *,
+        task_store: "TaskStore | None" = None,
+        queue_manager: "QueueManager | None" = None,
+        push_config_store: "PushNotificationConfigStore | None" = None,
+        push_sender: "PushNotificationSender | None" = None,
+        request_context_builder: "RequestContextBuilder | None" = None,
+    ) -> "RequestHandler":
+        """Build a request handler for A2A application.
+
+        Args:
+            task_store: The task store to use.
+            queue_manager: The queue manager to use.
+            push_config_store: The push notification config store to use.
+            push_sender: The push notification sender to use.
+            request_context_builder: The request context builder to use.
+
+        Returns:
+            A configured RequestHandler instance.
+        """
+        return DefaultRequestHandler(
+            agent_executor=self.executor,
+            task_store=task_store or InMemoryTaskStore(),
+            queue_manager=queue_manager,
+            push_config_store=push_config_store,
+            push_sender=push_sender,
+            request_context_builder=request_context_builder,
+        )
+
+    def build_starlette_app(
+        self,
+        *,
+        request_handler: "RequestHandler | None" = None,
+        context_builder: "CallContextBuilder | None" = None,
+    ) -> "Starlette":
+        """Build a Starlette A2A application for ASGI server.
+
+        Args:
+            request_handler: The request handler to use.
+            context_builder: The context builder to use.
+
+        Returns:
+            A configured Starlette application instance.
+        """
+        from a2a.server.apps import A2AStarletteApplication
+
+        return A2AStarletteApplication(
+            agent_card=self.card,
+            extended_agent_card=self.extended_agent_card,
+            http_handler=request_handler
+            or DefaultRequestHandler(
+                agent_executor=self.executor,
+                task_store=InMemoryTaskStore(),
+            ),
+            context_builder=context_builder,
+            card_modifier=self.card_modifier,
+            extended_card_modifier=self.extended_card_modifier,
+        ).build()
+
+    build = build_starlette_app  # default alias for build_starlette_app