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

Merge #3745

This change enables Agent Engine deployments to use App objects with event compaction and context caching configs while using the Agent Engine resource name for session operations, rather than App.name.

- Allow app_name parameter to override app.name when both are provided
- Still error when app and agent are both provided (prevents confusion)
- Updated tests to reflect new behavior and added test for override case
- Updateed documentation to clarify the new usage pattern

This fixes the issue where App.name (a simple identifier) conflicts with Agent Engine's requirement for resource names in session creation.

Related to issue #3715

**Please ensure you have read the [contribution guide](https://github.com/google/adk-python/blob/main/CONTRIBUTING.md) before creating a pull request.**

### Link to Issue or Description of Change

**1. Link to an existing issue (if applicable):**

- Closes: #3715
- Related: #3715

**2. Or, if no issue exists, describe the change:**

_If applicable, please follow the issue templates to provide as much detail as
possible._

**Problem:**
When deploying an agent to Agent Engine with event compaction and/or context caching enabled, users must wrap their agent in an `App` object to configure these features. However, when the `App` is passed to `AdkApp` and deployed, session creation fails because:
1. `App.name` is validated as a simple Python identifier (e.g., `"my_agent_name"`) via `validate_app_name()`
2. Agent Engine expects the app name to be either a full Reasoning Engine resource name (e.g., `"projects/123/locations/us-central1/reasoningEngines/456"`) or the reasoning engine ID
3. When an `App` object is passed to `AdkApp`, the deployment stores `App.name` (the simple identifier), but session creation later rejects it as invalid

This prevents users from deploying to Agent Engine with event compaction or context caching enabled.

**Solution:**
Allow the `app_name` parameter in `Runner.__init__()` to override `app.name` when both are provided. This enables Agent Engine (and other deployment scenarios) to:

- Pass the full `App` object to preserve event compaction and context caching configurations
- Override `app.name` with the Agent Engine resource name for session operations
- Successfully create sessions using the resource name while maintaining App-level features

The change is backward compatible: existing code that only provides `app` continues to use `app.name` as before. The override only applies when `app_name` is explicitly provided along with `app`.

### Testing Plan

_Please describe the tests that you ran to verify your changes. This is required
for all PRs that are not small documentation or typo fixes._

**Unit Tests:**

- [x] I have added or updated unit tests for my change.
- [x] All unit tests pass locally.

1. **Updated existing test** (`test_runner_init_raises_error_with_app_and_agent`):
   - Changed from testing `app` + `app_name` + `agent` error to testing only `app` + `agent` error
   - Verifies that `app` and `agent` cannot both be provided (prevents confusion)

2. **Added new test** (`test_runner_init_allows_app_name_override_with_app`):
   - Verifies that `app_name` can override `app.name` when both are provided
   - Confirms that `runner.app_name == "override_name"` while `runner.app` still references the original App object
   - Ensures all App configs (agent, plugins, context_cache_config, etc.) are preserved

```
pytest tests/unittests/test_runners.py::TestRunnerWithPlugins::test_runner_init_raises_error_with_app_and_agent -v
pytest tests/unittests/test_runners.py::TestRunnerWithPlugins::test_runner_init_allows_app_name_override_with_app -v
```
tests/unittests/test_runners.py::TestRunnerWithPlugins::test_runner_init_allows_app_name_override_with_app PASSED [100%]

tests/unittests/test_runners.py::TestRunnerWithPlugins::test_runner_init_raises_error_with_app_and_agent PASSED [100%]

**Manual End-to-End (E2E) Tests:**

1. Create an agent with event compaction and context caching:
```python
from google.adk import Agent
from google.adk.apps import App
from google.adk.apps import EventsCompactionConfig
from google.adk.agents import ContextCacheConfig

root_agent = Agent(
    name="my_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant.",
)

app = App(
    name="my_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=2,
        overlap_size=1,
    ),
    context_cache_config=ContextCacheConfig(),
)
```

2. Create a Runner with app and override app_name:
```python
from google.adk import Runner
from google.adk.sessions import InMemorySessionService
from google.adk.artifacts import InMemoryArtifactService

runner = Runner(
    app=app,
    app_name="projects/123/locations/us-central1/reasoningEngines/456",  # Resource name
    session_service=InMemorySessionService(),
    artifact_service=InMemoryArtifactService(),
)

# Verify app_name override worked
assert runner.app_name == "projects/123/locations/us-central1/reasoningEngines/456"
assert runner.app == app  # Original app object preserved
assert runner.context_cache_config is not None  # Config preserved
assert runner.app.events_compaction_config is not None  # Config preserved
```

3. Verify session creation uses the overridden name:
```python
session = await runner.session_service.create_session(
    app_name=runner.app_name,  # Uses resource name, not app.name
    user_id="test_user",
)
```

**Expected Results:**
- Runner creation succeeds with both `app` and `app_name` provided
- `runner.app_name` equals the provided `app_name` (not `app.name`)
- All App configurations (event compaction, context caching) are preserved
- Session creation uses the overridden `app_name`

### Checklist

- [x] I have read the [CONTRIBUTING.md](https://github.com/google/adk-python/blob/main/CONTRIBUTING.md) document.
- [x] I have performed a self-review of my own code.
- [x] I have commented my code, particularly in hard-to-understand areas.
- [x] I have added tests that prove my fix is effective or that my feature works.
- [x] New and existing unit tests pass locally with my changes.
- [x] I have manually tested my changes end-to-end.
- [x] Any dependent changes have been merged and published in downstream modules.

### Additional context

**Backward Compatibility:**
This change is fully backward compatible. All existing code patterns continue to work:

- `Runner(app=my_app)` → Still uses `app.name`
- `Runner(app_name="x", agent=my_agent)` → Still works
- `Runner(app=my_app, app_name=None)` → Still works (uses `app.name`)

**Impact on Agent Engine:**
This change enables Agent Engine deployments to support event compaction and context caching. Once this PR is merged, Agent Engine SDK should:

1. Accept `App` objects from `AdkApp(app=my_app, ...)`
2. Create `Runner` with both `app` and `app_name` (resource name):
   ```python
   runner = Runner(
       app=my_app,  # Preserves event_compaction_config and context_cache_config
       app_name=resource_name,  # Overrides app.name for session operations
       session_service=session_service,
       ...
   )
   ```
3. Event compaction and context caching will work automatically once the App is passed correctly.

**Related Documentation:**
- Event compaction is documented in `src/google/adk/apps/compaction.py`
- Context caching is documented in `src/google/adk/agents/context_cache_config.py`
- The Runner's App support is documented in `src/google/adk/runners.py`

COPYBARA_INTEGRATE_REVIEW=#3745 from sarojrout:feat/agent-engine-app-name-override 22d91d5
PiperOrigin-RevId: 854325898

Author: sarojrout

src/google/adk/runners.py

@@ -153,15 +153,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.
@@ -171,8 +177,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
     (
@@ -213,7 +219,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.
 
@@ -232,18 +239,16 @@ def _validate_runner_params(
       )
 
     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

@@ -648,20 +648,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(