feat(runners): Allow app_name to override app.name when both provided

src/google/adk/runners.py

@@ -121,15 +121,21 @@ def __init__(
     """Initializes the Runner.
 
     Developers should provide either an `app` instance or both `app_name` and
-    `agent`. Providing a mix of `app` and `app_name`/`agent` will result in a
-    `ValueError`. Providing `app` is the recommended way to create a runner.
+    `agent`. When `app` is provided, `app_name` can optionally override the
+    app's name (useful for deployment scenarios like Agent Engine where the
+    resource name differs from the app's identifier). However, `agent` should
+    not be provided when `app` is provided. Providing `app` is the recommended
+    way to create a runner.
 
     Args:
-        app: An optional `App` instance. If provided, `app_name` and `agent`
-          should not be specified.
+        app: An optional `App` instance. If provided, `agent` should not be
+          specified. `app_name` can optionally override `app.name`.
         app_name: The application name of the runner. Required if `app` is not
-          provided.
-        agent: The root agent to run. Required if `app` is not provided.
+          provided. If `app` is provided, this can optionally override `app.name`
+          (e.g., for deployment scenarios where a resource name differs from the
+          app identifier).
+        agent: The root agent to run. Required if `app` is not provided. Should
+          not be provided when `app` is provided.
         plugins: Deprecated. A list of plugins for the runner. Please use the
           `app` argument to provide plugins instead.
         artifact_service: The artifact service for the runner.
@@ -139,8 +145,8 @@ def __init__(
         plugin_close_timeout: The timeout in seconds for plugin close methods.
 
     Raises:
-        ValueError: If `app` is provided along with `app_name` or `plugins`, or
-          if `app` is not provided but either `app_name` or `agent` is missing.
+        ValueError: If `app` is provided along with `agent` or `plugins`, or if
+          `app` is not provided but either `app_name` or `agent` is missing.
     """
     self.app = app
     (
@@ -181,7 +187,8 @@ def _validate_runner_params(
 
     Args:
         app: An optional `App` instance.
-        app_name: The application name of the runner.
+        app_name: The application name of the runner. Can override app.name when
+          app is provided.
         agent: The root agent to run.
         plugins: A list of plugins for the runner.
 
@@ -193,18 +200,16 @@ def _validate_runner_params(
         ValueError: If parameters are invalid.
     """
     if app:
-      if app_name:
-        raise ValueError(
-            'When app is provided, app_name should not be provided.'
-        )
       if agent:
         raise ValueError('When app is provided, agent should not be provided.')
       if plugins:
         raise ValueError(
             'When app is provided, plugins should not be provided and should be'
             ' provided in the app instead.'
         )
-      app_name = app.name
+      # Allow app_name to override app.name (useful for deployment scenarios
+      # like Agent Engine where resource names differ from app identifiers)
+      app_name = app_name or app.name
       agent = app.root_agent
       plugins = app.plugins
       context_cache_config = app.context_cache_config

tests/unittests/test_runners.py

@@ -586,20 +586,38 @@ async def test_runner_passes_plugin_close_timeout(self):
     )
     assert runner.plugin_manager._close_timeout == 10.0
 
-  def test_runner_init_raises_error_with_app_and_app_name_and_agent(self):
-    """Test that ValueError is raised when app, app_name and agent are provided."""
+  @pytest.mark.filterwarnings(
+      "ignore:The `plugins` argument is deprecated:DeprecationWarning"
+  )
+  def test_runner_init_raises_error_with_app_and_agent(self):
+    """Test that ValueError is raised when app and agent are provided."""
     with pytest.raises(
         ValueError,
-        match="When app is provided, app_name should not be provided.",
+        match="When app is provided, agent should not be provided.",
     ):
       Runner(
           app=App(name="test_app", root_agent=self.root_agent),
-          app_name="test_app",
           agent=self.root_agent,
           session_service=self.session_service,
           artifact_service=self.artifact_service,
       )
 
+  @pytest.mark.filterwarnings(
+      "ignore:The `plugins` argument is deprecated:DeprecationWarning"
+  )
+  def test_runner_init_allows_app_name_override_with_app(self):
+    """Test that app_name can override app.name when both are provided."""
+    app = App(name="test_app", root_agent=self.root_agent)
+    runner = Runner(
+        app=app,
+        app_name="override_name",
+        session_service=self.session_service,
+        artifact_service=self.artifact_service,
+    )
+    assert runner.app_name == "override_name"
+    assert runner.agent == self.root_agent
+    assert runner.app == app
+
   def test_runner_init_raises_error_without_app_and_app_name(self):
     """Test ValueError is raised when app is not provided and app_name is missing."""
     with pytest.raises(