feat：新增demo_frontend_agent支持前端工具交互验证

Author: Rasic2

agents/matmaster_agent/flow_agents/agent.py

@@ -119,6 +119,15 @@
     PLAN,
     UPLOAD_FILE,
 )
+from agents.matmaster_agent.sub_agents.built_in_agent.demo_frontend_agent import (
+    DemoFrontendAgent,
+)
+from agents.matmaster_agent.sub_agents.built_in_agent.demo_frontend_agent.constant import (
+    DEMO_FRONTEND_AGENT_NAME,
+)
+from agents.matmaster_agent.sub_agents.built_in_agent.demo_frontend_agent.tool import (
+    demo_frontend_tool,
+)
 from agents.matmaster_agent.sub_agents.mapping import (
     AGENT_CLASS_MAPPING,
     ALL_AGENT_TOOLS_LIST,
@@ -218,6 +227,13 @@ def after_init(self):
             instruction='',
         )
 
+        self._demo_frontend_agent = DemoFrontendAgent(
+            name=DEMO_FRONTEND_AGENT_NAME,
+            model=MatMasterLlmConfig.default_litellm_model,
+            instruction='',
+            tools=[demo_frontend_tool],
+        )
+
         self.sub_agents = [
             self.chat_agent,
             self.handle_upload_agent,
@@ -804,6 +820,10 @@ async def _run_async_impl(
                     yield quota_remaining_event
                 return
 
+            # 在需要验证的节点调用内置 demo_frontend_agent（其内挂 demo_frontend_tool，同一轮 run 内等前端回传）
+            async for demo_event in self._demo_frontend_agent.run_async(ctx):
+                yield demo_event
+
             # 上传文件特殊处理
             async for handle_upload_event in self.handle_upload_agent.run_async(ctx):
                 yield handle_upload_event

agents/matmaster_agent/flow_agents/constant.py

@@ -9,6 +9,10 @@
 MATMASTER_FLOW = 'matmaster_flow'
 MATMASTER_FLOW_PLANS = 'matmaster_flow_plans'
 MATMASTER_GENERATE_NPS = 'matmaster_generate_nps'
+# 前端 demo 工具名；ADK 只下发 function_call，等前端执行后回传 function_response 再继续
+DEMO_FRONTEND_TOOL = 'demo_frontend_tool'
+# 前端 tool 返回值写入 session.state 的 key，后续逻辑可用 ctx.session.state[DEMO_FRONTEND_TOOL_RESULT_STATE_KEY] 读取
+DEMO_FRONTEND_TOOL_RESULT_STATE_KEY = 'demo_frontend_tool_result'
 
 # matmaster_flow 展示文案，直接传给前端（正常执行无标签则传空字符串）
 EXECUTION_TYPE_LABEL_RETRY = '重试工具'

agents/matmaster_agent/flow_agents/utils.py

@@ -1,6 +1,6 @@
 import logging
 import re
-from typing import List
+from typing import Any, List, Optional
 
 from google.adk.agents import InvocationContext
 
@@ -47,6 +47,25 @@ def get_tools_list(ctx: InvocationContext, scenes: list):
         return final_tools_list
 
 
+def get_latest_frontend_tool_response(session: Any, tool_name: str) -> Optional[dict]:
+    """
+    从 session.events 中查找最近一次名为 tool_name 的前端 tool 的 function_response，
+    用于「ADK 调用前端 tool → 前端返回 → ADK 继续」的闭环。
+    若前端通过 API 已把 function_response 追加到 session，这里能拿到返回值。
+    """
+    events = getattr(session, 'events', None) or []
+    for event in reversed(events):
+        if not getattr(event, 'content', None) or not getattr(
+            event.content, 'parts', None
+        ):
+            continue
+        for part in event.content.parts:
+            fr = getattr(part, 'function_response', None)
+            if fr and getattr(fr, 'name', None) == tool_name:
+                return getattr(fr, 'response', None)
+    return None
+
+
 def get_agent_name(tool_name, sub_agents):
     try:
         target_agent_name = ALL_TOOLS[tool_name]['belonging_agent']

agents/matmaster_agent/sub_agents/built_in_agent/demo_frontend_agent/__init__.py

@@ -0,0 +1,13 @@
+from agents.matmaster_agent.sub_agents.built_in_agent.demo_frontend_agent.agent import (
+    DemoFrontendAgent,
+)
+from agents.matmaster_agent.sub_agents.built_in_agent.demo_frontend_agent.tool import (
+    set_frontend_tool_result,
+    wait_for_frontend_tool_result,
+)
+
+__all__ = [
+    'DemoFrontendAgent',
+    'set_frontend_tool_result',
+    'wait_for_frontend_tool_result',
+]

agents/matmaster_agent/sub_agents/built_in_agent/demo_frontend_agent/agent.py

@@ -0,0 +1,51 @@
+import logging
+import uuid
+from typing import AsyncGenerator
+
+from google.adk.agents import InvocationContext
+from google.adk.events import Event
+
+from agents.matmaster_agent.constant import ModelRole
+from agents.matmaster_agent.core_agents.public_agents.sync_agent import (
+    BaseSyncAgentWithToolValidator,
+)
+from agents.matmaster_agent.flow_agents.constant import (
+    DEMO_FRONTEND_TOOL,
+    DEMO_FRONTEND_TOOL_RESULT_STATE_KEY,
+)
+from agents.matmaster_agent.sub_agents.built_in_agent.demo_frontend_agent.tool import (
+    wait_for_frontend_tool_result,
+)
+from agents.matmaster_agent.utils.event_utils import (
+    context_function_call_event,
+    update_state_event,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class DemoFrontendAgent(BaseSyncAgentWithToolValidator):
+    async def _run_events(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]:
+        function_call_id = f"added_{str(uuid.uuid4()).replace('-', '')[:24]}"
+        # 在 args 里带上三 id，前端用户确认/取消后可用以请求 POST /awp/frontend-tool-result
+        yield context_function_call_event(
+            ctx,
+            self.name,
+            function_call_id,
+            DEMO_FRONTEND_TOOL,
+            ModelRole,
+            {
+                'message': '请确认',
+                'title': '前端 Demo Tool',
+                'session_id': ctx.session.id,
+                'invocation_id': ctx.invocation_id,
+                'function_call_id': function_call_id,
+            },
+        )
+        demo_result = await wait_for_frontend_tool_result(
+            ctx.session.id, ctx.invocation_id, function_call_id
+        )
+        ctx.session.state[DEMO_FRONTEND_TOOL_RESULT_STATE_KEY] = demo_result
+        yield update_state_event(
+            ctx, state_delta={DEMO_FRONTEND_TOOL_RESULT_STATE_KEY: demo_result}
+        )

agents/matmaster_agent/sub_agents/built_in_agent/demo_frontend_agent/constant.py

@@ -0,0 +1 @@
+DEMO_FRONTEND_AGENT_NAME = 'demo_frontend_agent'

agents/matmaster_agent/sub_agents/built_in_agent/demo_frontend_agent/tool.py

@@ -0,0 +1,102 @@
+"""
+前端 Demo Tool：ADK 侧注册为 FunctionTool，实际执行由前端完成，返回值在同轮 run 内回传。
+
+- 本 tool 挂在 demo_frontend_agent 的 tools 里；flow 在需要验证的节点调用该 agent 即可。
+- 前端收到 function_call 后展示卡片，用户操作后通过 API 调用 set_frontend_tool_result
+  传入 (session_id, invocation_id, function_call_id, result)，本侧 await 即返回并继续。
+"""
+
+import asyncio
+import logging
+from typing import Dict
+
+from google.adk.tools import ToolContext
+
+logger = logging.getLogger(__name__)
+
+# (session_id, invocation_id, function_call_id) -> asyncio.Future[dict]
+_pending: Dict[tuple, asyncio.Future] = {}
+_DEFAULT_TIMEOUT = 60.0
+
+
+def _key(session_id: str, invocation_id: str, function_call_id: str) -> tuple:
+    return (session_id, invocation_id, function_call_id)
+
+
+async def wait_for_frontend_tool_result(
+    session_id: str,
+    invocation_id: str,
+    function_call_id: str,
+    timeout: float = _DEFAULT_TIMEOUT,
+) -> dict:
+    """
+    在同一轮 run 内阻塞等待前端回传的 tool 结果。
+    前端通过 API 调用 set_frontend_tool_result(session_id, invocation_id, function_call_id, result) 后，本函数返回 result。
+    """
+    k = _key(session_id, invocation_id, function_call_id)
+    if k not in _pending:
+        fut: asyncio.Future = asyncio.get_event_loop().create_future()
+        _pending[k] = fut
+    try:
+        return await asyncio.wait_for(_pending[k], timeout=timeout)
+    finally:
+        _pending.pop(k, None)
+
+
+def set_frontend_tool_result(
+    session_id: str,
+    invocation_id: str,
+    function_call_id: str,
+    result: dict,
+) -> None:
+    """
+    由运行时 API 在收到前端提交的 tool 结果时调用，用于解除 wait_for_frontend_tool_result 的阻塞。
+    """
+    k = _key(session_id, invocation_id, function_call_id)
+    fut = _pending.get(k)
+    if fut is not None and not fut.done():
+        fut.set_result(result)
+        logger.info(
+            'demo_frontend_tool result set for session_id=%s invocation_id=%s function_call_id=%s',
+            session_id,
+            invocation_id,
+            function_call_id,
+        )
+    else:
+        logger.warning(
+            'demo_frontend_tool no pending future for session_id=%s invocation_id=%s function_call_id=%s',
+            session_id,
+            invocation_id,
+            function_call_id,
+        )
+
+
+async def demo_frontend_tool(
+    message: str,
+    title: str,
+    tool_context: ToolContext,
+) -> dict:
+    """
+    Demo frontend tool for verifying ADK can call a client-side tool.
+    实际执行由前端完成；本函数在此轮 run 内等待前端回传结果后返回。
+
+    Args:
+        message: 展示给用户的文案，与前端约定一致。
+        title: 卡片标题，与前端约定一致。
+
+    Returns:
+        前端回传的 dict，例如 {"confirmed": True, "value": "..."}。
+    """
+    session_id = tool_context.session.id
+    invocation_id = getattr(tool_context, 'invocation_id', None) or ''
+    function_call_id = getattr(tool_context, 'function_call_id', None) or ''
+    return await wait_for_frontend_tool_result(
+        session_id, invocation_id, function_call_id
+    )
+
+
+# 供 ADK 自动从函数签名生成 schema 的 docstring（参数与前端一致）
+demo_frontend_tool.__doc__ = (
+    'Demo frontend tool for verifying ADK can call a client-side tool. '
+    'Renders a card on the frontend (message, title); execution and return value are provided by the frontend.'
+)