Improve wording for agent card information into agent transfer context

Author: luis5tb

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

@@ -82,49 +82,36 @@ def _build_target_agent_info_from_card(
     agent_card: The resolved A2A Agent Card
 
   Returns:
-    Formatted string with detailed agent information from the card
+    Formatted string with detailed agent information from the card,
+    optimized for LLM consumption when selecting subagents.
   """
-  info_parts = [f'Agent name: {target_agent.name}']
+  info_parts = []
 
-  # Use card description if available, fallback to agent description
-  description = agent_card.description or target_agent.description
-  if description:
-    info_parts.append(f'Agent description: {description}')
+  # Start with a clear header for the agent
+  info_parts.append(f'### Agent: {target_agent.name}')
 
-  # Add skills information from the card
+  # Include both RemoteA2aAgent description and agent card description
+  # This provides both the locally-configured context and the remote agent's self-description
+  descriptions = []
+  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}')
+
+  if descriptions:
+    info_parts.append('\n'.join(descriptions))
+
+  # Add skills in a structured, LLM-friendly format
   if agent_card.skills:
-    skills_info = []
+    info_parts.append('\nSkills:')
     for skill in agent_card.skills:
-      skill_desc = f'  - {skill.name}'
+      # Format: "- skill_name: description (tags: tag1, tag2)"
+      skill_parts = [f'  - **{skill.name}**']
       if skill.description:
-        skill_desc += f': {skill.description}'
+        skill_parts.append(f': {skill.description}')
       if skill.tags:
-        skill_desc += f' (tags: {", ".join(skill.tags)})'
-      skills_info.append(skill_desc)
-
-    info_parts.append(f'Agent skills:\n' + '\n'.join(skills_info))
-
-  # Add capabilities if available
-  if agent_card.capabilities:
-    caps = agent_card.capabilities
-    cap_info = []
-    if hasattr(caps, 'streaming') and caps.streaming:
-      cap_info.append('supports streaming')
-    if hasattr(caps, 'multimodal') and caps.multimodal:
-      cap_info.append('supports multimodal input/output')
-
-    if cap_info:
-      info_parts.append(f'Capabilities: {", ".join(cap_info)}')
-
-  # Add input/output modes
-  if agent_card.default_input_modes:
-    info_parts.append(
-        f'Input modes: {", ".join(agent_card.default_input_modes)}'
-    )
-  if agent_card.default_output_modes:
-    info_parts.append(
-        f'Output modes: {", ".join(agent_card.default_output_modes)}'
-    )
+        skill_parts.append(f' [Tags: {", ".join(skill.tags)}]')
+      info_parts.append(''.join(skill_parts))
 
   return '\n'.join(info_parts)
 
@@ -166,12 +153,15 @@ def _build_target_agents_info(target_agent: BaseAgent) -> str:
     target_agent: The agent to build info for
 
   Returns:
-    Formatted string with basic agent information
+    Formatted string with basic agent information, matching the enhanced format
+    for consistency with A2A agent cards.
   """
-  return f"""
-Agent name: {target_agent.name}
-Agent description: {target_agent.description}
-"""
+  info_parts = [f'### Agent: {target_agent.name}']
+
+  if target_agent.description:
+    info_parts.append(f'Description: {target_agent.description}')
+
+  return '\n'.join(info_parts)
 
 
 line_break = '\n'
@@ -187,7 +177,8 @@ async def _build_target_agents_instructions(
     target_agents: List of agents that can be transferred to
 
   Returns:
-    Formatted instructions string with agent transfer information
+    Formatted instructions string with agent transfer information,
+    optimized for LLM decision-making about which subagent to use.
   """
   # Build list of available agent names for the NOTE
   # target_agents already includes parent agent if applicable, so no need to add it again
@@ -207,25 +198,30 @@ async def _build_target_agents_instructions(
     agent_info = await _build_target_agents_info_async(target_agent)
     agent_info_list.append(agent_info)
 
+  # Create a separator for visual clarity
+  agents_section = '\n\n'.join(agent_info_list)
+
   si = f"""
-You have a list of other agents to transfer to:
+## Available Agents for Transfer
+
+You can delegate tasks to the following specialized agents. Carefully review each agent's description and skills to determine the best match for the user's request.
+
+{agents_section}
+
+## Decision Criteria
 
-{line_break.join(agent_info_list)}
+1. **Assess your own capability**: If you are the best agent to handle this request based on your own description and capabilities, answer it directly.
 
-If you are the best to answer the question according to your description, you
-can answer it.
+2. **Consider specialized agents**: If another agent has more relevant skills or expertise for this request, call the `{_TRANSFER_TO_AGENT_FUNCTION_NAME}` function to transfer to that agent. Match the user's needs with the agent's skills and descriptions above.
 
-If another agent is better for answering the question according to its
-description, call `{_TRANSFER_TO_AGENT_FUNCTION_NAME}` function to transfer the
-question to that agent. When transferring, do not generate any text other than
-the function call.
+3. **When transferring**: Only call the function - do not generate any additional text.
 
-**NOTE**: the only available agents for `{_TRANSFER_TO_AGENT_FUNCTION_NAME}` function are {formatted_agent_names}.
+**IMPORTANT**: The only valid agent names for `{_TRANSFER_TO_AGENT_FUNCTION_NAME}` are: {formatted_agent_names}
 """
 
   if agent.parent_agent and not agent.disallow_transfer_to_parent:
     si += f"""
-If neither you nor the other agents are best for the question, transfer to your parent agent {agent.parent_agent.name}.
+4. **Escalate to parent**: If neither you nor the specialized agents are suitable for this request, transfer to your parent agent `{agent.parent_agent.name}` for broader assistance.
 """
   return si