From 86e76640066b4d7b844e3ddd1acccf0da1f2f47e Mon Sep 17 00:00:00 2001 From: saroj rout Date: Fri, 9 Jan 2026 13:34:39 -0800 Subject: [PATCH] feat(runners): Allow app_name to override app.name when both provided MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Merge https://github.com/google/adk-python/pull/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=https://github.com/google/adk-python/pull/3745 from sarojrout:feat/agent-engine-app-name-override 22d91d59df1460d25d06a71e155ad3dc20a69ca8 PiperOrigin-RevId: 854325898 --- src/google/adk/runners.py | 33 +++++++++++++++++++-------------- tests/unittests/test_runners.py | 26 ++++++++++++++++++++++---- 2 files changed, 41 insertions(+), 18 deletions(-) diff --git a/src/google/adk/runners.py b/src/google/adk/runners.py index 730216e0..cbf2c595 100644 --- a/src/google/adk/runners.py +++ b/src/google/adk/runners.py @@ -153,15 +153,21 @@ class Runner: """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 @@ class Runner: 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 @@ class Runner: 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,10 +239,6 @@ class Runner: ) 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: @@ -243,7 +246,9 @@ class Runner: '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 diff --git a/tests/unittests/test_runners.py b/tests/unittests/test_runners.py index c347a789..710ca90d 100644 --- a/tests/unittests/test_runners.py +++ b/tests/unittests/test_runners.py @@ -648,20 +648,38 @@ class TestRunnerWithPlugins: ) 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(