Skip to content

AgentTool and task-mode delegation never show a RemoteA2aAgent's agent-card description to the model #8155

Description

@fponsse

🔴 Required Information

Describe the Bug:

RemoteA2aAgent documents description as "autopopulated from card if empty", and when such an agent is a transfer_to_agent target ADK does resolve it: _build_transfer_target_info awaits RemoteA2aAgent._get_transfer_description, which downloads the card, before the instruction is built.

When the same agent is exposed to the model as a tool, the card description never reaches the model:

  • A sub-agent in mode="task" becomes a _TaskAgentTool, whose declaration is built synchronously from self.agent.description or '', so the model sees only the generic IMPORTANT: This tool delegates execution… sentence.
  • AgentTool(RemoteA2aAgent(...)) declares an empty description for the same reason.

Both _get_declaration() implementations are synchronous, so they cannot await the card, and nothing resolves it for them.

The description adopted in RemoteA2aAgent._ensure_resolved does not help in task mode, because the delegation runs on a clone (build_node does agent_node.clone(update=kwargs), the same cause as #7629) and whatever the clone learns stays on the clone. On 2.14.0 I checked the instance held by the calling agent after a delegation had run: _is_resolved was False, it had no card and description == ''. So the description does not arrive late, it never arrives, and the model only knows the tool's name.

Setting description= on the RemoteA2aAgent works around it, which defeats the point of reading it from the card.

Steps to Reproduce:

  1. pip install "google-adk[a2a]" (I ran it on main, d05e482, ADK 2.14.1)
  2. Run the script below. It needs no API key: the model is a stub that prints what it is shown.
"""Does the agent card's description reach the model of the calling agent?

A remote agent publishes a card with a description. The caller points a RemoteA2aAgent at the card's URL and gives it no
`description` of its own, so the card is the only place it is written ("autopopulated from card if empty").

The script records what the caller's model is shown in three setups and needs no API key: the model is a stub.
"""

import asyncio

import uvicorn
from google.adk.a2a.utils.agent_to_a2a import to_a2a
from google.adk.agents import Agent
from google.adk.agents.remote_a2a_agent import AGENT_CARD_WELL_KNOWN_PATH, RemoteA2aAgent
from google.adk.models.base_llm import BaseLlm
from google.adk.models.llm_response import LlmResponse
from google.adk.runners import InMemoryRunner
from google.adk.tools.agent_tool import AgentTool
from google.genai import types

PORT = 8772
CARD_URL = f"http://127.0.0.1:{PORT}{AGENT_CARD_WELL_KNOWN_PATH}"
DESCRIPTION = "Opens a refund for an order and returns its code."


class RecordingLlm(BaseLlm):
  model: str = "stub"

  async def generate_content_async(self, llm_request, stream=False):
    instruction = str(llm_request.config.system_instruction or "")
    if "Agent description:" in instruction:
      block = instruction.split("Agent description:")[1].split("\n\n")[0]
      print(f"    system instruction -> 'Agent description: {' '.join(block.split())}'")
    for tool in llm_request.config.tools or []:
      for declaration in tool.function_declarations or []:
        print(f"    tool {declaration.name!r} description -> {declaration.description!r}")
    yield LlmResponse(content=types.Content(role="model", parts=[types.Part(text="ok")]))


async def ask(title, **root_kwargs):
  print(f"\n{title}")
  root = Agent(name="root", model=RecordingLlm(), instruction="Help the customer.", **root_kwargs)
  runner = InMemoryRunner(agent=root)
  session = await runner.session_service.create_session(app_name=runner.app_name, user_id="user")
  message = types.Content(role="user", parts=[types.Part(text="hi")])
  async for _ in runner.run_async(user_id="user", session_id=session.id, new_message=message):
    pass


async def main():
  remote_app = to_a2a(Agent(name="refunds", description=DESCRIPTION, model=RecordingLlm(), instruction="Refund."), host="127.0.0.1", port=PORT)
  server = uvicorn.Server(uvicorn.Config(remote_app, port=PORT, log_level="warning"))
  serving = asyncio.create_task(server.serve())
  while not server.started:
    await asyncio.sleep(0.05)

  print(f"The card says: {DESCRIPTION!r}")
  await ask(
      "1. sub_agents=[RemoteA2aAgent(...)]  (transfer_to_agent target)",
      sub_agents=[RemoteA2aAgent(name="refunds_remote", agent_card=CARD_URL)],
  )
  await ask(
      '2. sub_agents=[RemoteA2aAgent(..., mode="task")]  (delegation tool)',
      sub_agents=[RemoteA2aAgent(name="refunds_remote", agent_card=CARD_URL, mode="task")],
  )
  await ask(
      "3. tools=[AgentTool(RemoteA2aAgent(...))]",
      tools=[AgentTool(RemoteA2aAgent(name="refunds_remote", agent_card=CARD_URL))],
  )

  server.should_exit = True
  await serving


asyncio.run(main())

Expected Behavior:

In all three setups the model is shown the description from the card (in cases 2 and 3 the same fenced text that case 1 shows, since it arrived over the network).

Observed Behavior:

Case 1 shows the description; cases 2 and 3 do not:

The card says: 'Opens a refund for an order and returns its code.'
1. sub_agents=[RemoteA2aAgent(...)]  (transfer_to_agent target)
    system instruction -> 'Agent description: <<<BEGIN_QUOTED_AGENT_CONTENT>>> Opens a refund for an order and returns its code. <<<END_QUOTED_AGENT_CONTENT>>>'
    tool 'transfer_to_agent' description -> "Transfer the query to another agent.\n\nUse this tool to hand off control to another agent that is more suitable to\nanswer the user's query according to the agent's description.\n\nArgs:\n  agent_name: the agent name to transfer to."
2. sub_agents=[RemoteA2aAgent(..., mode="task")]  (delegation tool)
    tool 'refunds_remote' description -> 'IMPORTANT: This tool delegates execution to a specialized agent. Do NOT call this tool in parallel with any other tools.'
3. tools=[AgentTool(RemoteA2aAgent(...))]
    tool 'refunds_remote' description -> ''

Environment Details:

  • ADK Library Version (pip show google-adk): 2.14.1 (main, d05e482); also seen on 2.14.0
  • Desktop OS: macOS
  • Python Version (python -V): 3.12

Model Information:

  • Are you using LiteLLM: No
  • Which model is being used: none, a stub BaseLlm (also seen with a real model through LiteLLM)

🟡 Optional Information

Regression:
N/A, I have not checked older versions.

Additional Context:

Related: #7629 (the agent tree is cloned per invocation, so state cached on RemoteA2aAgent is lost) and #4064 (closed; the transfer-target path).

A possible fix: have AgentTool.process_llm_request resolve the description through the same _build_transfer_target_info hook that transfer targets use. That keeps the per-invocation cache, the 5 s timeout, the fallback to agent.description and the fencing of text that came over the network, and changes nothing for agents without the hook. I have a PR for it with tests and will link it here.

How often has this issue occurred?:

  • Always (100%)

Activity

  1. added a commit that references this issue on Nov 15, 2026
    b978b74
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions