feat: more generic url

Author: racinmat

contributing/samples/a2a_auth/README.md

@@ -185,15 +185,16 @@ When deploying the remote BigQuery A2A agent to different environments (e.g., Cl
 }
 ```
 
-**Important:** The `url` field in `remote_a2a/bigquery_agent/agent.json` must point to the actual RPC endpoint where your remote BigQuery A2A agent is deployed and accessible.
+**Important:** The `url` field in `remote_a2a/bigquery_agent/agent.json` must point to the actual RPC endpoint where your remote BigQuery A2A agent is deployed and accessible. 
+If the `url` field is an empty string, it will be automatically filled by the `--host` and `--port`, or `--base_url` provided to `adk api_server`.
 
 ## Troubleshooting
 
 **Connection Issues:**
 - Ensure the local ADK web server is running on port 8000
 - Ensure the remote A2A server is running on port 8001
 - Check that no firewall is blocking localhost connections
-- **Verify the `url` field in `remote_a2a/bigquery_agent/agent.json` matches the actual deployed location of your remote A2A server**
+- **Verify the `url` field in `remote_a2a/bigquery_agent/agent.json` matches the actual deployed location of your remote A2A server, or if it's empty, make sure the `--host` and `--port`, or `--base_url` provided to `adk api_server` match the actual deployed location of your remote A2A server**
 - Verify the agent card URL passed to RemoteA2AAgent constructor matches the running A2A server
 
 

contributing/samples/a2a_basic/README.md

@@ -136,14 +136,15 @@ When deploying the remote A2A agent to different environments (e.g., Cloud Run,
 ```
 
 **Important:** The `url` field in `remote_a2a/check_prime_agent/agent.json` must point to the actual RPC endpoint where your remote A2A agent is deployed and accessible.
+If the `url` field is an empty string, it will be automatically filled by the `--host` and `--port`, or `--base_url` provided to `adk api_server`.
 
 ## Troubleshooting
 
 **Connection Issues:**
 - Ensure the local ADK web server is running on port 8000
 - Ensure the remote A2A server is running on port 8001
 - Check that no firewall is blocking localhost connections
-- **Verify the `url` field in `remote_a2a/check_prime_agent/agent.json` matches the actual deployed location of your remote A2A server**
+- **Verify the `url` field in `remote_a2a/check_prime_agent/agent.json` matches the actual deployed location of your remote A2A server, or if it's empty, make sure the `--host` and `--port`, or `--base_url` provided to `adk api_server` match the actual deployed location of your remote A2A server**
 - Verify the agent card URL passed to RemoteA2AAgent constructor matches the running A2A server
 
 

contributing/samples/a2a_human_in_loop/README.md

