Agent Starter Pack 智能体模板全览：从 ReAct 到多模态 Live API 的生产级起点-酒店常州论坛

Agent Starter Pack 智能体模板全览：从 ReAct 到多模态 Live API 的生产级起点

【免费下载链接】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 采用"自带智能体（bring your own agent）"的设计理念，在仓库 agent_starter_pack/agents 目录下预置了 8 套生产级智能体模板，覆盖 Python、Go、TypeScript、Java 四种语言生态，以及 ReAct、RAG、A2A 多智能体协作、实时多模态等主流模式。本文基于 docs/agents/overview.md 展开，并结合每个模板的源码实现深入讲解，帮助你按业务目标、语言偏好、框架选择与推理复杂度快速选定起点，并通过create命令一键生成可部署的 Google Cloud 项目。

模板总览

Agent Starter Pack 的核心思路是：不绑定单一框架，而是提供多种"开箱即用"的模板，同时保留替换框架的自由度。所有模板均为生产级起点，内置了 CI/CD、评测（evaluation）与可观测性（observability）能力。当前提供的 8 个模板如下：

模板名	说明	典型用途
`adk`	基于 Google Agent Development Kit（ADK）实现的 ReAct 基础智能体	通用对话智能体
`adk_go`	基于 ADK for Go 实现的 ReAct 基础智能体	Go 生态对话智能体
`adk_ts`	基于 ADK for TypeScript 实现的 ReAct 基础智能体	TypeScript/Node.js 对话智能体
`adk_java`	基于 ADK for Java 实现的 ReAct 基础智能体	Java 生态对话智能体
`adk_a2a`	集成 Agent2Agent（A2A）协议的 ADK 智能体	跨框架分布式智能体通信与互操作
`agentic_rag`	面向文档检索与问答的 RAG 智能体	文档搜索与知识库问答
`langgraph`	基于 LangChain LangGraph 实现的 ReAct 基础智能体	图结构对话智能体
`adk_live`	实时多模态 RAG 智能体	音频/视频/文本与知识库对话

这 8 个模板的代码分别位于 agent_starter_pack/agents 下对应的同名目录中，均以 CookieCutter 模板形式组织，字段如{{cookiecutter.agent_directory}}、{{cookiecutter.project_name}}在创建项目时会被实际值替换。

如何选择正确的模板

选择模板时，建议从以下六个维度进行决策（沿用原文档的选型框架）：

核心目标（Primary Goal）：你构建的是对话机器人、面向文档的问答系统、任务自动化网络，还是其他形态？目标决定了模板类别——通用对话选adk/langgraph，文档问答选agentic_rag，多智能体协作选adk_a2a。
编程语言（Programming Language）：多数模板基于 Python，但adk_go、adk_ts、adk_java分别提供 Go、TypeScript、Java 替代实现。若团队已有相应语言的技术栈，可直接对齐。
核心模式/框架（Core Pattern/Framework）：你偏好 Google ADK、LangChain/LangGraph，还是直接实现 RAG 等模式？Starter Pack 对多种路线均提供支持。
推理复杂度（Reasoning Complexity）：智能体是否需要复杂的规划与工具调用（如 ReAct 模式），还是更聚焦于检索与综合（如基础 RAG）？
协作需求（Collaboration Needs）：是否需要多个专业化智能体协同工作？若是，优先考虑带 A2A 协议支持的adk_a2a与langgraph。
模态（Modality）：智能体是否需要处理或响应对话之外的音频、视频？需要时选择adk_live。

模板详情

ADK 基础模板（`adk`）

该模板基于 Google ADK（Python）提供了 ReAct 智能体的最小示例，演示了 ADK 的核心概念：智能体创建与工具集成，实现推理与工具选择。

看模板源码 agent_starter_pack/agents/adk/app/agent.py：

def get_weather(query: str) -> str: """Simulates a web search. Use it get information on weather. ... """ if "sf" in query.lower() or "san francisco" in query.lower(): return "It's 60 degrees and foggy." return "It's 90 degrees and sunny." root_agent = Agent( name="root_agent", model=Gemini( model="gemini-3-flash-preview", retry_options=types.HttpRetryOptions(attempts=3), ), instruction="You are a helpful AI assistant designed to provide accurate and useful information.", tools=[get_weather, get_current_time], ) app = App( root_agent=root_agent, name="{{cookiecutter.agent_directory}}", )

