saroj rout
86e7664006
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
Agent Development Kit (ADK)
An open-source, code-first Python framework for building, evaluating, and deploying sophisticated AI agents with flexibility and control.
Important Links: Docs, Samples, Java ADK, Go ADK & ADK Web.
</html>Agent Development Kit (ADK) is a flexible and modular framework that applies software development principles to AI agent creation. It is designed to simplify building, deploying, and orchestrating agent workflows, from simple tasks to complex systems. While optimized for Gemini, ADK is model-agnostic, deployment-agnostic, and compatible with other frameworks.
π₯ What's new
-
Custom Service Registration: Add a service registry to provide a generic way to register custom service implementations to be used in FastAPI server. See short instruction. (391628f)
-
Rewind: Add the ability to rewind a session to before a previous invocation (9dce06f).
-
New CodeExecutor: Introduces a new AgentEngineSandboxCodeExecutor class that supports executing agent-generated code using the Vertex AI Code Execution Sandbox API (ee39a89)
β¨ Key Features
-
Rich Tool Ecosystem: Utilize pre-built tools, custom functions, OpenAPI specs, MCP tools or integrate existing tools to give agents diverse capabilities, all for tight integration with the Google ecosystem.
-
Code-First Development: Define agent logic, tools, and orchestration directly in Python for ultimate flexibility, testability, and versioning.
-
Agent Config: Build agents without code. Check out the Agent Config feature.
-
Tool Confirmation: A tool confirmation flow(HITL) that can guard tool execution with explicit confirmation and custom input.
-
Modular Multi-Agent Systems: Design scalable applications by composing multiple specialized agents into flexible hierarchies.
-
Deploy Anywhere: Easily containerize and deploy agents on Cloud Run or scale seamlessly with Vertex AI Agent Engine.
π Installation
Stable Release (Recommended)
You can install the latest stable version of ADK using pip:
pip install google-adk
The release cadence is roughly bi-weekly.
This version is recommended for most users as it represents the most recent official release.
Development Version
Bug fixes and new features are merged into the main branch on GitHub first. If you need access to changes that haven't been included in an official PyPI release yet, you can install directly from the main branch:
pip install git+https://github.com/google/adk-python.git@main
Note: The development version is built directly from the latest code commits. While it includes the newest fixes and features, it may also contain experimental changes or bugs not present in the stable release. Use it primarily for testing upcoming changes or accessing critical fixes before they are officially released.
π€ Agent2Agent (A2A) Protocol and ADK Integration
For remote agent-to-agent communication, ADK integrates with the A2A protocol. See this example for how they can work together.
π Documentation
Explore the full documentation for detailed guides on building, evaluating, and deploying agents:
π Feature Highlight
Define a single agent:
from google.adk.agents import Agent
from google.adk.tools import google_search
root_agent = Agent(
name="search_assistant",
model="gemini-2.5-flash", # Or your preferred Gemini model
instruction="You are a helpful assistant. Answer user questions using Google Search when needed.",
description="An assistant that can search the web.",
tools=[google_search]
)
Define a multi-agent system:
Define a multi-agent system with coordinator agent, greeter agent, and task execution agent. Then ADK engine and the model will guide the agents works together to accomplish the task.
from google.adk.agents import LlmAgent, BaseAgent
# Define individual agents
greeter = LlmAgent(name="greeter", model="gemini-2.5-flash", ...)
task_executor = LlmAgent(name="task_executor", model="gemini-2.5-flash", ...)
# Create parent agent and assign children via sub_agents
coordinator = LlmAgent(
name="Coordinator",
model="gemini-2.5-flash",
description="I coordinate greetings and tasks.",
sub_agents=[ # Assign sub_agents here
greeter,
task_executor
]
)
Development UI
A built-in development UI to help you test, evaluate, debug, and showcase your agent(s).
Evaluate Agents
adk eval \
samples_for_testing/hello_world \
samples_for_testing/hello_world/hello_world_eval_set_001.evalset.json
π€ Contributing
We welcome contributions from the community! Whether it's bug reports, feature requests, documentation improvements, or code contributions, please see our
- General contribution guideline and flow.
- Then if you want to contribute code, please read Code Contributing Guidelines to get started.
Community Repo
We have adk-python-community repo that is home to a growing ecosystem of community-contributed tools, third-party service integrations, and deployment scripts that extend the core capabilities of the ADK.
Vibe Coding
If you want to develop agent via vibe coding the llms.txt and the llms-full.txt can be used as context to LLM. While the former one is a summarized one and the later one has the full information in case your LLM has big enough context window.
Community Events
- [Completed] ADK's 1st community meeting on Wednesday, October 15, 2025. Remember to join our group to get access to the recording, and deck.
π License
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
Happy Agent Building!