refactor(agents): Improve transfer type safety

[mdabydeen]

Created branch refactor/agent-transfer-typing and implemented the typing cleanup in src/google/ adk/flows/llm_flows/agent_transfer.py

Changes:

• Replaced Any with BaseAgent.
• Accepted Sequence[BaseAgent].
• Corrected type-only imports.
• Removed obsolete TODOs and quoted annotations.

[rohityan]

Hi @mdabydeen , Thank you for your contribution! We appreciate you taking the time to submit this pull request.
Can you please clarify the changes.

[mdabydeen]

Hey @rohityan, appreciate you taking the time.

This PR is a small, low-risk typing cleanup in agent_transfer.py There's no behavior changes.

What changed:

• Replaced loose Any types with the actual BaseAgent type for transfer target parameters.
• Changed list[...] to Sequence[...] where the code only reads the collection, better reflecting intent.
• Cleaned up TYPE_CHECKING imports to reference concrete modules (agents.base_agent, agents.llm_agent) instead of package-level re-exports.
• Removed quoted forward-ref strings ('LlmAgent', 'BaseAgent') now that from future import annotations makes them unnecessary
• Deleted two stale # TODO: Refactor the annotation comments that this change resolves. these functions previously accepted Any, so type checkers couldn't catch misuse of target_agent/target_agents. Now ca and the docstrings match reality instead of describing a duck-typed contract.

Risk: none functionally, this is annotations and imports only, no runtime logic touched.

[adk-bot]

Response from ADK Triaging Agent

Hello @mdabydeen, thank you for creating this PR!

This PR is a code refactoring of type annotations. Could you please include a testing plan section in your PR description describing how you have verified these changes (e.g., summary of mypy or pytest results)? If there is an associated GitHub issue for this, please link it in your description as well.

This will help our reviewers verify the correctness of the refactoring. Thank you!

[mdabydeen]

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

• No associated GitHub issue.

2. Or, if no issue exists, describe the change:

Problem:
src/google/adk/flows/llm_flows/agent_transfer.py used Any (and a stale # TODO: Refactor the annotation of the parameters) for the target_agent(s) parameters of _build_target_agents_info and _build_transfer_instruction_body, and imported BaseAgent/LlmAgent from the ...agents package __init__ instead of their defining modules.

Solution:

• Replaced Any with BaseAgent for _build_target_agents_info's target_agent param.
• Replaced list[Any] with Sequence[BaseAgent] for target_agents params, since the values are only ever read, not mutated.
• Changed the TYPE_CHECKING imports to pull BaseAgent/LlmAgent directly from ...agents.base_agent / ...agents.llm_agent instead of the ...agents package __init__, avoiding a package-level import for type-only usage.
• Removed the obsolete # TODO: Refactor the annotation of the parameters comments and quoted ('LlmAgent', 'BaseAgent') forward-reference annotations, now that the module has from __future__ import annotations.
• No behavior change — this is a type-annotation-only refactor.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change. (N/A — this is a type-annotation-only refactor with no behavior change, so no new tests were needed. Existing coverage of agent_transfer.py already exercises the changed functions.)
• All unit tests pass locally.

Summary of pytest results:

Ran the full unit test suite locally (pytest tests/unittests -q):

8082 passed, 24 skipped, 31 xfailed, 9 xpassed, 1795 warnings, 6 subtests passed in 128.64s (0:02:08)

Also ran the tests that directly exercise agent_transfer.py in isolation:

pytest tests/unittests/workflow/test_agent_transfer.py \
       tests/unittests/flows/llm_flows/test_agent_transfer_system_instructions.py \
       tests/unittests/workflow/test_llm_agent_as_node.py \
       tests/unittests/agents/test_llm_agent_output_save.py \
       tests/unittests/plugins/test_bigquery_agent_analytics_plugin.py -q

378 passed, 8 skipped, 4 xfailed, 37 warnings in 23.71s

Also ran mypy on the changed file:

mypy src/google/adk/flows/llm_flows/agent_transfer.py

This reports 2 pre-existing errors (Argument ... incompatible type "BaseNode | None"; expected "LlmAgent" at lines 47 and 58) that are unrelated to this change — I confirmed by running the identical mypy command against main and got the same 2 errors, so this PR introduces no new type errors.

Manual End-to-End (E2E) Tests:

Not applicable — this is a non-functional, type-annotation-only refactor (no runtime logic changed). Correctness is covered by the existing unit test suite above, which exercises agent-transfer instruction building and multi-agent transfer flows end-to-end.

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. (N/A — no behavior change; existing tests provide coverage.)
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end. (N/A — no runtime behavior changed; see Testing Plan.)
• Any dependent changes have been merged and published in downstream modules.

Additional context

This PR is purely a typing/readability cleanup of agent_transfer.py: no runtime behavior is affected. Confirmed by running the full test suite and mypy both before (on main) and after this change, with identical results apart from the annotations themselves.