从源码可以看到该模板的几个要点：

模型配置：默认使用gemini-3-flash-preview模型，并通过HttpRetryOptions(attempts=3)配置了 HTTP 重试策略（最多尝试 3 次），提升生产环境下的稳定性。
工具集成：两个模拟工具get_weather与get_current_time直接以 Python 函数形式注册进tools列表，ADK 会自动完成函数到工具描述的转换。
认证模式：模板支持两种模型访问方式——通过 CookieCutter 变量use_google_api_key区分。当不使用 API Key 时，源码通过google.auth.default()读取应用默认凭证，并设置GOOGLE_GENAI_USE_VERTEXAI=True走 Vertex AI 通道（agent_starter_pack/agents/adk/app/agent.py#L31-L40）。
可观测性扩展：模板预留了bq_analytics开关，启用后会自动初始化BigQueryAgentAnalyticsPlugin，将智能体调用日志写入 BigQuery 数据集（默认adk_agent_analytics），便于后续做对话分析与评测。

该模板最合适以下场景：

在 Google Cloud 上开始智能体开发的首个入口；
构建通用对话智能体；
学习 ADK 框架与 ReAct 模式本身。

配套的评测与测试资产也已就绪：adk模板目录下包含 agent_starter_pack/agents/adk/tests/integration/test_agent.py 集成测试，以及tests/eval/下的评测集配置（basic.evalset.json与eval_config.json），可用于验证智能体行为。

ADK 基础模板 Go 版（`adk_go`）

该模板提供与 Python 版相同核心概念（智能体创建、工具集成、ReAct 模式）的 Go 实现。适合：

在 Google Cloud 上构建智能体的 Go 开发者；
已有 Go 代码库、希望加入 AI 智能体能力的团队；
利用 Go 并发模型实现高性能部署的场景。

Go 模板的核心实现位于 agent_starter_pack/agents/adk_go/agent/agent.go，其结构同样清晰：先用GetWeatherArgs结构体通过 json schema 标签声明工具入参，再用functiontool.New()注册get_weather工具，最后通过llmagent.New()组装根智能体：

model, err := gemini.NewModel(ctx, "gemini-3-flash-preview", &genai.ClientConfig{ Backend: genai.BackendVertexAI, }) weatherTool, err := functiontool.New(functiontool.Config{ Name: "get_weather", Description: "Get the current weather for a city.", }, GetWeather) rootAgent, err := llmagent.New(llmagent.Config{ Name: "{{cookiecutter.project_name}}", Model: model, Description: "A helpful AI assistant.", Instruction: "You are a helpful AI assistant designed to provide accurate and useful information.", Tools: []tool.Tool{weatherTool}, })

Go 版还配套了 agent_starter_pack/agents/adk_go/agent/agent_test.go 单元测试。

注意：adk_go模板当前仅支持 Cloud Run 部署方式（对应部署目标见 agent_starter_pack/deployment_targets/cloud_run/go）。

ADK 基础模板 TypeScript 版（`adk_ts`）

为 TypeScript/Node.js 开发者提供的同款 ReAct 智能体。适合：

在 Google Cloud 上构建智能体的 TypeScript/Node.js 开发者；
已有 JavaScript/TypeScript 代码库的团队；
熟悉 Node.js 生态的全栈开发者。

TypeScript 实现位于 agent_starter_pack/agents/adk_ts/app/agent.ts，它使用 ADK 的FunctionTool类并借助 Zod 做参数 schema 校验：

import { FunctionTool, LlmAgent } from '@google/adk'; import { z } from 'zod'; const getWeather = new FunctionTool({ name: 'get_weather', description: 'Returns the current weather in a specified city.', parameters: z.object({ city: z.string().describe("The name of the city for which to retrieve the weather."), }), execute: ({ city }) => { return { status: 'success', report: `The weather in ${city} is sunny with a temperature of 72°F` }; }, }); export const rootAgent = new LlmAgent({ name: '{{cookiecutter.project_name | replace("-", "_")}}_agent', model: 'gemini-3-flash-preview', description: 'Tells the current weather in a specified city.', instruction: `You are a helpful assistant that tells the current weather in a city. ...`, tools: [getWeather], });

