[Fix] A2a Agent Gateway Fixes - A2A agents deployed with localhost/internal URLs in their agent cards (e.g., http://0.0.0.0:8001/)

.circleci/config.yml

@@ -1372,6 +1372,51 @@ jobs:
           paths:
             - mcp_coverage.xml
             - mcp_coverage
+  agent_testing:
+    docker:
+      - image: cimg/python:3.11
+        auth:
+          username: ${DOCKERHUB_USERNAME}
+          password: ${DOCKERHUB_PASSWORD}
+    working_directory: ~/project
+
+    steps:
+      - checkout
+      - setup_google_dns
+      - run:
+          name: Install Dependencies
+          command: |
+            python -m pip install --upgrade pip
+            python -m pip install -r requirements.txt
+            pip install "pytest==7.3.1"
+            pip install "pytest-retry==1.6.3"
+            pip install "pytest-cov==5.0.0"
+            pip install "pytest-asyncio==0.21.1"
+            pip install "respx==0.22.0"
+            pip install "pydantic==2.11.0"
+            pip install "a2a-sdk"
+      # Run pytest and generate JUnit XML report
+      - run:
+          name: Run tests
+          command: |
+            pwd
+            ls
+            python -m pytest -vv tests/agent_tests --ignore=tests/agent_tests/local_only_agent_tests --cov=litellm --cov-report=xml -x -s -v --junitxml=test-results/junit.xml --durations=5
+          no_output_timeout: 120m
+      - run:
+          name: Rename the coverage files
+          command: |
+            mv coverage.xml agent_coverage.xml
+            mv .coverage agent_coverage
+
+      # Store test results
+      - store_test_results:
+          path: test-results
+      - persist_to_workspace:
+          root: .
+          paths:
+            - agent_coverage.xml
+            - agent_coverage
   guardrails_testing:
     docker:
       - image: cimg/python:3.11
@@ -4264,6 +4309,12 @@ workflows:
               only:
                 - main
                 - /litellm_.*/
+      - agent_testing:
+          filters:
+            branches:
+              only:
+                - main
+                - /litellm_.*/
       - guardrails_testing:
           filters:
             branches:
@@ -4371,6 +4422,7 @@ workflows:
             - llm_translation_testing
             - realtime_translation_testing
             - mcp_testing
+            - agent_testing
             - google_generate_content_endpoint_testing
             - guardrails_testing
             - llm_responses_api_testing
@@ -4449,6 +4501,7 @@ workflows:
             - llm_translation_testing
             - realtime_translation_testing
             - mcp_testing
+            - agent_testing
             - google_generate_content_endpoint_testing
             - llm_responses_api_testing
             - ocr_testing

litellm/a2a_protocol/__init__.py

@@ -39,6 +39,12 @@
 """
 
 from litellm.a2a_protocol.client import A2AClient
+from litellm.a2a_protocol.exceptions import (
+    A2AAgentCardError,
+    A2AConnectionError,
+    A2AError,
+    A2ALocalhostURLError,
+)
 from litellm.a2a_protocol.main import (
     aget_agent_card,
     asend_message,
@@ -49,11 +55,19 @@
 from litellm.types.agents import LiteLLMSendMessageResponse
 
 __all__ = [
+    # Client
     "A2AClient",
+    # Functions
     "asend_message",
     "send_message",
     "asend_message_streaming",
     "aget_agent_card",
     "create_a2a_client",
+    # Response types
     "LiteLLMSendMessageResponse",
+    # Exceptions
+    "A2AError",
+    "A2AConnectionError",
+    "A2AAgentCardError",
+    "A2ALocalhostURLError",
 ]

litellm/a2a_protocol/card_resolver.py

@@ -7,6 +7,7 @@
 from typing import TYPE_CHECKING, Any, Dict, Optional
 
 from litellm._logging import verbose_logger
+from litellm.constants import LOCALHOST_URL_PATTERNS
 
 if TYPE_CHECKING:
     from a2a.types import AgentCard
@@ -26,33 +27,79 @@
     pass
 
 
+def is_localhost_or_internal_url(url: Optional[str]) -> bool:
+    """
+    Check if a URL is a localhost or internal URL.
+
+    This detects common development URLs that are accidentally left in
+    agent cards when deploying to production.
+
+    Args:
+        url: The URL to check
+
+    Returns:
+        True if the URL is localhost/internal
+    """
+    if not url:
+        return False
+
+    url_lower = url.lower()
+
+    return any(pattern in url_lower for pattern in LOCALHOST_URL_PATTERNS)
+
+
+def fix_agent_card_url(agent_card: "AgentCard", base_url: str) -> "AgentCard":
+    """
+    Fix the agent card URL if it contains a localhost/internal address.
+
+    Many A2A agents are deployed with agent cards that contain internal URLs
+    like "http://0.0.0.0:8001/" or "http://localhost:8000/". This function
+    replaces such URLs with the provided base_url.
+
+    Args:
+        agent_card: The agent card to fix
+        base_url: The base URL to use as replacement
+
+    Returns:
+        The agent card with the URL fixed if necessary
+    """
+    card_url = getattr(agent_card, "url", None)
+
+    if card_url and is_localhost_or_internal_url(card_url):
+        # Normalize base_url to ensure it ends with /
+        fixed_url = base_url.rstrip("/") + "/"
+        agent_card.url = fixed_url
+
+    return agent_card
+
+
 class LiteLLMA2ACardResolver(_A2ACardResolver):  # type: ignore[misc]
     """
     Custom A2A card resolver that supports multiple well-known paths.
-    
+
     Extends the base A2ACardResolver to try both:
     - /.well-known/agent-card.json (standard)
     - /.well-known/agent.json (previous/alternative)
     """
-    
+
     async def get_agent_card(
         self,
         relative_card_path: Optional[str] = None,
         http_kwargs: Optional[Dict[str, Any]] = None,
     ) -> "AgentCard":
         """
         Fetch the agent card, trying multiple well-known paths.
-        
+
         First tries the standard path, then falls back to the previous path.
-        
+
         Args:
             relative_card_path: Optional path to the agent card endpoint.
                 If None, tries both well-known paths.
             http_kwargs: Optional dictionary of keyword arguments to pass to httpx.get
-            
+
         Returns:
             AgentCard from the A2A agent
-            
+
         Raises:
             A2AClientHTTPError or A2AClientJSONError if both paths fail
         """
@@ -62,13 +109,13 @@ async def get_agent_card(
                 relative_card_path=relative_card_path,
                 http_kwargs=http_kwargs,
             )
-        
+
         # Try both well-known paths
         paths = [
             AGENT_CARD_WELL_KNOWN_PATH,
             PREV_AGENT_CARD_WELL_KNOWN_PATH,
         ]
-        
+
         last_error = None
         for path in paths:
             try:
@@ -85,11 +132,11 @@ async def get_agent_card(
                 )
                 last_error = e
                 continue
-        
+
         # If we get here, all paths failed - re-raise the last error
         if last_error is not None:
             raise last_error
-        
+
         # This shouldn't happen, but just in case
         raise Exception(
             f"Failed to fetch agent card from {self.base_url}. "