fix: BigQuery plugin — A2A tool classification, self-consistent span tree, and A2A metadata

[caohy1988]

Summary

Fixes #5073, #5310, and #5311

Three fixes to the BigQueryAgentAnalyticsPlugin, all localized to the plugin — no changes to ADK core.

Fix 1: Classify TransferToAgentTool transfers to RemoteA2aAgent as TRANSFER_A2A (#5073)

When a RemoteA2aAgent is registered via sub_agents=[], the plugin now correctly classifies transfers to it as TRANSFER_A2A instead of the generic TRANSFER_AGENT. Classification is call-level: a single TransferToAgentTool with mixed local and A2A targets produces the correct label per invocation based on the selected agent_name.

Changes:

• Added _find_transfer_target() helper — searches the agent tree (sub-agents, parent, peers) for the transfer target
• Extended _get_tool_origin() with optional tool_args/tool_context for call-level transfer classification
• Updated after_tool_callback and on_tool_error_callback to pass tool_args/tool_context

Tool path	Selected target	Label
TransferToAgentTool	local agent	TRANSFER_AGENT (unchanged)
TransferToAgentTool	RemoteA2aAgent	TRANSFER_A2A (new)

Fix 2: Self-consistent BQ span tree (#5310)

When OTel instrumentation was active, _resolve_ids() derived parent_span_id from ambient framework spans (execute_tool, call_llm, invoke_agent, send_data) that are never written to BQ, creating phantom references. In production datasets, 92.8% of LLM_RESPONSE events and 10.3% of TOOL events had dangling parent_span_id values.

Root cause: _resolve_ids() Layer 2 (ambient OTel) unconditionally overrode the plugin stack's span_id / parent_span_id, and all 6 post-pop callbacks suppressed plugin-stack overrides when an ambient span was present (None if has_ambient else ...).

Fix:

• _resolve_ids(): plugin-stack span_id / parent_span_id are now the preferred source. Ambient OTel only provides trace_id (always) and falls back for span IDs only when the plugin stack has no span.
• 6 post-pop callbacks (after_agent, after_run, after_model, after_tool, on_model_error, on_tool_error): always pass both span_id_override and parent_span_id_override from the plugin stack. The has_ambient gating is removed.

This ensures every parent_span_id in BQ references a span_id that also exists in BQ, producing a self-consistent execution tree.

Fix 3: Surface A2A metadata in BQ (#5311)

RemoteA2aAgent already attaches correlation metadata (a2a:task_id, a2a:context_id, a2a:request, a2a:response) to event.custom_metadata on both legacy (lines 504-520) and v2 (lines 575-590) A2A paths. However, on_event_callback() only logged STATE_DELTA and HITL events — the A2A metadata was silently dropped before reaching BigQuery.

Fix:

• on_event_callback() now detects events carrying a2a:request or a2a:response in custom_metadata and logs an A2A_INTERACTION event with:
  • content: truncated a2a:response payload (the remote agent's answer)
  • attributes.a2a_metadata: all truncated a2a:* keys for cross-reference JOINs
• A2A_INTERACTION added to _EVENT_VIEW_DEFS with extracted columns: response_content, a2a_task_id, a2a_context_id, a2a_request, a2a_response
• Events with only a2a:task_id / a2a:context_id (no request/response payload) are not logged

E2E Validation (real Gemini + real BigQuery)

Tested with a real multi-agent setup:

supervisor (gemini-2.0-flash)
  ├── local_helper  — local sub-agent (greeting)
  └── remote_math   — RemoteA2aAgent via A2A protocol (math)

26 rows landed in BigQuery. Results:

Check	Result
Phantom parent_span_id refs	0 (all resolved or null for root events)
A2A_INTERACTION events	3 rows with a2a:task_id, a2a:response metadata
TRANSFER_A2A classification	Correct for A2A transfers

Test plan

• 205 unit tests pass, 0 regressions
• 5 new tests for BigQueryAgentAnalyticsPlugin: tool_origin not set to "A2A" when RemoteA2aAgent is used via sub_agents #5073: A2A sub-agent, local sub-agent, A2A peer, mixed-target per-call, fallback without args
• 1 new test for BigQueryAgentAnalyticsPlugin: tool_origin not set to "A2A" when RemoteA2aAgent is used via sub_agents #5073 error path: on_tool_error_callback with RemoteA2aAgent target
• 3 existing _resolve_ids tests updated to reflect new priority rules
• 2 new _resolve_ids tests: plugin-stack-wins-over-ambient, ambient-fallback-when-no-stack
• 4 new A2A_INTERACTION tests: response metadata, request-only metadata, irrelevant metadata skipped, no metadata skipped
• E2E validation against real Gemini + real BigQuery with multi-agent A2A setup

🤖 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!

It looks like you have not yet signed the Contributor License Agreement (CLA). Please visit https://cla.developers.google.com/ to sign the agreement. This is necessary for us to be able to merge your contribution.

Thanks!