feat: add opt-in final_response_tool_names to BigQueryAgentAnalyticsPlugin

Agents that deliver their final answer through a dedicated tool (e.g. a
submit_final_response tool) instead of a plain-text final event do not trigger
the on-event AGENT_RESPONSE path, so the response text is not captured. Add an
opt-in BigQueryLoggerConfig.final_response_tool_names: when a completed tool's
name is in the set, after_tool_callback logs its call args as an AGENT_RESPONSE
event. The default (empty) preserves existing behavior.

Co-authored-by: Haiyuan Cao <haiyuan@google.com>
PiperOrigin-RevId: 953043855

Author: haiyuan-eng-google

src/google/adk/plugins/bigquery_agent_analytics_plugin.py

@@ -1015,8 +1015,14 @@ class BigQueryLoggerConfig:
         views all stay consistent); views that reference a denied column drop
         the dependent derived columns. NOTE: denying ``attributes`` also
         disables ``attributes.otel`` and ``attributes.custom_metadata``;
-        combining it with a non-empty ``custom_metadata_allowlist`` is
-        rejected at construction.
+        combining it with a non-empty ``custom_metadata_allowlist`` is rejected
+        at construction.
+      final_response_tool_names: Tool names whose successful completion carries
+        the agent's final answer. When a completed tool's name is in this set,
+        its call args are logged as an ``AGENT_RESPONSE`` event. For agents that
+        emit the final answer via a dedicated tool (e.g.
+        ``submit_final_response``) rather than a plain-text final event. Empty
+        (the default) preserves today's behavior.
   """
 
   enabled: bool = True
@@ -1081,6 +1087,17 @@ class BigQueryLoggerConfig:
   # are protected (see ``_PROJECTABLE_PAYLOAD_COLUMNS``).
   payload_column_denylist: list[str] | None = None
 
+  # --- final-answer-via-tool capture ---
+  # Tool names whose successful completion carries the agent's final
+  # response.  Some agents deliver their final answer through a dedicated
+  # tool (e.g. ``submit_final_response``) instead of a plain-text final
+  # event, so the on-event ``AGENT_RESPONSE`` path (which excludes function
+  # calls/responses) never fires.  When a completed tool's name is in this
+  # set, its call args (the final-answer payload) are logged as an
+  # ``AGENT_RESPONSE`` event.  Empty (the default) preserves today's
+  # behavior.
+  final_response_tool_names: frozenset[str] = frozenset()
+
 
 # ==============================================================================
 # HELPER: TRACE MANAGER (Async-Safe with ContextVars)
@@ -5147,6 +5164,25 @@ async def after_tool_callback(
         event_data=event_data,
     )
 
+    # Some agents deliver their final answer through a dedicated tool
+    # (e.g. ``submit_final_response``) rather than a plain-text final event,
+    # so the on-event AGENT_RESPONSE path (which excludes function
+    # calls/responses) never fires.  When such a tool completes, log its call
+    # args (the final-answer payload the model supplied) as AGENT_RESPONSE so
+    # the visible response text is captured.  Opt-in via
+    # ``config.final_response_tool_names`` (empty by default).
+    if tool.name in self.config.final_response_tool_names:
+      args_truncated, args_is_truncated = _recursive_smart_truncate(
+          tool_args, self.config.max_content_length
+      )
+      await self._log_event(
+          "AGENT_RESPONSE",
+          tool_context,
+          raw_content={"response": args_truncated},
+          is_truncated=args_is_truncated,
+          event_data=EventData(extra_attributes={"source_tool": tool.name}),
+      )
+
   @_safe_callback
   async def on_tool_error_callback(
       self,

tests/unittests/plugins/test_bigquery_agent_analytics_plugin.py

@@ -1041,6 +1041,98 @@ async def test_max_content_length_tool_result_no_truncation(
       assert content_dict["tool"] == "MyTool"
       assert content_dict["result"]["res"] == "A" * 100
 
+  @pytest.mark.asyncio
+  async def test_after_tool_callback_logs_agent_response_for_final_tool(
+      self,
+      mock_write_client,
+      tool_context,
+      mock_auth_default,
+      mock_bq_client,
+      mock_to_arrow_schema,
+      dummy_arrow_schema,
+      mock_asyncio_to_thread,
+  ):
+    """A configured final-response tool also logs AGENT_RESPONSE from its args."""
+    _ = mock_auth_default
+    _ = mock_bq_client
+    _ = mock_to_arrow_schema
+    _ = mock_asyncio_to_thread
+    config = bigquery_agent_analytics_plugin.BigQueryLoggerConfig(
+        final_response_tool_names=frozenset({"submit_final_response"})
+    )
+    async with managed_plugin(
+        PROJECT_ID, DATASET_ID, table_id=TABLE_ID, config=config
+    ) as plugin:
+      await plugin._ensure_started()
+      mock_write_client.append_rows.reset_mock()
+      mock_tool = mock.create_autospec(
+          base_tool_lib.BaseTool, instance=True, spec_set=True
+      )
+      type(mock_tool).name = mock.PropertyMock(
+          return_value="submit_final_response"
+      )
+      bigquery_agent_analytics_plugin.TraceManager.push_span(tool_context)
+      await plugin.after_tool_callback(
+          tool=mock_tool,
+          tool_args={"answer": "The table has 241 rows."},
+          tool_context=tool_context,
+          result={"status": "SUCCESS"},
+      )
+      await plugin.flush()
+      rows = await _get_captured_rows_async(
+          mock_write_client, dummy_arrow_schema
+      )
+      event_types = [r["event_type"] for r in rows]
+      assert "TOOL_COMPLETED" in event_types
+      assert event_types.count("AGENT_RESPONSE") == 1
+      agent_resp = next(r for r in rows if r["event_type"] == "AGENT_RESPONSE")
+      content_dict = json.loads(agent_resp["content"])
+      assert content_dict["response"] == {"answer": "The table has 241 rows."}
+      attributes = json.loads(agent_resp["attributes"])
+      assert attributes["source_tool"] == "submit_final_response"
+
+  @pytest.mark.asyncio
+  async def test_after_tool_callback_no_agent_response_by_default(
+      self,
+      mock_write_client,
+      tool_context,
+      mock_auth_default,
+      mock_bq_client,
+      mock_to_arrow_schema,
+      dummy_arrow_schema,
+      mock_asyncio_to_thread,
+  ):
+    """With the default empty set, a tool never emits AGENT_RESPONSE."""
+    _ = mock_auth_default
+    _ = mock_bq_client
+    _ = mock_to_arrow_schema
+    _ = mock_asyncio_to_thread
+    config = bigquery_agent_analytics_plugin.BigQueryLoggerConfig()
+    async with managed_plugin(
+        PROJECT_ID, DATASET_ID, table_id=TABLE_ID, config=config
+    ) as plugin:
+      await plugin._ensure_started()
+      mock_write_client.append_rows.reset_mock()
+      mock_tool = mock.create_autospec(
+          base_tool_lib.BaseTool, instance=True, spec_set=True
+      )
+      type(mock_tool).name = mock.PropertyMock(
+          return_value="submit_final_response"
+      )
+      bigquery_agent_analytics_plugin.TraceManager.push_span(tool_context)
+      await plugin.after_tool_callback(
+          tool=mock_tool,
+          tool_args={"answer": "hi"},
+          tool_context=tool_context,
+          result={"status": "SUCCESS"},
+      )
+      await plugin.flush()
+      rows = await _get_captured_rows_async(
+          mock_write_client, dummy_arrow_schema
+      )
+      event_types = [r["event_type"] for r in rows]
+      assert "AGENT_RESPONSE" not in event_types
+
   @pytest.mark.asyncio
   async def test_max_content_length_tool_error(
       self,