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

[sarojrout]

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: Add validation to BaseAgent to verify that all sub_agents have unique names #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:

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

• 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

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:

[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 potential ambiguity issue where BaseAgent instances could be initialized with sub-agents having non-unique names. By integrating a Pydantic field validator, the system now enforces uniqueness among sub-agent names during object creation. This enhancement improves data integrity, prevents confusion when referencing sub-agents, and provides immediate feedback to developers through descriptive error messages, ensuring a more robust and predictable agent hierarchy.

Highlights

• Sub-Agent Name Uniqueness: Introduced a Pydantic field validator to ensure all sub-agents within a BaseAgent have unique names, preventing ambiguity and potential issues.
• Robust Error Handling: Implemented robust error handling that raises a ValueError with a clear, descriptive message listing all detected duplicate names, aiding developers in quick resolution.
• Comprehensive Unit Testing: Added comprehensive unit tests covering various scenarios, including single duplicates, multiple duplicates, unique names, and empty sub-agent lists, to ensure the validation works as expected.
• Automatic Inheritance: Ensured the new validation automatically applies to all agent types that inherit from BaseAgent (e.g., LlmAgent, LoopAgent), providing consistent behavior across the agent hierarchy.

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 valuable validation check to ensure that sub-agents within a BaseAgent have unique names. The implementation is sound and the inclusion of unit tests is great. I've provided a couple of suggestions. One is to refine the error message to avoid redundancy when a name is duplicated multiple times. The other is to strengthen the unit tests to be more specific in their assertions, which will make them more robust against future changes. Overall, this is a solid contribution that improves the reliability of agent creation.