从源码看，TypeScript 版的特色在于：LlmAgent的 name 使用了replace("-", "_")过滤器确保项目名转换为合法标识符；工具参数用z.object声明运行时校验规则，比纯字符串描述更严谨。

注意：与 Go 版相同，adk_ts当前仅支持 Cloud Run 部署。

ADK 基础模板 Java 版（`adk_java`）

面向 Java 生态的 ReAct 智能体模板，集成 Spring Boot 并支持 A2A 协议。适合：

在 Google Cloud 上构建智能体的 Java 开发者；
已有 Java/Spring Boot 代码库的团队；
以 Java 为标准的企事业环境。

模板源码位于 agent_starter_pack/agents/adk_java/src/main/java/{{cookiecutter.java_package_path}}/Agent.java，配套单元测试在 agent_starter_pack/agents/adk_java/src/test/java/{{cookiecutter.java_package_path}}/unit/AgentTest.java。Java 模板遵循与adk_go/adk_ts一致的"单一根智能体 + 函数工具"模式，便于在 Maven 工程中直接运行。

注意：adk_java当前同样仅支持 Cloud Run 部署。

ADK A2A 基础模板（`adk_a2a`）

该模板将 Google ADK 与 Agent2Agent（A2A）协议集成，实现跨框架、跨语言的分布式智能体通信与互操作。它在展示 ADK 核心概念的同时，为构建分布式智能体系统提供了标准化接口。适合：

探索 A2A 协议与智能体互操作模式；
构建跨框架通信的分布式多智能体系统；
实现基于微服务的智能体架构。

对比adk_a2a与adk的源码（agent_starter_pack/agents/adk_a2a/app/agent.py），可以发现 A2A 模板的核心差异在于引入了一个"暂停等待用户"的长时工具：

def request_user_input(message: str) -> dict: """Request additional input from the user. ... Calling this tool will pause execution until the user responds. """ return {"status": "pending", "message": message} root_agent = Agent( name="root_agent", model=Gemini( model="gemini-3-flash-preview", retry_options=types.HttpRetryOptions(attempts=3), ), description="An agent that can provide information about the weather and time.", instruction="You are a helpful AI assistant designed to provide accurate and useful information.", tools=[ get_weather, get_current_time, LongRunningFunctionTool(func=request_user_input), ], )

这里的关键点是LongRunningFunctionTool：它将request_user_input包装为"长运行"工具，调用时会挂起智能体执行直至用户响应——这正是分布式多智能体交互中"任务暂停-恢复"语义的实现基础。此外adk_a2a模板的智能体增加了description字段，方便其他智能体或编排层理解其职责。对应的评测资源位于 agent_starter_pack/agents/adk_a2a/tests，与adk模板一样包含集成测试与评测集配置。

Agentic RAG 模板（`agentic_rag`）

基于 ADK 构建，实现了生产级的**检索增强生成（RAG）**与数据摄入流水线，面向文档问答场景。它允许你摄入、处理并嵌入自定义数据以提升回答相关性。核心特性包括：

自动化数据摄入流水线：将自定义文档处理为可检索的向量/索引数据；
灵活的存储选项：同时支持 Vertex AI Search 与 Vertex AI Vector Search 两种数据存储；
自定义嵌入生成：为增强语义检索生成定制 embedding；
基于检索上下文的答案综合：把检索结果作为上下文交给大模型生成答案；
基础设施即代码：通过 Terraform 部署基础设施，并可选择 Google Cloud Build 或 GitHub Actions 作为 CI/CD 运行器。

模板核心位于 agent_starter_pack/agents/agentic_rag/app/agent.py，其智能体定义会根据 CookieCutter 变量datastore_type分流：

当datastore_type = "vertex_ai_search"时，构造 Vertex AI Search 工具：

data_store_region = os.getenv("DATA_STORE_REGION", "global") data_store_id = os.getenv( "DATA_STORE_ID", "{{cookiecutter.project_name}}-collection_documents" ) data_store_path = ( f"projects/{project_id}/locations/{data_store_region}" f"/collections/default_collection/dataStores/{data_store_id}" ) vertex_search_tool = create_search_tool(data_store_path)

create_search_tool定义在 agent_starter_pack/agents/agentic_rag/app/retrievers.py，它返回VertexAiSearchTool实例；值得一提的是源码中预留了测试钩子——当环境变量INTEGRATION_TEST=TRUE时返回 mock 搜索函数，保证集成测试不依赖真实云资源。

当datastore_type = "vertex_ai_vector_search"时，模板定义一个retrieve_docs函数作为检索工具，内部调用search_collection：

def search_collection(query, collection_path, top_k=10) -> str: ... request = vectorsearch_v1beta.SearchDataObjectsRequest( parent=collection_path, semantic_search=vectorsearch_v1beta.SemanticSearch( search_text=query, search_field="text_embedding", task_type="QUESTION_ANSWERING", top_k=top_k, output_fields=vectorsearch_v1beta.OutputFields( data_fields=["question_id", "text_chunk", "full_text_md"] ), ), ) results = client.search_data_objects(request) # 将结果格式化为 "<Document N>...</Document N>" 供大模型消费

从 retrievers.py 源码可以看到检索实现的细节：使用semantic_search语义检索，task_type设为QUESTION_ANSWERING以匹配问答场景，top_k默认返回 10 条结果，并抽取text_chunk字段拼装成带文档编号的上下文块。最终智能体的 instruction 明确要求"使用提供的上下文尽力作答，若已知答案可直接回答"（agent_starter_pack/agents/agentic_rag/app/agent.py#L93-L96）。

数据摄入流水线位于 agent_starter_pack/agents/agentic_rag/data_ingestion，由data_ingestion_pipeline/components/ingest_data.py、process_data.py与pipeline.py组成，并提供submit_pipeline.py提交入口，配套 Terraform 配置在 agent_starter_pack/agents/agentic_rag/deployment/terraform（含 Vertex AI Search、Vector Search、服务账号与数据连接器脚本）。

LangGraph 基础模板（`langgraph`）

基于 LangChain 的 LangGraph 框架实现的 ReAct 智能体，支持 A2A 协议集成，可实现跨框架的分布式智能体通信。它是图结构智能体开发的绝佳起点，提供：

显式状态管理与复杂推理流的图式构建；
对智能体行为与工具编排的细粒度控制；
带 A2A 协议支持的分布式多智能体系统。

模板核心位于 agent_starter_pack/agents/langgraph/app/agent.py，实现非常精简：

from langchain.agents import create_agent from langchain_google_genai import ChatGoogleGenerativeAI from langgraph.graph.state import CompiledStateGraph llm = ChatGoogleGenerativeAI(model=LLM, temperature=0) def get_weather(query: str) -> str: """Simulates a web search. Use it get information on weather""" if "sf" in query.lower() or "san francisco" in query.lower(): return "It's 60 degrees and foggy." return "It's 90 degrees and sunny." root_agent: CompiledStateGraph = create_agent( model=llm, tools=[get_weather], system_prompt="You are a helpful assistant" )

从源码可以看到 LangGraph 模板的要点：

使用create_agent将模型与工具组合为编译后的CompiledStateGraph（状态图）；
LLM 通过ChatGoogleGenerativeAI接入，temperature=0保证问答输出的确定性；
同样支持use_google_api_key开关切换 API Key 与 Vertex AI 两种认证通道（agent_starter_pack/agents/langgraph/app/agent.py#L24-L32）。

配套的评测 notebook 位于 agent_starter_pack/agents/langgraph/notebooks/evaluating_langgraph_agent.ipynb，集成测试在 agent_starter_pack/agents/langgraph/tests/integration/test_agent.py。

Live API 模板（`adk_live`）

由 Google Gemini 驱动，基于 Vertex AI Live API 展示实时多模态对话 RAG 智能体。特性包括：

支持音频、视频与文本多模态交互；
利用工具调用（tool calling）增强能力；
通过 WebSocket 实现低延迟的双向实时通信；
生产级 Python 后端（FastAPI）与 React 前端；
内置反馈收集能力。

