adk-python

encounter/adk-python

Fork 0

mirror of https://github.com/encounter/adk-python.git synced 2026-07-09 18:19:28 -07:00

Commit Graph

Author	SHA1	Message	Date
sarojrout Copybara-Service George Weale	e0b9712a49	fix: Add endpoints to get/list artifact version metadata This change introduces new FastAPI endpoints in adk_web_server.py and corresponding client methods in adk_web_server_client.py to allow fetching metadata for artifact versions without downloading the artifact content Close #3710 Co-authored-by: George Weale <gweale@google.com> PiperOrigin-RevId: 868217569	2026-02-10 10:40:54 -08:00
saroj routandCopybara-Service	86e7664006	feat(runners): Allow app_name to override app.name when both provided 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	2026-01-09 13:35:11 -08:00
saroj routandCopybara-Service	2247a45922	feat(agents): add validation for unique sub-agent names (#3557 ) Merge https://github.com/google/adk-python/pull/3576 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: #3557 - Related: #_issue_number_ 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 creating a BaseAgent with multiple sub-agents, there was no validation to ensure that all sub-agents have unique names. This could lead to confusion when trying to find or reference specific sub-agents by name, as duplicate names would make it ambiguous which agent is being referenced. Solution: Added a @field_validator for the sub_agents field in BaseAgent that validates all sub-agents have unique names. The validator: Checks for duplicate names in the sub-agents list Raises a ValueError with a clear error message listing all duplicate names found Returns the validated list if all names are unique Handles edge cases like empty lists gracefully ### 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. _Please include a summary of passed `pytest` results._ Added 4 new test cases in tests/unittests/agents/test_base_agent.py: test_validate_sub_agents_unique_names_single_duplicate: Verifies that a single duplicate name raises ValueError test_validate_sub_agents_unique_names_multiple_duplicates: Verifies that multiple duplicate names are all reported in the error message test_validate_sub_agents_unique_names_no_duplicates: Verifies that unique names pass validation successfully test_validate_sub_agents_unique_names_empty_list: Verifies that empty sub-agents list passes validation All tests pass locally. You can run with: pytest tests/unittests/agents/test_base_agent.py::test_validate_sub_agents_unique_names_single_duplicate tests/unittests/agents/test_base_agent.py::test_validate_sub_agents_unique_names_multiple_duplicates tests/unittests/agents/test_base_agent.py::test_validate_sub_agents_unique_names_no_duplicates tests/unittests/agents/test_base_agent.py::test_validate_sub_agents_unique_names_empty_list -v Manual End-to-End (E2E) Tests: _Please provide instructions on how to manually test your changes, including any necessary setup or configuration. Please provide logs or screenshots to help reviewers better understand the fix._ Test Case 1: Duplicate names should raise error from google.adk.agents import Agent agent1 = Agent(name="sub_agent", model="gemini-2.5-flash") agent2 = Agent(name="sub_agent", model="gemini-2.5-flash") # Same name # This should raise ValueError try: parent = Agent( name="parent", model="gemini-2.5-flash", sub_agents=[agent1, agent2] ) except ValueError as e: print(f"Expected error: {e}") # Output: Found duplicate sub-agent names: `sub_agent`. All sub-agents must have unique names. Test Case 2: Unique names should work from google.adk.agents import Agent agent1 = Agent(name="agent1", model="gemini-2.5-flash") agent2 = Agent(name="agent2", model="gemini-2.5-flash") # This should work without error parent = Agent( name="parent", model="gemini-2.5-flash", sub_agents=[agent1, agent2] ) print("Success: Unique names validated correctly") ### 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 This change adds validation at the BaseAgent level, so it automatically applies to all agent types that inherit from BaseAgent (e.g., LlmAgent, LoopAgent, etc.). The validation uses Pydantic's field validator system, which runs during object initialization, ensuring the constraint is enforced early and consistently. The error message clearly identifies which names are duplicated, making it easy for developers to fix the issue: COPYBARA_INTEGRATE_REVIEW=https://github.com/google/adk-python/pull/3576 from sarojrout:feat/validate-unique-sub-agent-names 07adf1f9a5fc935389eb9dfa3cbc1311f551ebe3 PiperOrigin-RevId: 835358118	2025-11-21 14:24:07 -08:00

Author

SHA1

Message

Date

e0b9712a49

fix: Add endpoints to get/list artifact version metadata

This change introduces new FastAPI endpoints in adk_web_server.py and corresponding client methods in adk_web_server_client.py to allow fetching metadata for artifact versions without downloading the artifact content

Close #3710

Co-authored-by: George Weale <gweale@google.com>
PiperOrigin-RevId: 868217569

2026-02-10 10:40:54 -08:00

saroj routandCopybara-Service

86e7664006

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

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

2026-01-09 13:35:11 -08:00

saroj routandCopybara-Service

2247a45922

feat(agents): add validation for unique sub-agent names (#3557 )

Merge https://github.com/google/adk-python/pull/3576

**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: #3557
- Related: #_issue_number_

**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 creating a BaseAgent with multiple sub-agents, there was no validation to ensure that all sub-agents have unique names. This could lead to confusion when trying to find or reference specific sub-agents by name, as duplicate names would make it ambiguous which agent is being referenced.
**Solution:**
Added a @field_validator for the sub_agents field in BaseAgent that validates all sub-agents have unique names. The validator:
Checks for duplicate names in the sub-agents list
Raises a ValueError with a clear error message listing all duplicate names found
Returns the validated list if all names are unique
Handles edge cases like empty lists gracefully

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

_Please include a summary of passed `pytest` results._
Added 4 new test cases in tests/unittests/agents/test_base_agent.py:
test_validate_sub_agents_unique_names_single_duplicate: Verifies that a single duplicate name raises ValueError
test_validate_sub_agents_unique_names_multiple_duplicates: Verifies that multiple duplicate names are all reported in the error message
test_validate_sub_agents_unique_names_no_duplicates: Verifies that unique names pass validation successfully
test_validate_sub_agents_unique_names_empty_list: Verifies that empty sub-agents list passes validation
All tests pass locally. You can run with:
pytest tests/unittests/agents/test_base_agent.py::test_validate_sub_agents_unique_names_single_duplicate tests/unittests/agents/test_base_agent.py::test_validate_sub_agents_unique_names_multiple_duplicates tests/unittests/agents/test_base_agent.py::test_validate_sub_agents_unique_names_no_duplicates tests/unittests/agents/test_base_agent.py::test_validate_sub_agents_unique_names_empty_list -v
**Manual End-to-End (E2E) Tests:**

_Please provide instructions on how to manually test your changes, including any
necessary setup or configuration. Please provide logs or screenshots to help
reviewers better understand the fix._

Test Case 1: Duplicate names should raise error
from google.adk.agents import Agent

agent1 = Agent(name="sub_agent", model="gemini-2.5-flash")
agent2 = Agent(name="sub_agent", model="gemini-2.5-flash")  # Same name

# This should raise ValueError
try:
    parent = Agent(
        name="parent",
        model="gemini-2.5-flash",
        sub_agents=[agent1, agent2]
    )
except ValueError as e:
    print(f"Expected error: {e}")
    # Output: Found duplicate sub-agent names: `sub_agent`. All sub-agents must have unique names.

Test Case 2: Unique names should work
from google.adk.agents import Agent

agent1 = Agent(name="agent1", model="gemini-2.5-flash")
agent2 = Agent(name="agent2", model="gemini-2.5-flash")

# This should work without error
parent = Agent(
    name="parent",
    model="gemini-2.5-flash",
    sub_agents=[agent1, agent2]
)
print("Success: Unique names validated correctly")

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

This change adds validation at the BaseAgent level, so it automatically applies to all agent types that inherit from BaseAgent (e.g., LlmAgent, LoopAgent, etc.). The validation uses Pydantic's field validator system, which runs during object initialization, ensuring the constraint is enforced early and consistently.
The error message clearly identifies which names are duplicated, making it easy for developers to fix the issue:

COPYBARA_INTEGRATE_REVIEW=https://github.com/google/adk-python/pull/3576 from sarojrout:feat/validate-unique-sub-agent-names 07adf1f9a5fc935389eb9dfa3cbc1311f551ebe3
PiperOrigin-RevId: 835358118

2025-11-21 14:24:07 -08:00