ADK Live Agent 实战指南基于 Gemini Live 音频模型构建实时多模态对话智能体【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack本文聚焦 agent-starter-pack 仓库中的ADK Live Agent模式agent_starter_pack/agents/adk_live/README.md介绍如何基于 Google ADK 与 Gemini Live 音频模型构建支持音频、视频、文本三种交互方式且具备原生工具调用能力的实时对话智能体。读完本文你将掌握后端 Agent 的声明式定义、前端 Web 控制台的 WebSocket 通信机制以及从本地运行到部署 Cloud Run / Agent Engine 的完整实践路径。一、模式概览什么是 ADK Live AgentADK Live Agent 是 agent-starter-pack 中面向实时对话场景的智能体模板。与普通基于文本的 Agent 不同它借助 Gemini 的 Live 音频模型实现低延迟、可打断的流式对话支持用户以语音、摄像头画面、屏幕共享和文本与智能体交互同时保留 ADK 的原生工具调用Tool Calling能力——智能体可以在对话过程中自主调用后端注册的函数并返回结构化结果。从仓库目录结构看该模式由两大核心组件构成Python 后端app/基于 ADK 构建的 Agent使用 Gemini Live 音频模型内置工具调用能力支持部署到 Cloud Run 与 Agent EngineReact 前端agent_starter_pack/frontends/adk_live_react/一个 Web 控制台通过浏览器采集麦克风、摄像头与屏幕画面经 WebSocket 与后端实时双向通信实现「说话-回复」式的语音交互体验。README 中给出的典型验证场景是运行应用后点击播放按钮建立连接然后对智能体说 Whats the weather like in San Francisco?即可直观看到工具调用Tool Calling的完整执行链路。二、后端实现源码解析后端核心代码位于 app/agent.py全文约 60 行完整展示了 ADK 声明式 Agent 的编写范式。2.1 Agent 定义Live 音频模型 原生工具调用from google.adk.agents import Agent from google.adk.apps import App from google.adk.models import Gemini from google.genai import types root_agent Agent( nameroot_agent, modelGemini( modelgemini-live-2.5-flash-native-audio, retry_optionstypes.HttpRetryOptions(attempts3), ), instructionYou are a helpful AI assistant designed to provide accurate and useful information., tools[get_weather], ) app App(root_agentroot_agent, name{{cookiecutter.agent_directory}})关键点说明model参数指定模型为gemini-live-2.5-flash-native-audio这是支持原生音频输入输出的 Gemini Live 系列模型是实时语音对话能力的基础retry_optionstypes.HttpRetryOptions(attempts3)为模型调用配置了最多 3 次的重试策略提升弱网等不稳定场景下的可用性instruction定义系统提示词约束智能体的回答风格与行为边界tools[get_weather]将 Python 函数直接注册为 Agent 的原生工具ADK 会自动完成函数签名解析、参数注入与结果回传App(root_agent..., name...)将 Agent 包装为可被服务化加载的应用对象name使用 cookiecutter 模板变量{{cookiecutter.agent_directory}}即生成项目时传入的 Agent 目录名。2.2 工具函数get_weatherdef get_weather(query: str) - str: Simulates a web search. Use it get information on weather. Args: query: A string containing the location to get weather information for. Returns: A string with the simulated weather information for the queried location. if sf in query.lower() or san francisco in query.lower(): return Its 60 degrees and foggy. return Its 90 degrees and sunny.这是一个模拟天气查询工具当用户问到旧金山含缩写 sf时返回60 度、有雾其他地点统一返回90 度、晴天。它的作用是演示 ADK 的完整工具调用闭环——LLM 从对话中提取参数、调用函数、将返回值组织成自然语言回复。README 中建议的 Whats the weather like in San Francisco? 提问正是为了触发这一链路。2.3 Vertex AI 认证分支agent.py 中还包含一段基于 cookiecutter 条件变量的认证逻辑{%- if not cookiecutter.use_google_api_key %} import os import google.auth import vertexai _, project_id google.auth.default() os.environ[GOOGLE_CLOUD_PROJECT] project_id os.environ[GOOGLE_CLOUD_LOCATION] us-east1 os.environ[GOOGLE_GENAI_USE_VERTEXAI] True vertexai.init(projectproject_id, locationus-east1) {%- endif %}当生成项目时未使用 Google API Keyuse_google_api_key为 False时代码会通过 Application Default Credentials 自动获取 GCP 项目 ID设置us-east1区域并开启GOOGLE_GENAI_USE_VERTEXAI环境变量以切换到 Vertex AI 通道最终调用vertexai.init()完成初始化。这意味着同一份模板既可以配合 API Key 本地快速体验也可以在 GCP 上以 Vertex AI 方式生产运行。2.4 包导出app/init.py 仅做一件事from .agent import app __all__ [app]将app对象作为包级导出便于部署层Cloud Run 的 FastAPI 应用、Agent Engine 的入口以from app import app的形式加载。三、单元测试工具函数的可验证性app/tests/unit/test_dummy.py 为工具函数提供了三个单元测试覆盖正常输入、缩写输入与兜底分支def test_get_weather_san_francisco() - None: result get_weather(Whats the weather in San Francisco?) assert result Its 60 degrees and foggy. def test_get_weather_san_francisco_abbreviation() - None: result get_weather(weather in sf) assert result Its 60 degrees and foggy. def test_get_weather_other_location() - None: result get_weather(Whats the weather in New York?) assert result Its 90 degrees and sunny.这三个用例分别验证了完整地名命中、大小写不敏感的缩写命中query.lower()保证了这一点、以及未匹配任何规则时的默认返回。测试文件顶部注释说明这里适用于测试业务逻辑、Agent 功能与数据处理等核心组件为后续扩展 Agent 行为测试提供了挂载点。四、前端 Web 控制台源码解析前端位于 agent_starter_pack/frontends/adk_live_react/frontend/基于 React 18 TypeScript Vite 构建见 package.json依赖包括react、react-dom、sass、react-select、zustand、eventemitter3以及google/generative-ai类型定义。核心脚本为devvite 开发服务器、buildtsc vite 构建、testvitest。4.1 WebSocket 客户端MultimodalLiveClientsrc/utils/multimodal-live-client.ts 是整个前端的通信中枢它基于EventEmitter封装了一个 WebSocket 客户端核心职责包括默认连接地址未显式传入 URL 时默认使用${window.location.protocol https: ? wss: : ws:}//${window.location.host}/ws即与页面同源下的/ws路径并自动适配 HTTPS/WSS连接握手connect()建立 WebSocket 后立即发送 setup 消息携带user_id默认default_user与run_id默认crypto.randomUUID()生成用于后端会话追踪消息分发通过事件机制向外发射open、setupcomplete、close、audio、content、interrupted、toolcall、turncomplete以及 ADK 特有的inputtranscription用户语音转写、outputtranscription智能体语音转写、adkevent等事件音频发送节流sendRealtimeInput()在连接建立初期以 300ms 间隔发送前 10 个音频块RAMPUP_CHUNKS随后切换到 125ms约 8 块/秒的常规速率避免连接建立瞬间打爆队列实时输入支持以 base64 的audio/pcm16kHz 采样和image/jpeg块发送麦克风与视频帧首个内容块会自动包装为{user_id, live_request}格式供后端识别ADK 事件处理解析后端的input_transcription、output_transcription、content.parts中的function_call转译为 toolcall 日志、audio/*内联数据解码为ArrayBuffer后触发audio事件交给扬声器播放。4.2 React 集成层src/hooks/use-live-api.ts将客户端生命周期封装为useLiveAPIHook管理connected状态与volume音量并通过AudioStreamer将服务端返回的 PCM16 音频数据写入扬声器同时注册vumeter-out音量计 Worklet 驱动界面音量动画src/contexts/LiveAPIContext.tsx通过 React Context 向全组件树提供useLiveAPIContext()任一组件可访问client、connect、disconnect、connected、volumesrc/App.tsx判断开发模式端口 8501 时认为前端运行在本地开发服务器默认连接同机:8000后端并用LiveAPIProvider包裹控制台与视频区。4.3 控制台界面SidePanelsrc/components/side-panel/SidePanel.tsx 实现了完整的交互控制台主要功能包括连接设置Connection Settings可手动修改 Server URL占位符ws://localhost:8000/与 User ID播放/暂停按钮即 README 提到的 play 按钮点击触发connect()/disconnect()连接成功后状态切换为 Streaming并自动聚焦回按钮麦克风开关AudioRecorder以audio/pcm;rate16000格式采集音频并通过client.sendRealtimeInput()上传静音时停止采集视频能力通过useWebcam、useScreenCapture两个 Hook 采集摄像头与屏幕流以 0.5 fps 的帧率将缩小 25% 的画面编码为 JPEG base64 发送日志控制台提供 Conversations / Tool Use / All 三种过滤粒度实时展示连接、音频缓冲、工具调用、转写等日志并在新增日志时自动滚动到底部文本输入支持打字对话与 Enter 发送反馈提交向{serverUrl}/feedback提交score、text、run_id、user_id、log_type: feedback用于采集对话质量评分音频脉冲指示底部以AI Speaking... / AI Ready / Not connected与音量动画实时反馈智能体语音播放状态。五、端到端运行与体验流程综合 README 与源码完整的本地体验路径如下按仓库文档生成或加载 adk_live 项目cookiecutter 变量会决定是否走 Vertex AI 认证分支启动 Python 后端暴露 WebSocket 服务默认:8000端口与前端 App.tsx 中的开发模式约定一致在frontend目录执行npm install后运行npm run dev启动 Vite 开发服务器浏览器打开控制台点击play按钮建立 WebSocket 连接等待setupcomplete事件前端据此切换为 Streaming 状态即可开始对话尝试说 Whats the weather like in San Francisco?观察日志面板中的工具调用Tool Use记录与智能体的语音回复验证get_weather的完整调用链路。体验过程中可随时通过连接设置中的 Server URL / User ID 调整后端地址与用户标识或使用摄像头、屏幕共享按钮切换视频输入源观察智能体对多模态输入的响应。六、部署支持README 明确声明该模式支持部署到Cloud Run与Agent Engine。从仓库的部署目标目录可以看到对应的模板实现agent_starter_pack/deployment_targets/cloud_run/python/提供 FastAPI 应用入口fast_api_app.py、Dockerfile 与 Terraform 服务配置agent_starter_pack/deployment_targets/agent_engine/python/提供 Agent Engine 应用入口agent_engine_app.py与配套部署工具。这两个部署目标均在仓库搜索中被确认与 adk_live 相关说明实时对话应用可以通过统一的基础模板base_templates/python/快速生成再叠加不同部署目标完成生产化。结合 agent.py 中的 Vertex AI 认证分支生产环境建议以 Vertex AI 方式运行以获取托管凭据与项目级权限管理。七、当前状态与后续规划README 明确标注该模式仍在积极开发中under active development已规划但尚未落地的能力包括可观测性Observability计划实现完整的监控与链路追踪Tracing能力负载测试Load Testing计划集成负载测试能力。需要说明的是以上两项在撰写本文时属于规划内容而非已实现功能如果你需要生产级别的可观测性或压测能力可以关注仓库后续更新或参考仓库中其他已具备相关能力的 Agent 模式如 agent_starter_pack/agents/ 下的其他实现。八、延伸学习资源README 末尾列举了若干与 Gemini Multimodal Live API 相关的学习资源主题包括Project PastraGemini Multimodal Live API 综合开发指南、ADK Samples 中的实时对话 Agent 全栈模板、Google Cloud Multimodal Live API 的示例与演示集合、Gemini 2 Cookbook 的实战教程以及 Multimodal Live API Web Console交互式 React 调试界面。本仓库的前端实现与最后一个主题高度同源可作为深入研究 Multimodal Live API 协议的起点原文附带的资源链接为外部地址此处不再赘述。总结ADK Live Agent 模式用极简的代码展示了实时多模态对话智能体的完整技术栈后端以 ADK 声明式 Agent Gemini Live 原生音频模型 工具调用为核心前端以 WebSocket 多模态客户端 React 控制台为交互载体并通过 cookiecutter 模板在 API Key 直连与 Vertex AI 生产认证之间自由切换。对于希望快速构建语音助手、实时客服、多模态交互演示等场景的开发者而言这是一个可以直接复用并在此基础上扩展的起点。【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考