模板核心位于 agent_starter_pack/agents/adk_live/app/agent.py，其模型配置与前面模板最大的区别是换用了实时语音模型：

root_agent = Agent( name="root_agent", model=Gemini( model="gemini-live-2.5-flash-native-audio", retry_options=types.HttpRetryOptions(attempts=3), ), instruction="You are a helpful AI assistant designed to provide accurate and useful information.", tools=[get_weather], )

同时该模板源码在非 API Key 模式下通过vertexai.init(project=project_id, location="us-east1")显式初始化 Vertex AI，并以us-east1作为 Live API 区域（agent_starter_pack/agents/adk_live/app/agent.py#L20-L32）。

前端参考实现位于 agent_starter_pack/frontends/adk_live_react，是一个基于 React + Vite 的完整应用，包含use-live-api.ts、use-webcam.ts、use-screen-capture.ts、use-media-stream-mux.ts等 hooks，以及音频脉冲（AudioPulse）、日志面板（Logger）、侧边面板（SidePanel）、转写预览（TranscriptionPreview）等组件，可直接作为多模态前端起点。部署到 Cloud Run 的 FastAPI 入口见 agent_starter_pack/deployment_targets/cloud_run/python/{{cookiecutter.agent_directory}}/fast_api_app.py。

自定义模板

所有模板都只是起点，被设计为可自由定制。官方建议的自定义流程如下：

选择最接近需求的模板；
基于所选模板创建新的智能体实例；
熟悉代码结构，重点关注智能体逻辑（agent logic）、工具定义（tool definitions）与 UI 组件（如有）；
修改与扩展：调整提示词（prompt）、增删工具、接入不同数据源、修改推理逻辑或更新框架版本。

以adk模板为例，自定义的常见切入点包括：修改Agent(...)中的instruction调整人格与行为边界；向tools=[...]列表追加新的 Python 函数实现自定义工具；在App(...)中通过bq_analytics开关开启 BigQuery 可观测性。各模板目录内的README.md（如 agent_starter_pack/agents/adk/README.md）会注明当前模板使用的模型与工具清单，可作为定制时的参考基线。

从模板到项目：一条命令生成可部署工程

选定模板后，可以通过 CLI 的create命令将其实例化为独立项目（详见 docs/cli/create.md）。最基础的用法：

uvx agent-starter-pack create my-agent -a adk

其中-a/--agent参数既接受上述内置模板名（adk、adk_go、adk_ts、adk_java、adk_a2a、agentic_rag、langgraph、adk_live），也支持远程模板地址；省略时会弹出交互式模板列表。常用组合还包括：

# 选择部署目标与 CI/CD 运行器 uvx agent-starter-pack create my-agent -a adk -d cloud_run --cicd-runner google_cloud_build # 快速原型：跳过 CI/CD 与 Terraform 基础设施 uvx agent-starter-pack create my-agent -a agentic_rag -p --datastore vertex_ai_search

部署目标-d可选cloud_run（Cloud Run 无服务器容器）、gke（GKE Autopilot）、agent_engine（Google Cloud Agent Engine 托管平台）；--prototype会跳过.github/workflows/、deployment/（Terraform）与tests/load_test/等脚手架，之后可随时用enhance命令补齐 CI/CD（见 docs/cli/index.md）。对需要数据摄入的模板（如agentic_rag），--datastore会按vertex_ai_search或vertex_ai_vector_search自动装配对应的检索工具与 Terraform 资源。

总结

Agent Starter Pack 的 8 个模板构成了从"单语言 ReAct 入门"到"跨框架分布式协作"再到"实时多模态交互"的完整梯度：adk系列四模板（Python/Go/TS/Java）让你在自己熟悉的语言里掌握 ADK 与 ReAct 模式；adk_a2a与langgraph面向多智能体协作与互操作；agentic_rag提供了生产级的数据摄入 + 双存储检索方案；adk_live则把体验推进到音频/视频实时对话。所有模板共享同一套"模板 →create生成项目 → 定制 → 部署"的流水线，并且都内置了评测集、集成测试与可观测性配置，确保从原型到生产环境的路径平滑可控。浏览 agent_starter_pack/agents 目录即可预览每个模板的完整实现，再结合上述选型维度，即可快速定位最适合你项目的起点。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析