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

sarojrout · 2025-11-27T20:11:05Z

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 before creating a pull request.

Link to Issue or Description of Change

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

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:

App.name is validated as a simple Python identifier (e.g., "my_agent_name") via validate_app_name()
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
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:

I have added or updated unit tests for my change.
All unit tests pass locally.

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)
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:

Create an agent with event compaction and context caching:

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(),
)

Create a Runner with app and override app_name:

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

Verify session creation uses the overridden name:

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

I have read the CONTRIBUTING.md document.
I have performed a self-review of my own code.
I have commented my code, particularly in hard-to-understand areas.
I have added tests that prove my fix is effective or that my feature works.
New and existing unit tests pass locally with my changes.
I have manually tested my changes end-to-end.
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:

Accept App objects from AdkApp(app=my_app, ...)

Create Runner with both app and app_name (resource name):

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,
    ...
)

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

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 google#3715

gemini-code-assist · 2025-11-27T20:11:29Z

Summary of Changes

Hello @sarojrout, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a critical limitation in the Runner class that prevented App objects with advanced configurations (such as event compaction and context caching) from being seamlessly deployed to environments like Agent Engine, which require specific resource names that may not match the App's internal identifier. By enabling the app_name parameter to override the App's name during Runner initialization, the change ensures compatibility with external systems while preserving all App-level configurations, thereby unlocking full functionality for these deployment scenarios.

Highlights

App Name Override: The Runner class now allows the app_name parameter to explicitly override the name attribute of an App object when both are provided during initialization. This is particularly useful for deployment scenarios like Agent Engine where a resource name might differ from the App's internal identifier.
Refined Validation Logic: The validation rules for Runner initialization have been updated. While app and agent still cannot be provided simultaneously, app_name can now be provided alongside an App object without raising a ValueError.
Documentation Updates: The docstrings for Runner.__init__ and the internal _validate_runner_params function have been clarified to reflect the new app_name override behavior and the updated parameter validation.
Enhanced Test Coverage: A new unit test (test_runner_init_allows_app_name_override_with_app) has been added to specifically verify the app_name override functionality. An existing test (test_runner_init_raises_error_with_app_and_agent) was also modified to align with the revised validation rules.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a useful enhancement to the Runner class, allowing app_name to override app.name when both are provided. This change is well-motivated, particularly for Agent Engine deployment scenarios. The implementation is clean, and the new behavior is covered by a dedicated unit test. The documentation has also been updated to reflect this change. My review found one minor issue: the Raises section in the __init__ docstring is now incomplete as it omits the case where plugins are provided with an app, which still raises a ValueError. I've provided a suggestion to correct this. Overall, this is a good change that improves the flexibility of the Runner.

src/google/adk/runners.py

- Update Raises section in Runner.__init__ docstring to mention plugins validation error when app is provided - Add warning filters to new tests to suppress deprecation warnings from setup_method that uses deprecated plugins parameter

ryanaiagent · 2025-11-30T05:34:24Z

Hi @sarojrout , Thank you for your contribution! We appreciate you taking the time to submit this pull request. Your PR has been received by the team and is currently under review. We will provide feedback as soon as we have an update to share.

ryanaiagent · 2025-11-30T05:34:39Z

Hi @wyf7107 , can you please review this.

juszzz · 2025-12-10T20:08:51Z

@sarojrout this PR should also allow users to specify a ResumabilityConfig in the App configuration as well, correct? If so, I think this would potentially resolve #3290.

I was able to get tool confirmation working with a locally running adk web referencing a (remote) VertexAiSessionService instance, but deploying to Agent Engine with resumability enabled would similarly require configuring the App that is deployed (similar to event compaction and context caching configs), if I understand correctly.

sarojrout · 2025-12-15T21:49:56Z

@sarojrout this PR should also allow users to specify a ResumabilityConfig in the App configuration as well, correct? If so, I think this would potentially resolve #3290.

I was able to get tool confirmation working with a locally running adk web referencing a (remote) VertexAiSessionService instance, but deploying to Agent Engine with resumability enabled would similarly require configuring the App that is deployed (similar to event compaction and context caching configs), if I understand correctly.

Hi @juszzz,

Yes, exactly! The PR should support ResumabilityConfig the same way it supports EventsCompactionConfig and ContextCacheConfig. Since the PR preserves the entire App object (not just specific configs), any App-level configuration should work, including ResumabilityConfig.

This should indeed resolve #3290. The pattern is:

app = App(
    name="my_agent",
    root_agent=root_agent,
    resumability_config=ResumabilityConfig(...),  # Works with app_name override
)

runner = Runner(
    app=app,
    app_name="projects/.../reasoningEngines/...",  # Override for Agent Engine
)

If you've tested this and it works, that's great! If you encounter any issues specific to ResumabilityConfig, let me know and I can address them.

juszzz · 2025-12-22T18:59:17Z

@ankursharmas is there anyone else who could review this PR besides @yeesian? It's been open a month and is a barrier to getting access to three important features on Agent Engine (context caching, event compaction, and resumability).

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

adk-bot · 2026-01-09T21:35:23Z

Thank you @sarojrout for your contribution! 🎉

Your changes have been successfully imported and merged via Copybara in commit 86e7664.

Closing this PR as the changes are now in the main branch.

adk-bot added the core [Component] This issue is related to the core interface and implementation label Nov 27, 2025

gemini-code-assist bot reviewed Nov 27, 2025

View reviewed changes

src/google/adk/runners.py Outdated Show resolved Hide resolved

ryanaiagent self-assigned this Nov 30, 2025

ryanaiagent added the needs-review [Status] The PR is awaiting review from the maintainer label Nov 30, 2025

ankursharmas requested a review from yeesian December 2, 2025 00:46

sarojrout mentioned this pull request Dec 15, 2025

Tool Confirmation not working when persisting session with Vertexaisession Service #3290

Open

yeesian approved these changes Jan 8, 2026

View reviewed changes

yeesian and others added 2 commits January 9, 2026 11:05

Merge branch 'main' into feat/agent-engine-app-name-override

3df141e

Merge branch 'main' into feat/agent-engine-app-name-override

22d91d5

sasha-gitg approved these changes Jan 9, 2026

View reviewed changes

sasha-gitg added the ready to pull [Status] This PR is ready to be importing back to Google label Jan 9, 2026

adk-bot closed this Jan 9, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

sarojrout commented Nov 27, 2025

Uh oh!

gemini-code-assist bot commented Nov 27, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

ryanaiagent commented Nov 30, 2025

Uh oh!

ryanaiagent commented Nov 30, 2025

Uh oh!

juszzz commented Dec 10, 2025

Uh oh!

sarojrout commented Dec 15, 2025

Uh oh!

juszzz commented Dec 22, 2025

Uh oh!

adk-bot commented Jan 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

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

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

Conversation

sarojrout commented Nov 27, 2025

Link to Issue or Description of Change

Testing Plan

Checklist

Additional context

Uh oh!

gemini-code-assist bot commented Nov 27, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

ryanaiagent commented Nov 30, 2025

Uh oh!

ryanaiagent commented Nov 30, 2025

Uh oh!

juszzz commented Dec 10, 2025

Uh oh!

sarojrout commented Dec 15, 2025

Uh oh!

juszzz commented Dec 22, 2025

Uh oh!

adk-bot commented Jan 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants