拓冰网站定制 
RAG Agent on Agent Platform Search用 ADK 构建零管道 RAG 检索增强问答智能体【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples本指南以core/python/rag-agent-search示例项目为主体讲解如何用 Agent Development Kit (ADK) 构建一个基于Agent Platform SearchDiscovery Engine的检索增强问答RAG智能体文档只需放入 GCS 存储桶由 GCS Data Connector 自动完成索引无需单独搭建摄取ingestion流水线。读完本文你将掌握从 Terraform 基础设施编排、.env配置、数据上传与同步到VertexAiSearchTool工具接线、ADK Playground 交互调试、集成测试与 CI/CD 同步策略的完整实战链路。项目概览一个零摄取管道的起步级 RAG 智能体core/python/rag-agent-search是一个面向 Agent Platform Search 的起步级starterRAG 示例。它的核心设计理念是检索侧的一切交给托管服务。文档落在 GCS 存储桶后由 GCS Data Connector 自动摄取进 Agent Platform Search 的数据存储data store并自动创建对应的搜索引擎search engineAgent 只需要在推理时通过VertexAiSearchTool发起检索再交给 Gemini 生成基于上下文的回答。该项目的 manifest.yaml 明确标注了它的定位type: standalone、language: python、architecture.agent: single单智能体、datasources: [external]外部数据源并由 Makefile 提供全流程命令封装。Agent 详情速览属性详情交互类型Interaction Type对话式Conversational复杂度Complexity进阶Intermediate智能体类型Agent Type单智能体Single Agent组件ComponentsTools、RAG、Terraform、Evaluation工作原理三段式结构整个示例由三部分组成各司其职app/agent.py —— ADK 智能体入口负责把检索工具挂接到 Gemini 模型上并通过App包装为可运行的 ADK 应用app/retrievers.py ——create_search_tool()工厂函数返回绑定到指定 data store 的VertexAiSearchTool在INTEGRATION_TESTTRUE时返回 mock 函数以便测试infra/terraform/ —— 一次性编排创建 docs GCS 存储桶、配置 GCS Data Connector、并在自动创建的 data store 之上建立搜索引擎。从代码结构可以推断这是一个典型的搜索工具即函数的单智能体模式Agent 不直接感知检索细节检索能力被封装成一个工具由模型按需调用。智能体入口app/agent.py 的关键接线app/agent.py 的初始化逻辑值得逐段拆解通过load_dotenv()加载.env已存在于环境中的变量优先未设置时才回填默认值项目 ID 缺省时通过google.auth.default()从 Application Default CredentialsADC解析强制设定GOOGLE_GENAI_USE_VERTEXAI True注释明确指出本 recipe 仅面向 Vertex AI显式设定可防止过期环境变量静默覆盖检测到的认证模式vertexai.init(projectproject_id, locationLOCATION)其中LOCATION us-east1是检索数据存储所在区域而LLM_LOCATION global用于 Gemini 模型data store 资源路径按projects/{project_id}/locations/{data_store_region}/collections/{data_store_collection}/dataStores/{data_store_id}拼接。模型配置上Gemini(modelLLM, retry_optionstypes.HttpRetryOptions(attempts3))为推理调用配置了 3 次 HTTP 重试系统提示词instruction要求模型尽最大能力基于提供的上下文回答并充分利用所给工具若已知答案可直接作答这正是 RAG 智能体保持检索优先、直答兜底行为的关键提示工程。最终root_agent挂载tools[vertex_search_tool]再由App(root_agentroot_agent, nameapp)包装成可被adk web加载的应用。检索工具工厂app/retrievers.py 的双模式设计app/retrievers.py 暴露create_search_tool(data_store_path)当环境变量INTEGRATION_TEST TRUE时返回一个返回固定字符串Mock search result for testing purposes.的 mock 函数使测试无需真实检索服务否则返回VertexAiSearchTool(data_store_iddata_store_path)直接绑定上文拼接出的完整资源路径。这种生产工具 / 测试替身双模式设计让同一份 agent 代码既能在本地无依赖运行也能在测试中隔离外部服务是 ADK 示例中常见的可测试性模式。基础设施编排Terraform 一键拉起检索栈infra/terraform/ 目录下是全部基础设施定义核心在 agent_platform_search.tfdocs GCS 存储桶google_storage_bucket.docs_bucket命名规则为{project_id}-{project_name}-docs启用uniform_bucket_level_access统一访问控制GCS Data Connector通过null_resourcelocal-exec调用 scripts/setup_data_connector.py传入项目、区域、collection ID、桶地址、刷新间隔与数据 schema销毁时自动调用delete_data_connector.py清理自动生成的 data store ID 解析data external data_store_id调用 scripts/get_data_store_id.py 查询 connector 自动创建的 data store —— 关键点在于 connector 会把 data store 放进它自己的 collection{project_name}-collection而非默认的default_collection搜索引擎google_discovery_engine_search_engine在解析出的 collection 上建立{project_name}-search引擎search_tier SEARCH_TIER_ENTERPRISE并把自动创建的 data store 关联进去。agent_platform_search_variables.tf 定义了三个可调参数变量默认值说明data_store_regionglobalAgent Platform Search data store 所在区域data_connector_refresh_interval86400sGCS Data Connector 周期性同步的刷新间隔默认每天一次data_connector_data_schemacontent数据 schemacontent用于非结构化文件PDF、HTML、TXTdocument用于 NDJSON/JSONLcsv用于 CSVcustom用于自定义 JSONproviders.tf 声明了google ~ 7.13.0、google-beta ~ 7.13.0、null ~ 3.2、external ~ 2.3四个 provider并定义了一个启用user_project_override的google.billing_overrideprovider 别名用于搜索引擎资源的计费项目覆盖。变量文件 vars/env.tfvars 只需填写三个值即可开始project_id your-gcp-project-id project_name rag-agent-search region us-central1从零到跑通完整 Setup 四步走按 README 的指引依次执行以下步骤第 1 步准备环境变量cp .env.example .env在.env中设置GOOGLE_CLOUD_PROJECT。若留空app/agent.py 会在导入时自动通过 ADC 解析项目 ID。第 2 步编排 data store编辑infra/terraform/vars/env.tfvars填入真实项目 ID然后执行make setup-infra该命令等价于cd infra/terraform terraform init terraform apply -var-filevars/env.tfvars会创建 GCS 桶、GCS Data Connector 与搜索引擎。第 3 步把 Terraform 输出回填到 .env连接器会自动生成data_store_id与data_store_collection其默认值可能与代码中的默认值不匹配因此必须用 Terraform 输出覆盖# 从 data_store_id / data_store_collection 输出中取值 DATA_STORE_IDdata_store_id DATA_STORE_COLLECTIONdata_store_collection此外还需按需设置DATA_STORE_REGION对应data_store_region默认global。这些值最终在 app/agent.py 中被拼进VertexAiSearchTool的完整资源路径。第 4 步上传文档并触发同步make upload-sample-data make ingestmake upload-sample-data使用gcloud storage cp把内置的 sample_data/ 上传到 docs 桶你也可以把自己的文件复制进桶make ingest读取.env中的项目/区域调用 scripts/start_connector_run.py 并带--collection-id rag-agent-search-collection --wait触发立即同步——如果不执行这一步连接器要等到每天的刷新周期才会摄取新文档。内置示例数据sample_data/product_catalog.txt 是一个虚构的Northwind Robotics产品目录例如Atlas-7 Warehouse Robot The Atlas-7 is Northwind Robotics flagship autonomous warehouse robot. - Maximum payload: 75 kg - Battery life: 14 hours per charge - Top speed: 2.5 m/s - Navigation: LiDAR visual SLAM - List price: USD 42,000配合 sample_data/support_faq.txt支持 FAQ构成一组适合演示检索问答的语料。运行ADK Playground 对话式交互基础设施与数据就绪后一键启动本地 Playgroundmake install make playgroundmake install执行uv sync --dev --extra eval安装依赖含评估所需 extramake playground执行uv run adk web . --port 8501 --reload_agents在打开的 Web 界面中选择app文件夹然后就可以提问例如What is the payload and battery life of the Atlas-7 robot?此时智能体会调用VertexAiSearchTool在 data store 中检索相关片段Gemini 基于返回的上下文组织出引用文档事实的回答。测试Mock 检索 真实模型调用执行make test等价于uv sync --dev INTEGRATION_TESTTRUE uv run pytest tests/integration运行集成测试。需要理解其中的关键设计检索器被 mockINTEGRATION_TESTTRUE时create_search_tool返回假函数但 agent 仍会发起真实的 Gemini 调用因此要求本机具备 Google Cloud 凭据ADC与 Vertex AI 访问权限没有凭据时测试会被跳过而不是报错——这一点由 tests/integration/test_agent.py 中的_has_gcp_credentials()检测与pytest.mark.skipif保证测试逻辑使用InMemorySessionService创建会话用Runner以StreamingMode.SSE流式运行 agent并断言事件流中至少存在一条包含文本内容的消息。另有 tests/test_runnability.py 提供可运行性测试在 patch 掉vertexai.init、预置假项目 ID 的前提下导入app.agent断言root_agent与app均能成功实例化从而在无任何云依赖的环境中验证代码可编译、可装配。仓库还自带评估配置 tests/eval/eval_config.yaml 与数据集 tests/eval/datasets/basic-dataset.json用于后续的离线质量评估。CI/CD 与文档保鲜连接器驱动 按需强制同步这些示例默认不捆绑部署流水线文档的新鲜度由 GCS Data Connector 负责它会按data_connector_refresh_interval默认每天一次重新同步 GCS 桶中的内容。若希望文档变更立即生效可在 CI或本地中调用make ingest强制触发一次同步。部署智能体时请走 ADK 原生路径而不是已废弃的 agent-starter-pack 工具链例如uv run adk deploy cloud_run . # 或 adk deploy agent_engine延伸阅读想用向量检索怎么办本项目使用的是 Agent Platform SearchDiscovery Engine托管的语义检索。如果你更关注向量检索方案仓库提供了两个可对照的变体core/python/rag-vector-search —— Vector Search 2.0 变体检索后端基于向量索引contrib/python/multiformat-hybrid-rag —— 面向生产的混合检索语义 关键词系统。对比之下可以清晰看到本示例的取舍把索引、摄取、同步全部托管化以最小的运维成本换回一个开箱即用的对话式 RAG 智能体非常适合作为接入 Agent Platform Search 的起点模板。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 RAG Agent on Agent Platform Search：用 ADK 构建零管道 RAG 检索增强问答智能体
RAG Agent on Agent Platform Search用 ADK 构建零管道 RAG 检索增强问答智能体【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples本指南以core/python/rag-agent-search示例项目为主体讲解如何用 Agent Development Kit (ADK) 构建一个基于Agent Platform SearchDiscovery Engine的检索增强问答RAG智能体文档只需放入 GCS 存储桶由 GCS Data Connector 自动完成索引无需单独搭建摄取ingestion流水线。读完本文你将掌握从 Terraform 基础设施编排、.env配置、数据上传与同步到VertexAiSearchTool工具接线、ADK Playground 交互调试、集成测试与 CI/CD 同步策略的完整实战链路。项目概览一个零摄取管道的起步级 RAG 智能体core/python/rag-agent-search是一个面向 Agent Platform Search 的起步级starterRAG 示例。它的核心设计理念是检索侧的一切交给托管服务。文档落在 GCS 存储桶后由 GCS Data Connector 自动摄取进 Agent Platform Search 的数据存储data store并自动创建对应的搜索引擎search engineAgent 只需要在推理时通过VertexAiSearchTool发起检索再交给 Gemini 生成基于上下文的回答。该项目的 manifest.yaml 明确标注了它的定位type: standalone、language: python、architecture.agent: single单智能体、datasources: [external]外部数据源并由 Makefile 提供全流程命令封装。Agent 详情速览属性详情交互类型Interaction Type对话式Conversational复杂度Complexity进阶Intermediate智能体类型Agent Type单智能体Single Agent组件ComponentsTools、RAG、Terraform、Evaluation工作原理三段式结构整个示例由三部分组成各司其职app/agent.py —— ADK 智能体入口负责把检索工具挂接到 Gemini 模型上并通过App包装为可运行的 ADK 应用app/retrievers.py ——create_search_tool()工厂函数返回绑定到指定 data store 的VertexAiSearchTool在INTEGRATION_TESTTRUE时返回 mock 函数以便测试infra/terraform/ —— 一次性编排创建 docs GCS 存储桶、配置 GCS Data Connector、并在自动创建的 data store 之上建立搜索引擎。从代码结构可以推断这是一个典型的搜索工具即函数的单智能体模式Agent 不直接感知检索细节检索能力被封装成一个工具由模型按需调用。智能体入口app/agent.py 的关键接线app/agent.py 的初始化逻辑值得逐段拆解通过load_dotenv()加载.env已存在于环境中的变量优先未设置时才回填默认值项目 ID 缺省时通过google.auth.default()从 Application Default CredentialsADC解析强制设定GOOGLE_GENAI_USE_VERTEXAI True注释明确指出本 recipe 仅面向 Vertex AI显式设定可防止过期环境变量静默覆盖检测到的认证模式vertexai.init(projectproject_id, locationLOCATION)其中LOCATION us-east1是检索数据存储所在区域而LLM_LOCATION global用于 Gemini 模型data store 资源路径按projects/{project_id}/locations/{data_store_region}/collections/{data_store_collection}/dataStores/{data_store_id}拼接。模型配置上Gemini(modelLLM, retry_optionstypes.HttpRetryOptions(attempts3))为推理调用配置了 3 次 HTTP 重试系统提示词instruction要求模型尽最大能力基于提供的上下文回答并充分利用所给工具若已知答案可直接作答这正是 RAG 智能体保持检索优先、直答兜底行为的关键提示工程。最终root_agent挂载tools[vertex_search_tool]再由App(root_agentroot_agent, nameapp)包装成可被adk web加载的应用。检索工具工厂app/retrievers.py 的双模式设计app/retrievers.py 暴露create_search_tool(data_store_path)当环境变量INTEGRATION_TEST TRUE时返回一个返回固定字符串Mock search result for testing purposes.的 mock 函数使测试无需真实检索服务否则返回VertexAiSearchTool(data_store_iddata_store_path)直接绑定上文拼接出的完整资源路径。这种生产工具 / 测试替身双模式设计让同一份 agent 代码既能在本地无依赖运行也能在测试中隔离外部服务是 ADK 示例中常见的可测试性模式。基础设施编排Terraform 一键拉起检索栈infra/terraform/ 目录下是全部基础设施定义核心在 agent_platform_search.tfdocs GCS 存储桶google_storage_bucket.docs_bucket命名规则为{project_id}-{project_name}-docs启用uniform_bucket_level_access统一访问控制GCS Data Connector通过null_resourcelocal-exec调用 scripts/setup_data_connector.py传入项目、区域、collection ID、桶地址、刷新间隔与数据 schema销毁时自动调用delete_data_connector.py清理自动生成的 data store ID 解析data external data_store_id调用 scripts/get_data_store_id.py 查询 connector 自动创建的 data store —— 关键点在于 connector 会把 data store 放进它自己的 collection{project_name}-collection而非默认的default_collection搜索引擎google_discovery_engine_search_engine在解析出的 collection 上建立{project_name}-search引擎search_tier SEARCH_TIER_ENTERPRISE并把自动创建的 data store 关联进去。agent_platform_search_variables.tf 定义了三个可调参数变量默认值说明data_store_regionglobalAgent Platform Search data store 所在区域data_connector_refresh_interval86400sGCS Data Connector 周期性同步的刷新间隔默认每天一次data_connector_data_schemacontent数据 schemacontent用于非结构化文件PDF、HTML、TXTdocument用于 NDJSON/JSONLcsv用于 CSVcustom用于自定义 JSONproviders.tf 声明了google ~ 7.13.0、google-beta ~ 7.13.0、null ~ 3.2、external ~ 2.3四个 provider并定义了一个启用user_project_override的google.billing_overrideprovider 别名用于搜索引擎资源的计费项目覆盖。变量文件 vars/env.tfvars 只需填写三个值即可开始project_id your-gcp-project-id project_name rag-agent-search region us-central1从零到跑通完整 Setup 四步走按 README 的指引依次执行以下步骤第 1 步准备环境变量cp .env.example .env在.env中设置GOOGLE_CLOUD_PROJECT。若留空app/agent.py 会在导入时自动通过 ADC 解析项目 ID。第 2 步编排 data store编辑infra/terraform/vars/env.tfvars填入真实项目 ID然后执行make setup-infra该命令等价于cd infra/terraform terraform init terraform apply -var-filevars/env.tfvars会创建 GCS 桶、GCS Data Connector 与搜索引擎。第 3 步把 Terraform 输出回填到 .env连接器会自动生成data_store_id与data_store_collection其默认值可能与代码中的默认值不匹配因此必须用 Terraform 输出覆盖# 从 data_store_id / data_store_collection 输出中取值 DATA_STORE_IDdata_store_id DATA_STORE_COLLECTIONdata_store_collection此外还需按需设置DATA_STORE_REGION对应data_store_region默认global。这些值最终在 app/agent.py 中被拼进VertexAiSearchTool的完整资源路径。第 4 步上传文档并触发同步make upload-sample-data make ingestmake upload-sample-data使用gcloud storage cp把内置的 sample_data/ 上传到 docs 桶你也可以把自己的文件复制进桶make ingest读取.env中的项目/区域调用 scripts/start_connector_run.py 并带--collection-id rag-agent-search-collection --wait触发立即同步——如果不执行这一步连接器要等到每天的刷新周期才会摄取新文档。内置示例数据sample_data/product_catalog.txt 是一个虚构的Northwind Robotics产品目录例如Atlas-7 Warehouse Robot The Atlas-7 is Northwind Robotics flagship autonomous warehouse robot. - Maximum payload: 75 kg - Battery life: 14 hours per charge - Top speed: 2.5 m/s - Navigation: LiDAR visual SLAM - List price: USD 42,000配合 sample_data/support_faq.txt支持 FAQ构成一组适合演示检索问答的语料。运行ADK Playground 对话式交互基础设施与数据就绪后一键启动本地 Playgroundmake install make playgroundmake install执行uv sync --dev --extra eval安装依赖含评估所需 extramake playground执行uv run adk web . --port 8501 --reload_agents在打开的 Web 界面中选择app文件夹然后就可以提问例如What is the payload and battery life of the Atlas-7 robot?此时智能体会调用VertexAiSearchTool在 data store 中检索相关片段Gemini 基于返回的上下文组织出引用文档事实的回答。测试Mock 检索 真实模型调用执行make test等价于uv sync --dev INTEGRATION_TESTTRUE uv run pytest tests/integration运行集成测试。需要理解其中的关键设计检索器被 mockINTEGRATION_TESTTRUE时create_search_tool返回假函数但 agent 仍会发起真实的 Gemini 调用因此要求本机具备 Google Cloud 凭据ADC与 Vertex AI 访问权限没有凭据时测试会被跳过而不是报错——这一点由 tests/integration/test_agent.py 中的_has_gcp_credentials()检测与pytest.mark.skipif保证测试逻辑使用InMemorySessionService创建会话用Runner以StreamingMode.SSE流式运行 agent并断言事件流中至少存在一条包含文本内容的消息。另有 tests/test_runnability.py 提供可运行性测试在 patch 掉vertexai.init、预置假项目 ID 的前提下导入app.agent断言root_agent与app均能成功实例化从而在无任何云依赖的环境中验证代码可编译、可装配。仓库还自带评估配置 tests/eval/eval_config.yaml 与数据集 tests/eval/datasets/basic-dataset.json用于后续的离线质量评估。CI/CD 与文档保鲜连接器驱动 按需强制同步这些示例默认不捆绑部署流水线文档的新鲜度由 GCS Data Connector 负责它会按data_connector_refresh_interval默认每天一次重新同步 GCS 桶中的内容。若希望文档变更立即生效可在 CI或本地中调用make ingest强制触发一次同步。部署智能体时请走 ADK 原生路径而不是已废弃的 agent-starter-pack 工具链例如uv run adk deploy cloud_run . # 或 adk deploy agent_engine延伸阅读想用向量检索怎么办本项目使用的是 Agent Platform SearchDiscovery Engine托管的语义检索。如果你更关注向量检索方案仓库提供了两个可对照的变体core/python/rag-vector-search —— Vector Search 2.0 变体检索后端基于向量索引contrib/python/multiformat-hybrid-rag —— 面向生产的混合检索语义 关键词系统。对比之下可以清晰看到本示例的取舍把索引、摄取、同步全部托管化以最小的运维成本换回一个开箱即用的对话式 RAG 智能体非常适合作为接入 Agent Platform Search 的起点模板。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考