feat(plugins): add TRANSFER_A2A classification for TransferToAgentTool

[caohy1988]

Summary

• Adds target_origin_by_name metadata to TransferToAgentTool so analytics can distinguish remote A2A transfers from local agent transfers
• Populates the origin map in agent_transfer.py using isinstance(agent, RemoteA2aAgent) at tool construction time
• Adds _resolve_transfer_origin() helper in the BQ analytics plugin to refine TRANSFER_AGENT → TRANSFER_A2A at call time using tool_args["agent_name"]

Fixes #5073

Test plan

• 2 new tests in test_transfer_to_agent_tool.py — metadata storage (default empty, stored map)
• 1 new test in test_agent_transfer_system_instructions.py — wiring produces correct origin map with mixed local + A2A sub-agents
• 5 new tests in TestToolProvenance — all _resolve_transfer_origin branches (remote target, local target, no args, missing key, unknown name)
• 2 new e2e callback tests — before_tool_callback and after_tool_callback emit tool_origin=TRANSFER_A2A in serialized BQ rows
• All 195 existing BQ plugin tests pass (regression)
• All existing transfer tool and agent transfer tests pass

End-to-end validation against real BigQuery

Validation script: contributing/samples/validate_transfer_a2a/validate.py

Architecture:

orchestrator_agent (gemini-2.0-flash)
    ├── local_weather_agent   (local sub-agent)
    └── remote_math_agent     (RemoteA2aAgent → in-process A2A server)

The script starts an in-process A2A server (ASGI transport), creates an orchestrator with both sub-agent types, wires BigQueryAgentAnalyticsPlugin to a real GCP project, sends two prompts (one math, one weather), then queries BQ to verify classification.

BQ query results (test-project-0728-467323.adk_logs.transfer_a2a_validation)

SELECT event_type, JSON_VALUE(content, '$.tool_origin') AS tool_origin, content
FROM `test-project-0728-467323.adk_logs.transfer_a2a_validation`
WHERE event_type IN ('TOOL_STARTING', 'TOOL_COMPLETED')
  AND JSON_VALUE(content, '$.tool') = 'transfer_to_agent'
ORDER BY timestamp ASC

event_type	tool_origin	content
TOOL_STARTING	TRANSFER_A2A	{"args":{"agent_name":"remote_math_agent"},"tool":"transfer_to_agent","tool_origin":"TRANSFER_A2A"}
TOOL_COMPLETED	TRANSFER_A2A	{"result":null,"tool":"transfer_to_agent","tool_origin":"TRANSFER_A2A"}
TOOL_STARTING	TRANSFER_AGENT	{"args":{"agent_name":"local_weather_agent"},"tool":"transfer_to_agent","tool_origin":"TRANSFER_AGENT"}
TOOL_COMPLETED	TRANSFER_AGENT	{"result":null,"tool":"transfer_to_agent","tool_origin":"TRANSFER_AGENT"}

Feature-level validation

#	Feature	BQ Evidence	Status
1	target_origin_by_name metadata stored on tool	TOOL_STARTING rows show different tool_origin per agent — impossible without the metadata map	Validated
2	isinstance(RemoteA2aAgent) population at construction	remote_math_agent → TRANSFER_A2A, local_weather_agent → TRANSFER_AGENT	Validated
3	_resolve_transfer_origin() using tool_args["agent_name"]	All 4 rows (both callbacks, both transfer types) carry correctly resolved tool_origin	Validated

Note: TOOL_COMPLETED rows don't include args in the content JSON (by design — after_tool_callback serializes result, not args), but tool_origin is resolved from tool_args before serialization, so both TOOL_STARTING and TOOL_COMPLETED carry the correct classification.

🤖 Generated with Claude Code

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

[adk-bot]

Response from ADK Triaging Agent

Hello @caohy1988, thank you for creating this PR!

Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). You can find more information in the "checks" section at the bottom of the pull request. Thanks!