Agent card skills usage

[luis5tb]

Problem:
The subagents agent cards information is not being used by the root agent to decide on which subagent should the request be transfered to

Solution:
This PR ensures the subagents agent cards information (description, skills) are being used as context for the root agent so that it can better decide on the subagent to transfer the request.

It also includes a bit or rewording/formatting so that information about each subagent can be better processed

Testing Plan

Unit test (test_agent_transfer_system_instructions.py) has been modified to cover the new expected context

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

$ pytest ./tests/unittests/flows/llm_flows/test_agent_transfer_system_instructions.py                                                                                                                                                     agent_card_skills_usage 
==================================================================================================================================================== test session starts =====================================================================================================================================================
platform linux -- Python 3.11.14, pytest-8.4.2, pluggy-1.6.0
configfile: pyproject.toml
plugins: langsmith-0.4.38, xdist-3.8.0, asyncio-1.2.0, mock-3.15.1, anyio-4.11.0
asyncio: mode=Mode.AUTO, debug=False, asyncio_default_fixture_loop_scope=function, asyncio_default_test_loop_scope=function
collected 4 items                                                                                                                                                                                                                                                                                                            

tests/unittests/flows/llm_flows/test_agent_transfer_system_instructions.py ....                                                                                                                                                                                                                                        [100%]

====================================================================================================================================================== warnings summary ======================================================================================================================================================
.venv/lib64/python3.11/site-packages/google/genai/types.py:9562
  /home/ltomasbo/AI/Claude/adk-python/.venv/lib64/python3.11/site-packages/google/genai/types.py:9562: PydanticDeprecatedSince212: Using `@model_validator` with mode='after' on a classmethod is deprecated. Instead, use an instance method. See the documentation at https://docs.pydantic.dev/2.12/concepts/validators/#model-after-validator. Deprecated in Pydantic V2.12 to be removed in V3.0.
    @model_validator(mode='after')  # type: ignore[arg-type]

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
================================================================================================================================================ 4 passed, 1 warning in 3.26s ================================================================================================================================================

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.

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

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello @luis5tb, 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 significantly enhances the root agent's ability to intelligently delegate tasks to subagents. By integrating and leveraging detailed information from subagent 'agent cards'—such as descriptions and specific skills—the system can now provide richer context to the LLM. This improvement, coupled with a re-engineered instruction prompt, aims to optimize the decision-making process for agent transfers, leading to more accurate and efficient task routing.

Highlights

• Enhanced Subagent Information Usage: The root agent now utilizes detailed subagent information, including descriptions and skills from 'agent cards', to make more informed decisions when transferring requests.
• Asynchronous Agent Card Resolution: Introduced asynchronous processing to resolve A2A agent cards, ensuring that the most up-to-date and comprehensive subagent details are available for decision-making.
• Improved LLM Instructions for Agent Transfer: The instructions provided to the Large Language Model (LLM) for agent transfer have been significantly reworded and reformatted to clearly present available agents, their skills, and a structured decision-making process.

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

[adk-bot]

Response from ADK Triaging Agent

Hello @luis5tb, thank you for creating this PR!

To help us review your contribution, could you please address the following points from our contribution guidelines:

• Contributor License Agreement (CLA): It looks like the CLA check has failed. Please ensure you have signed the Contributor License Agreement before we can proceed with the review.
• Testing Plan: Could you please fill out the "Testing Plan" section in your PR description? This should include details on how you've tested the changes, along with any relevant logs or screenshots. This is crucial for our reviewers to understand and verify your fix.
• Associated Issue: For a feature enhancement like this, please create a GitHub issue that describes the problem and solution, and link it to this PR.

Providing this information will help us to review your PR more efficiently. Thanks!

[gemini-code-assist]

Code Review

This pull request enhances the agent transfer mechanism by incorporating detailed information from subagents' agent cards, including descriptions and skills. This provides richer context to the root agent for making more informed transfer decisions. The prompt for the root agent has also been significantly improved with better structure and clarity for the LLM.

My review includes two suggestions for improvement in src/google/adk/flows/llm_flows/agent_transfer.py:

1. Add logging for agent card resolution failures to aid in debugging.
2. Use asyncio.gather to resolve agent cards concurrently, which can improve performance when multiple remote agents are involved.

A critical point is that the unit tests in tests/unittests/flows/llm_flows/test_agent_transfer_system_instructions.py appear to be outdated. They test the old system prompt structure and will likely fail with the new changes. It's important to update these tests to ensure the new, more complex prompt generation logic is correctly validated.

[bparees]

@luis5tb thinking about our particular needs/use cases a few things come to mind:

1. when would we want to reload the agent card in case it has changed? (currently i assume this just does it when the ADK process starts up/initializes the remote agent). Tbh this is probably a bigger can of worms that is more closely tied to the A2A protocol/agent-card format itself (agent cards having some sort of guidance about reloading/expiration)

2. ability to choose not to use the agent card details as part of the supervisor routing instructions? (maybe this just means not providing an agent card url/string to the remote agent in the first place?)

[luis5tb]

@luis5tb thinking about our particular needs/use cases a few things come to mind:

1. when would we want to reload the agent card in case it has changed? (currently i assume this just does it when the ADK process starts up/initializes the remote agent). Tbh this is probably a bigger can of worms that is more closely tied to the A2A protocol/agent-card format itself (agent cards having some sort of guidance about reloading/expiration)

This is a good point. I agree it must be handled but not as part of this PR, right? I think it is loaded the first time the root agent needs to invoke the subagents (at least it is when I see the request on the subagent)

2. ability to choose not to use the agent card details as part of the supervisor routing instructions? (maybe this just means not providing an agent card url/string to the remote agent in the first place?)

Another great point! Thanks for raising! Perhaps one way to configure using or not the description/skills on the agent card is by defining or not a description when creating the RemoteA2aAgent. What do you think?

Note the agent card must be read as the endpoint is being retrieved from there (as well as other details such as the security needed for instance)

[bparees]

This is a good point. I agree it must be handled but not as part of this PR, right? I think it is loaded the first time the root agent needs to invoke the subagents (at least it is when I see the request on the subagent)

no, not as part of this PR per se, but it's the next logical question once the ADK has this behavior (to be fair this concern also applies to the existing ADK behavior because for example a new version of the agent card could update how security is managed), so maybe "when should agent cards be refreshed/how is it controlled" is a distinct RFE that just has implications for this behavior.

Another great point! Thanks for raising! Perhaps one way to configure using or not the description/skills on the agent card is by defining or not a description when creating the RemoteA2aAgent. What do you think?

yeah, ultimately these feel like config/parameter choices when constructing the remote agent:

1. to use the agent card or not for routing/supervisor instructions
2. to provide a description directly or not
3. interplay of the description and the agent card (can you provide both? if so, do they get merged together?)

[luis5tb]

This is a good point. I agree it must be handled but not as part of this PR, right? I think it is loaded the first time the root agent needs to invoke the subagents (at least it is when I see the request on the subagent)

no, not as part of this PR per se, but it's the next logical question once the ADK has this behavior (to be fair this concern also applies to the existing ADK behavior because for example a new version of the agent card could update how security is managed), so maybe "when should agent cards be refreshed/how is it controlled" is a distinct RFE that just has implications for this behavior.

Another great point! Thanks for raising! Perhaps one way to configure using or not the description/skills on the agent card is by defining or not a description when creating the RemoteA2aAgent. What do you think?

yeah, ultimately these feel like config/parameter choices when constructing the remote agent:

1. to use the agent card or not for routing/supervisor instructions
2. to provide a description directly or not
3. interplay of the description and the agent card (can you provide both? if so, do they get merged together?)

Yeah, currently (with this PR I mean) if both are provided, both are included:

  if target_agent.description:
    descriptions.append(f'Description: {target_agent.description}')
  if agent_card.description and agent_card.description != target_agent.description:
    descriptions.append(f'Agent card description: {agent_card.description}')