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

[sarojrout]

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

• Closes: Bug: Unable to create session for Agent Engine deployment when deploying with event compaction/context caching #3715
• Related: Bug: Unable to create session for Agent Engine deployment when deploying with event compaction/context caching #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:

• I have added or updated unit tests for my change.
• 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:

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:

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:

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:

1. Accept App objects from AdkApp(app=my_app, ...)
2. 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,
       ...
   )

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

[gemini-code-assist]

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.

Footnotes

1. 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.

[ryanaiagent]

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]

Hi @wyf7107 , can you please review this.