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

src/google/adk/agents/base_agent.py

@@ -563,6 +563,46 @@ class BaseAgent(BaseModel):
       )
     return value
 
+  @field_validator('sub_agents', mode='after')
+  @classmethod
+  def validate_sub_agents_unique_names(
+      cls, value: list[BaseAgent]
+  ) -> list[BaseAgent]:
+    """Validates that all sub-agents have unique names.
+
+    Args:
+      value: The list of sub-agents to validate.
+
+    Returns:
+      The validated list of sub-agents.
+
+    Raises:
+      ValueError: If duplicate sub-agent names are found.
+    """
+    if not value:
+      return value
+
+    seen_names: set[str] = set()
+    duplicates: set[str] = set()
+
+    for sub_agent in value:
+      name = sub_agent.name
+      if name in seen_names:
+        duplicates.add(name)
+      else:
+        seen_names.add(name)
+
+    if duplicates:
+      duplicate_names_str = ', '.join(
+          f'`{name}`' for name in sorted(duplicates)
+      )
+      raise ValueError(
+          f'Found duplicate sub-agent names: {duplicate_names_str}. '
+          'All sub-agents must have unique names.'
+      )
+
+    return value
+
   def __set_parent_agent_for_sub_agents(self) -> BaseAgent:
     for sub_agent in self.sub_agents:
       if sub_agent.parent_agent is not None:

tests/unittests/agents/test_base_agent.py

@@ -854,6 +854,110 @@ def test_set_parent_agent_for_sub_agent_twice(
     )
 
 
+def test_validate_sub_agents_unique_names_single_duplicate(
+    request: pytest.FixtureRequest,
+):
+  """Test that duplicate sub-agent names raise ValueError."""
+  duplicate_name = f'{request.function.__name__}_duplicate_agent'
+  sub_agent_1 = _TestingAgent(name=duplicate_name)
+  sub_agent_2 = _TestingAgent(name=duplicate_name)
+
+  with pytest.raises(ValueError, match='Found duplicate sub-agent names'):
+    _ = _TestingAgent(
+        name=f'{request.function.__name__}_parent',
+        sub_agents=[sub_agent_1, sub_agent_2],
+    )
+
+
+def test_validate_sub_agents_unique_names_multiple_duplicates(
+    request: pytest.FixtureRequest,
+):
+  """Test that multiple duplicate sub-agent names are all reported."""
+  duplicate_name_1 = f'{request.function.__name__}_duplicate_1'
+  duplicate_name_2 = f'{request.function.__name__}_duplicate_2'
+
+  sub_agents = [
+      _TestingAgent(name=duplicate_name_1),
+      _TestingAgent(name=f'{request.function.__name__}_unique'),
+      _TestingAgent(name=duplicate_name_1),  # First duplicate
+      _TestingAgent(name=duplicate_name_2),
+      _TestingAgent(name=duplicate_name_2),  # Second duplicate
+  ]
+
+  with pytest.raises(ValueError) as exc_info:
+    _ = _TestingAgent(
+        name=f'{request.function.__name__}_parent',
+        sub_agents=sub_agents,
+    )
+
+  error_message = str(exc_info.value)
+  # Verify each duplicate name appears exactly once in the error message
+  assert error_message.count(duplicate_name_1) == 1
+  assert error_message.count(duplicate_name_2) == 1
+  # Verify both duplicate names are present
+  assert duplicate_name_1 in error_message
+  assert duplicate_name_2 in error_message
+
+
+def test_validate_sub_agents_unique_names_triple_duplicate(
+    request: pytest.FixtureRequest,
+):
+  """Test that a name appearing three times is reported only once."""
+  duplicate_name = f'{request.function.__name__}_triple_duplicate'
+
+  sub_agents = [
+      _TestingAgent(name=duplicate_name),
+      _TestingAgent(name=f'{request.function.__name__}_unique'),
+      _TestingAgent(name=duplicate_name),  # Second occurrence
+      _TestingAgent(name=duplicate_name),  # Third occurrence
+  ]
+
+  with pytest.raises(ValueError) as exc_info:
+    _ = _TestingAgent(
+        name=f'{request.function.__name__}_parent',
+        sub_agents=sub_agents,
+    )
+
+  error_message = str(exc_info.value)
+  # Verify the duplicate name appears exactly once in the error message
+  # (not three times even though it appears three times in the list)
+  assert error_message.count(duplicate_name) == 1
+  assert duplicate_name in error_message
+
+
+def test_validate_sub_agents_unique_names_no_duplicates(
+    request: pytest.FixtureRequest,
+):
+  """Test that unique sub-agent names pass validation."""
+  sub_agents = [
+      _TestingAgent(name=f'{request.function.__name__}_sub_agent_1'),
+      _TestingAgent(name=f'{request.function.__name__}_sub_agent_2'),
+      _TestingAgent(name=f'{request.function.__name__}_sub_agent_3'),
+  ]
+
+  parent = _TestingAgent(
+      name=f'{request.function.__name__}_parent',
+      sub_agents=sub_agents,
+  )
+
+  assert len(parent.sub_agents) == 3
+  assert parent.sub_agents[0].name == f'{request.function.__name__}_sub_agent_1'
+  assert parent.sub_agents[1].name == f'{request.function.__name__}_sub_agent_2'
+  assert parent.sub_agents[2].name == f'{request.function.__name__}_sub_agent_3'
+
+
+def test_validate_sub_agents_unique_names_empty_list(
+    request: pytest.FixtureRequest,
+):
+  """Test that empty sub-agents list passes validation."""
+  parent = _TestingAgent(
+      name=f'{request.function.__name__}_parent',
+      sub_agents=[],
+  )
+
+  assert len(parent.sub_agents) == 0
+
+
 if __name__ == '__main__':
   pytest.main([__file__])