@@ -145,14 +145,15 @@ When deploying the remote approval A2A agent to different environments (e.g., Cl
 ```
 
 **Important:** The `url` field in `remote_a2a/human_in_loop/agent.json` must point to the actual RPC endpoint where your remote approval A2A agent is deployed and accessible.
+If the `url` field is an empty string, it will be automatically filled by the `--host` and `--port`, or `--base_url` provided to `adk api_server`.
 
 ## Troubleshooting
 
 **Connection Issues:**
 - Ensure the local ADK web server is running on port 8000
 - Ensure the remote A2A server is running on port 8001
 - Check that no firewall is blocking localhost connections
-- **Verify the `url` field in `remote_a2a/human_in_loop/agent.json` matches the actual deployed location of your remote A2A server**
+- **Verify the `url` field in `remote_a2a/human_in_loop/agent.json` matches the actual deployed location of your remote A2A server, or if it's empty, make sure the `--host` and `--port`, or `--base_url` provided to `adk api_server` match the actual deployed location of your remote A2A server**
 - Verify the agent card URL passed to RemoteA2AAgent constructor matches the running A2A server
 
 **Agent Not Responding:**

contributing/samples/a2a_root/remote_a2a/hello_world/agent.py

@@ -108,4 +108,4 @@ async def check_prime(nums: list[int]) -> str:
     ),
 )
 
-a2a_app = to_a2a(root_agent, port=8001)
+a2a_app = to_a2a(root_agent, base_url='http://localhost:8001/')

src/google/adk/a2a/utils/agent_to_a2a.py

@@ -47,17 +47,13 @@
 def to_a2a(
     agent: BaseAgent,
     *,
-    host: str = "localhost",
-    port: int = 8000,
-    protocol: str = "http",
+    base_url: str = "http://localhost:8000/",
 ) -> Starlette:
   """Convert an ADK agent to a A2A Starlette application.
 
   Args:
       agent: The ADK agent to convert
-      host: The host for the A2A RPC URL (default: "localhost")
-      port: The port for the A2A RPC URL (default: 8000)
-      protocol: The protocol for the A2A RPC URL (default: "http")
+      base_url: The base URL for the A2A RPC URL (default: "http://localhost:8000/")
 
   Returns:
       A Starlette application that can be run with uvicorn
@@ -94,10 +90,9 @@ async def create_runner() -> Runner:
   )
 
   # Build agent card
-  rpc_url = f"{protocol}://{host}:{port}/"
   card_builder = AgentCardBuilder(
       agent=agent,
-      rpc_url=rpc_url,
+      rpc_url=base_url,
   )
 
   # Create a Starlette app that will be configured during startup

src/google/adk/cli/cli_tools_click.py

@@ -23,6 +23,7 @@
 import os
 import tempfile
 from typing import Optional
+from urllib.parse import urlparse
 
 import click
 from click.core import ParameterSource
@@ -628,6 +629,16 @@ def decorator(func):
         help="Optional. The port of the server",
         default=8000,
     )
+    @click.option(
+        "--base_url",
+        type=str,
+        help=(
+            "Optional. The base URL of the server. "
+            "Mutually exclusive with --host and --port. "
+            "Overrides the values of --host and --port if specified."
+        ),
+        show_default=True,
+    )
     @click.option(
         "--allow_origins",
         help="Optional. Any additional origins to allow for CORS.",
@@ -721,6 +732,7 @@ def cli_web(
     allow_origins: Optional[list[str]] = None,
     host: str = "127.0.0.1",
     port: int = 8000,
+    base_url: Optional[str] = None,
     trace_to_cloud: bool = False,
     reload: bool = True,
     session_service_uri: Optional[str] = None,
@@ -741,6 +753,16 @@ def cli_web(
     adk web --session_service_uri=[uri] --port=[port] path/to/agents_dir
   """
   logs.setup_adk_logger(getattr(logging, log_level.upper()))
+  if base_url is None:
+    base_url = f"http://{host}:{port}"
+  else:
+    parsed_url = urlparse(base_url)
+    host = parsed_url.hostname
+    port = parsed_url.port
+    logging.debug(
+        f"Ignoring --host and --port parameters, because --base-url is"
+        f" specified."
+    )
 
   @asynccontextmanager
   async def _lifespan(app: FastAPI):
@@ -749,7 +771,7 @@ async def _lifespan(app: FastAPI):
 +-----------------------------------------------------------------------------+
 | ADK Web Server started                                                      |
 |                                                                             |
-| For local testing, access at http://{host}:{port}.{" "*(29 - len(str(port)))}|
+| For local testing, access at {base_url}.{" "*(29 - len(str(port)))}|
 +-----------------------------------------------------------------------------+
 """,
         fg="green",
@@ -777,8 +799,7 @@ async def _lifespan(app: FastAPI):
       trace_to_cloud=trace_to_cloud,
       lifespan=_lifespan,
       a2a=a2a,
-      host=host,
-      port=port,
+      base_url=base_url,
       reload_agents=reload_agents,
   )
   config = uvicorn.Config(
@@ -812,6 +833,7 @@ def cli_api_server(
     allow_origins: Optional[list[str]] = None,
     host: str = "127.0.0.1",
     port: int = 8000,
+    base_url: Optional[str] = None,
     trace_to_cloud: bool = False,
     reload: bool = True,
     session_service_uri: Optional[str] = None,
@@ -833,6 +855,16 @@ def cli_api_server(
   """
   logs.setup_adk_logger(getattr(logging, log_level.upper()))
 
+  if base_url is None:
+    base_url = f"http://{host}:{port}"
+  else:
+    parsed_url = urlparse(base_url)
+    host = parsed_url.hostname
+    port = parsed_url.port
+    logging.debug(
+        f"Ignoring --host and --port parameters, because --base-url is"
+        f" specified."
+    )
   session_service_uri = session_service_uri or session_db_url
   artifact_service_uri = artifact_service_uri or artifact_storage_uri
   config = uvicorn.Config(
@@ -846,8 +878,7 @@ def cli_api_server(
           web=False,
           trace_to_cloud=trace_to_cloud,
           a2a=a2a,
-          host=host,
-          port=port,
+          base_url=base_url,
           reload_agents=reload_agents,
       ),
       host=host,

src/google/adk/cli/fast_api.py

@@ -64,8 +64,7 @@ def get_fast_api_app(
     allow_origins: Optional[list[str]] = None,
     web: bool,
     a2a: bool = False,
-    host: str = "127.0.0.1",
-    port: int = 8000,
+    base_url: str = "http://127.0.0.1:8000",
     trace_to_cloud: bool = False,
     reload_agents: bool = False,
     lifespan: Optional[Lifespan[FastAPI]] = None,
@@ -352,6 +351,8 @@ async def _get_a2a_runner_async() -> Runner:
         logger.info("Setting up A2A agent: %s", app_name)
 
         try:
+          a2a_rpc_path = f"{base_url}/a2a/{app_name}"
+
           agent_executor = A2aAgentExecutor(
               runner=create_a2a_runner_loader(app_name),
           )
@@ -363,6 +364,10 @@ async def _get_a2a_runner_async() -> Runner:
           with (p / "agent.json").open("r", encoding="utf-8") as f:
             data = json.load(f)
             agent_card = AgentCard(**data)
+            if (
+                agent_card.url == ""
+            ):  # empty url is a placeholder to be filled with the provided url
+              agent_card.url = a2a_rpc_path
 
           a2a_app = A2AStarletteApplication(
               agent_card=agent_card,

tests/unittests/a2a/utils/test_agent_to_a2a.py

@@ -145,9 +145,7 @@ def test_to_a2a_custom_host_port_protocol(
     mock_card_builder_class.return_value = mock_card_builder
 
     # Act
-    result = to_a2a(
-        self.mock_agent, host="example.com", port=9000, protocol="https"
-    )
+    result = to_a2a(self.mock_agent, base_url="https://example.com:9000")
 
     # Assert
     assert result == mock_app
@@ -524,7 +522,7 @@ def test_to_a2a_with_custom_port_zero(
     mock_card_builder_class.return_value = mock_card_builder
 
     # Act
-    result = to_a2a(self.mock_agent, port=0)
+    result = to_a2a(self.mock_agent, base_url="http://localhost:0/")
 
     # Assert
     assert result == mock_app
@@ -559,7 +557,7 @@ def test_to_a2a_with_empty_string_host(
     mock_card_builder_class.return_value = mock_card_builder
 
     # Act
-    result = to_a2a(self.mock_agent, host="")
+    result = to_a2a(self.mock_agent, base_url="http://:8000/")
 
     # Assert
     assert result == mock_app
@@ -594,7 +592,7 @@ def test_to_a2a_with_negative_port(
     mock_card_builder_class.return_value = mock_card_builder
 
     # Act
-    result = to_a2a(self.mock_agent, port=-1)
+    result = to_a2a(self.mock_agent, base_url="http://localhost:-1/")
 
     # Assert
     assert result == mock_app
@@ -664,7 +662,9 @@ def test_to_a2a_with_special_characters_in_host(
     mock_card_builder_class.return_value = mock_card_builder
 
     # Act
-    result = to_a2a(self.mock_agent, host="test-host.example.com")
+    result = to_a2a(
+        self.mock_agent, base_url="http://test-host.example.com:8000/"
+    )
 
     # Assert
     assert result == mock_app
@@ -699,7 +699,7 @@ def test_to_a2a_with_ip_address_host(
     mock_card_builder_class.return_value = mock_card_builder
 
     # Act
-    result = to_a2a(self.mock_agent, host="192.168.1.1")
+    result = to_a2a(self.mock_agent, base_url="http://192.168.1.1:8000/")
 
     # Assert
     assert result == mock_app
@@ -734,7 +734,7 @@ def test_to_a2a_with_https_protocol(
     mock_card_builder_class.return_value = mock_card_builder
 
     # Act
-    result = to_a2a(self.mock_agent, protocol="https")
+    result = to_a2a(self.mock_agent, base_url="https://localhost:8000/")
 
     # Assert
     assert result == mock_app
@@ -769,7 +769,7 @@ def test_to_a2a_with_custom_protocol(
     mock_card_builder_class.return_value = mock_card_builder
 
     # Act
-    result = to_a2a(self.mock_agent, protocol="ws")
+    result = to_a2a(self.mock_agent, base_url="ws://localhost:8000/")
 
     # Assert
     assert result == mock_app
@@ -804,9 +804,7 @@ def test_to_a2a_with_all_custom_parameters(
     mock_card_builder_class.return_value = mock_card_builder
 
     # Act
-    result = to_a2a(
-        self.mock_agent, host="api.example.com", port=443, protocol="https"
-    )
+    result = to_a2a(self.mock_agent, base_url="https://api.example.com")
 
     # Assert
     assert result == mock_app