基于 LangGraph 的生成式 AI 智能体设计模式实践Gen AI Experience Concierge 全解析【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai本文基于仓库 gemini/agents/genai-experience-concierge/README.md 及其配套源码撰写介绍一个以 LangGraph 为核心编排框架、面向 Google Cloud 生成式 AI 场景的智能体Agent设计模式集合。文章涵盖四种可直接复用的 Agent 架构模式Guardrail Classifier、Semantic Router、Function Calling、Task Planner、自建 LangGraph Cloud API 兼容服务端的原理以及从本地 Quickstart 到 Terraform 一键端到端部署的完整路径。读完本文你将掌握在自托管环境FastAPI Streamlit中构建、调试与部署 LangGraph 多智能体应用的方法论与工程细节。项目定位与核心思想Gen AI Experience Concierge 是一套智能体设计模式Agent Design Patterns的参考实现集合所有设计模式均使用LangGraph 框架完成智能体编排Orchestration与会话管理Session Management。它解决的工程问题是在真实业务中Agent 应用往往需要组合多个智能体、接入多种工具并保证会话状态可控而这些能力需要一套可复用、可部署、可观测的实现范式。整个项目由两大组成部分协同工作独立 Notebook位于 agent-design-patterns/每个模式配套一个自包含的 Notebook如 guardrail-classifier.ipynb用于在无需部署任何服务端的前提下交互式地搭建与理解每种 Agent 模式。可一键部署的 Demo 应用将上述模式打包为 click-to-deploy 应用使用FastAPI承载 LangGraph Agent 服务端并用Streamlit提供前端演示界面。Agent 服务端兼容 LangGraph Cloud API Spec 目录。仓库结构速览部署型 Demo 的源码采用前后端分离 基础设施即代码的组织方式langgraph-demo │ ├── backend ; 后端 Agent 服务端 │ ├── concierge │ │ ├── agents ; 所有 Agent 定义 │ │ ├── langgraph_server ; LangGraph - fastapi.APIRouter 适配器 │ │ ├── nodes ; 所有 LangGraph 节点定义 │ │ │ └── task_planning │ │ │ └── ops │ │ └── tools ; LLM 工具定义 │ └── notebooks ; 与 Agent 交互的 Notebook │ ├── frontend ; 前端 Streamlit 服务端 │ └── concierge_ui │ └── agents ; 每个 Agent 的聊天处理逻辑 │ └── terraform ; 部署所需的基础设施代码其中 backend 与 frontend 各自包含独立的 README提供更深入的本机环境搭建说明。从源码结构看server.py服务端在启动时依次加载了 5 个 Agent基础 Gemini 聊天、带 Guardrails 的聊天、Function Calling、Semantic Router、Task Planner并将每个 Agent 通过build_agent_router注册为独立路由前缀路由前缀标签对应 Agent/geminiGemini Chat基础 Gemini 聊天 Agent/gemini-with-guardrailsGemini with GuardrailsGuardrail Classifier Agent/function-callingFunction CallingFunction Calling Agent/semantic-routerSemantic RouterSemantic Router Agent/task-plannerTask PlannerTask Planner Agent四种核心 Agent 设计模式以下四种模式是该项目的主体内容均可在 agent-design-patterns/README.md 中找到背景说明与架构图并有对应的独立 Notebook 与 Demo 源码模式独立 NotebookDemo 源码Guardrail Classifier Agentguardrail-classifier.ipynbguardrails.pySemantic Router Agentsemantic-router.ipynbsemantic_router.pyFunction Calling Agentfunction-calling.ipynbfunction_calling.pyTask Plannertask-planner.ipynbtask_planner.py模式一Guardrail Classifier护栏分类器在构建 Agentic 应用时仅依赖模型内置的 Safety Settings 往往不够通常还需要额外的护栏来约束交互范围避免离题off-topic或对抗性adversarial查询。该模式实现了一个基于 LLM 的护栏分类器对每条用户输入判定回答或拒绝。实现上存在两种路线在计算成本与延迟之间取舍顺序执行该 Demo 采用先生成分类结果再生成回复。如果判定为拒绝则直接跳过回复生成阶段因此延迟更高但成本更低。并行执行分类器与回复生成同时进行延迟更低但由于即便要拦截也需启动生成成本更高且护栏可以在判定被拦截时更快地打断生成。该 Demo 采用第一种方案顺序执行若你的场景对延迟敏感可自行修改为并行执行。在源码层面guardrails.py 定义了一个面向 Cymbal 零售公司的护栏系统提示词明确给出分类任务、使用场景与拦截标准Blocking Criteria例如输入与用例涵盖的主题无关输入试图诱导不当回复或篡改指令讨论 Cymbal 的具体员工、竞争对手企业、公众人物讨论法律或有争议的话题要求生成创意性回复、玩笑或任何不专业的语气。值得注意的是护栏系统提示词也特别说明与零售无关但属于正常对话的输入仍然是合法的Appropriate conversational inputs are valid even if they are not specifically about retail以避免护栏过度拦截。在图的编排上guardrails.py整个 Agent 由 3 个节点构成guardrails入口→ 判定放行则进入chat→ 最后统一进入save-turn保存会话若护栏判定拦截则guardrails节点直接跳转save-turn跳过回复生成。save-turn节点把当前轮次写回会话状态实现多轮记忆。这也印证了顺序执行方案中护栏拦截即可避免后续生成成本的核心收益。模式二Semantic Router语义路由器语义路由器模式用于从一组候选专家 Agent 中动态挑选最合适的一个来响应用户输入。该 Demo 使用基于 LLM 的意图检测分类器将每条用户查询路由到以下三种目标之一见 semantic_router.py 中的RouterTarget枚举Customer Support Assistant退货、政策、投诉、FAQ、升级等客服类问题Conversational Retail Search Assistant寒暄/日常对话以及 Cymbal 零售商品、门店、库存含实时数据的讨论Unsupported与上述 Agent 均无关的离题查询。路由系统提示词semantic_router.py中包含一组 few-shot 示例用于稳定分类行为例如询问商品如 Is the Meinl Byzance Jazz Ride 18 available?→ Retail Search发起退货 → Customer Support地球离太阳多远→ Unsupported。关键设计要点Demo 中的两位专家客服与零售搜索被简化为仅含系统提示词的 Gemini 调用但它们代表的是任意可以与其他子 Agent 共享会话历史的执行体。例如真实的客服 Agent 可能基于 Contact Center as a ServiceCCaaS实现而零售搜索助手可以基于 Gemini 部署在 Cloud Run 上。因此语义路由器层可以作为一个 Facade门面用统一接口屏蔽多个截然不同的 Agent 后端这也是该模式最具工程价值的应用场景。在图结构上semantic_router.pysemantic-router节点作为入口通过class_node_mapping把分类结果映射到customer-service、retail-search、unsupported三个聊天节点各节点最终统一汇聚到save-turn。路由节点还通过max_router_turn_history控制用于意图判定的历史轮数默认 3见 settings.py因为多轮对话中的意图往往依赖上下文。模式三Function Calling函数调用函数调用是实现结构化检索增强生成RAG以及让 LLM 在现实世界采取行动的流行技术。该 Demo 面向一家虚构公司 Cymbal Retail利用一组函数声明在合成的 BigQuery 数据集上执行受控查询。数据集包含商品、门店位置以及商品-门店库存三类信息。其核心价值在于用受控的结构化查询取代任意的 NL2SQL函数声明让 LLM 生成结构化的查询参数从而以安全、受控的方式查询数据库而 NL2SQL 虽然更灵活但会生成并执行任意 SQL存在更大的安全风险。该模式的 Retail Search Assistant 覆盖三类用例每类都支持丰富的过滤与排序维度门店搜索Store Search可按门店名称、搜索半径、商品 ID、结果数量过滤商品搜索Product Search可按门店 ID、价格区间、结果数量过滤并按商品名称/描述的语义相似度排序指定商品-门店对的库存查询Inventory Search。工具层由三个文件组成find_stores.py、find_products.py、find_inventory.py。每个工具由两部分构成*_fdgenai_types.FunctionDeclaration声明与generate_*_handler可调用的执行器在 function_calling.py 的load_function_specs中打包为FunctionSpec列表注入聊天节点。以 find_products.py 为例其函数声明包含参数max_results返回结果数上限默认 3硬上限MAX_PRODUCT_RESULTS 10product_search_query用于语义相似度检索的文本查询可匹配名称、描述、品牌、类别store_ids必须持有该商品的门店 ID 列表min_price/max_price价格下限 / 上限美元。该工具内部实现了两条 SQL 路径无语义查询时走_build_query_without_vector_search基于库存表INNER JOIN做门店过滤并支持IFNULL(sale_price, list_price)的价格区间过滤有语义查询时走_build_query_with_vector_search调用 BigQueryVECTOR_SEARCHML.GENERATE_TEXT_EMBEDDING对商品名/描述做语义相似度检索top_k取max_results * 3以留出后置过滤余量再叠加价格与门店过滤条件。这是 BQML 内建 Embedding 能力在 Agent 工具中的典型落地。在流式体验上聊天节点chat.py通过utils.generate_content_stream流式生成内容并将文本、function_call、function_response三类分片实时通过stream_writer推送出去前端因此可以看到调用工具 → 拿到结果 → 生成最终回复的完整过程。注意运行该 Demo 或独立 Notebook 前必须先创建 Cymbal Retail 数据集见下文创建 Cymbal Retail 数据集。模式四Task Planner任务规划器Task Planner 是一种与 Deep Research 类似的多智能体架构适用于需要更复杂推理、规划与多工具协同的任务。它由三个核心 Agent 构成Planner规划器接收用户输入后要么直接回应简单问题如 Hi要么生成一份研究计划包括待执行任务列表Executor执行器接收计划使用自己的工具执行每个任务并用执行结果更新计划Reflector反思器审查已执行的计划要么生成最终回复给用户要么生成新计划并跳回第 2 步形成 规划 → 执行 → 反思 → 再规划 的循环。图结构在 task_planner.py 中一目了然planner为入口简单查询直接 gotosave-turn复杂查询 gotoexecutorexecutor完成后 gotoreflectorreflector决定 gotoexecutor生成新计划还是save-turn生成最终回复。三个节点的模型名分别由planner_model_name、executor_model_name、reflector_model_name独立配置。节点实现位于 nodes/task_planning其中ops子目录下的 generate_plan.py、execute_plan.py、reflect_plan.py 分别承载这三类核心运算。两个需要了解的工程事实性能取舍该架构通常比单 Agent 设计慢得多因为单个回合可能包含大量 LLM 调用与工具使用。该 Demo 中的 Executor 仅支持线性计划linear plans且任务顺序执行因此尤其慢。业界已有研究如 LLM Compiler通过构造 DAG 来支持并行任务执行以改进这一设计。实时联网能力Demo 中的 Executor 是配备Google Search Grounding 工具的 Gemini 模型可在执行任务时进行实时网络搜索。为什么采用 LangGraph Cloud API SpecLangGraph Cloud API Spec 是标准 LangGraph 客户端 SDK 与已部署 Agent 交互所依赖的接口规范。本项目实现了langgraph_sdk.RemoteGraph接口所需的最小端点子集。RemoteGraph支持与本地 LangGraph 类CompiledGraph相同的协议这意味着你不需要为每个新 Agent 设计自定义路由只需依赖一套一致、可预测的接口即可在开发与部署阶段与 LangGraph Agent 交互下游团队如前端开发者只需学习一个客户端实现就能快速集成新部署的 Agent。目前LangGraph 官方仅在托管的 LangGraph Platform 上提供 LangGraph Cloud API 兼容部署方案。为了让自托管self-hosted部署也具备这一能力项目编写了一个小模块 langgraph_server把 LangGraph Agent 转换为 FastAPI 路由。它不支持 LangGraph Platform 的许多高级特性但足以支撑RemoteGraph客户端使用。模块内部的核心类是LangGraphAgentlanggraph_agent.py它封装了一个StateGraph并对外提供与RemoteGraph对齐的方法get_graph获取图的 JSON 结构支持xray深度检查get_state/get_state_history/get_state_checkpoint读取会话thread当前状态、历史状态与指定 checkpoint 状态update_state以指定节点身份更新会话状态stream流式执行支持stream_mode默认values、interrupt_before/interrupt_after、subgraphs等参数并将 langgraph_sdk 的流模式转换为 langgraph 类型后转发到compiled_graph.astream。适配层fastapi_app.py通过build_agent_router为每个 Agent 生成独立的fastapi.APIRouter。此外checkpoint_saver.py 提供可插拔的 Checkpointer 配置默认内存后端MemoryBackendConfig用于会话状态持久化。可移植性验证Streamlit 前端 Demo 共托管 5 个不同的聊天 Agent其唯一依赖就是标准的langgraph包通过RemoteGraph调用远端 Agent——这恰好证明了该方案的可移植性。每个 Agent 的前端聊天处理器位于 frontend/concierge_ui/agents。本地快速开始Quickstart Demo环境准备克隆仓库并配置 Google Application Default CredentialsADC# 克隆仓库并进入项目根目录 git clone https://github.com/GoogleCloudPlatform/generative-ai.git cd generative-ai/gemini/agents/genai-experience-concierge # 配置 Google Application Default Credentials gcloud auth login gcloud auth application-default login可选创建 Cymbal Retail 数据集Function Calling Demo Agent 需要存在一个 BigQuery 数据集和 Embedding 模型连接才能查询虚构的零售数据集。该数据集在 Demo 部署过程中会自动创建但如果目标 Demo 项目尚不存在则需要手动创建这些表和 Embedding 模型uv run --frozen concierge langgraph create-dataset --project-id $PROJECT_ID从 CLI 实现langgraph_demo.py可见该命令接受--project-id必填与--location可选多区域位置如 US/EU默认US两个参数内部调用dataset.create完成数据集创建。启动后端 Agent 服务端打开一个新终端进入langgraph-demo/backend并运行CONCIERGE_PROJECT$PROJECT_ID uv run --frozen uvicorn concierge.server:app \ --port 3000 \ --reload启动后可在https://localhost:3000/docs查看 Swagger 文档文档中为每个 Agent 的路由器提供了独立分区即上文表格中列出的 5 组路由。CONCIERGE_PROJECT环境变量对应 settings.py 中的concierge_环境变量前缀大小写不敏感嵌套配置用__分隔。该模块同时负责在启动前自动补齐 Cymbal 数据集相关资源的默认 URIsettings.py若未显式提供则按{project}.{cymbal_dataset}.{表名}的规则推导 embedding 模型、库存表、商品表与门店表的完整 URI。启动 Streamlit 前端服务端再打开一个新终端进入langgraph-demo/frontend并运行uv run --frozen streamlit run concierge_ui/server.py \ --server.port 8080 \ --server.runOnSave true随后访问https://localhost:8080/即可使用 Streamlit 演示界面。端到端部署End-to-End Deployment端到端部署工具concierge langgraph deploy会完成三件事创建新的 Demo 项目、供给必要的基础设施、部署后端 LangGraph 服务端与前端 Streamlit 应用。Google Cloud 架构整个 Demo 在 Google Cloud 上的架构可以归纳为以下关键组件以 terraform 目录下的.tf文件为证项目与网络project.tf 基于 terraform-google-modules 的 project-factory 模块创建 Demo 项目network.tf 创建 VPC 与子网数据层databases.tf 创建 BigQuery 数据集/连接与 AlloyDB 等依赖资源服务账号service_accounts.tf 为 Cloud Build、后端 Cloud Run、前端 App Engine 分别创建服务账号后端运行时后端 Agent 服务端以 Cloud Run 服务concierge形式部署通过 AlloyDB 连接密钥保存会话数据前端运行时前端 Streamlit 应用以 App Engine 服务部署并通过服务账号被授权为后端的 invoker。准备 Seed 项目Click-to-deploy 的 LangGraph Demo 使用 project-factory Terraform 模块自动化 Demo 项目创建与基础设施供给。该模块提供了辅助脚本用于检查 seed 项目是否配置正确。官方建议在正式部署前先运行该脚本避免部署中途报错。配置 LangGraph Demo 部署CLI 参数既可以写在命令行上也可以通过配置文件提供。一个典型的配置文件如下langgraph: deploy: # Seed project to use for the terraform project factory. seed_project: seed-project-id # Target demo project to create. project_id: target-project-id # Billing account to attach to the target project. billing_account: 000000-000000-000000 # Support email to appear in the OAuth consent screen. support_email: supportemail.com # Terraform state bucket for infrastructure provisioning state_bucket: bucket-name # demo users that should have access to the deployed frontend demo. demo_users: [group:testemail.com] # (Optional) state bucket prefix state_bucket_prefix: concierge/langgraph # (Optional) organization ID to create the target project org_id: 000000000000 # (Optional) folder ID to create the target project folder_id: 000000000000各字段与 CLI 选项一一对应见 langgraph_demo.py 的deploy命令配置字段对应 CLI 选项必填说明seed_project--seed-project是创建 Demo 项目时使用的 seed 项目 IDproject_id--project-id是要创建的 Demo 目标项目 IDbilling_account--billing-account是附加到目标项目的计费账号 IDsupport_email--support-email是显示在 Demo OAuth 同意屏幕上的支持邮箱demo_users--demo-users可多次是授予托管 Demo 访问权限的成员需带成员类型前缀如user:*、group:*state_bucket--state-bucket是用于 Terraform 状态管理的 GCS 桶state_bucket_prefix--state-bucket-prefix否Terraform 状态存储的 GCS 路径前缀org_id--org-id否创建目标项目所属的组织 IDfolder_id--folder-id否创建目标项目所属的文件夹 IDregion--region否创建资源的默认区域默认us-central1random_project_suffix--random-project-suffix/--no-random-project-suffix否是否为项目 ID 追加随机后缀默认否auto_approve--auto-approve/--no-auto-approve否Terraform 是否自动应用变更默认否执行部署创建好 seed 项目与配置后即可执行uv run --frozen concierge -f $CONFIG_YAML_FILE langgraph deploy从 deploy 的实现可以看到完整的自动化流水线terraform init指定状态桶与前缀→terraform apply创建项目与网络、数据库、服务账号等→ 读取 Terraform 输出真实项目 ID、数据集、连接、服务账号、Artifact Registry 仓库、VPC/子网、AlloyDB 密钥等→ 通过dataset.create创建 Cymbal Retail 数据集 → 使用 Cloud Build 构建后端镜像并推送至 Artifact Registry → 将后端部署为 Cloud Run 服务 → 为前端服务账号授予后端 invoker 权限 → 构建并部署前端到 App Engine。最后以 YAML 形式输出本次部署生成的关键资源项目、后端服务地址、前端地址、BigQuery 数据集等。运行时配置参数详解后端服务的运行时配置集中在 settings.py 的RuntimeSettings基于 pydantic-settings全部可通过CONCIERGE_*环境变量覆盖主要参数如下环境变量CONCIERGE_前缀默认值说明PROJECTunspecifiedGoogle Cloud 项目 ID必须指定且项目必须存在REGIONus-central1模型调用与资源创建区域CYMBAL_DATASETcymbal_retailBigQuery 数据集名CYMBAL_DATASET_LOCATIONUSBigQuery 数据集位置多区域CYMBAL_EMBEDDING_MODEL_URI自动推导Embedding 模型 URI默认{project}.{dataset}.text_embeddingCYMBAL_INVENTORY_TABLE_URI自动推导库存表 URI默认{project}.{dataset}.cymbal_inventoryCYMBAL_PRODUCTS_TABLE_URI自动推导商品表 URI默认{project}.{dataset}.cymbal_productCYMBAL_STORES_TABLE_URI自动推导门店表 URI默认{project}.{dataset}.cymbal_storeCHAT_MODEL_NAMEgemini-3.5-flash基础聊天模型FUNCTION_CALLING_MODEL_NAMEgemini-3.5-flashFunction Calling 模型ROUTER_MODEL_NAMEgemini-3.5-flash语义路由模型GUARDRAIL_MODEL_NAMEgemini-3.5-flash护栏分类模型PLANNER_MODEL_NAMEgemini-3.5-flashTask Planner 的 Planner 模型EXECUTOR_MODEL_NAMEgemini-3.5-flashTask Planner 的 Executor 模型REFLECTOR_MODEL_NAMEgemini-3.5-flashTask Planner 的 Reflector 模型MAX_ROUTER_TURN_HISTORY3路由判断使用的历史轮数CHECKPOINTER内存后端MemoryBackendConfigCheckpointer 配置会话持久化后端从代码注释可见这些默认值是合理默认sane default values仅需按需调整而 Cymbal 四类资源 URI 若不显式提供则由模型校验器在启动时自动补齐降低配置成本。小结Gen AI Experience Concierge 通过四种可复用的 Agent 设计模式示范了 LangGraph 在多智能体编排、护栏、意图路由、受控工具调用与复杂任务规划上的工程实践同时以LangGraph Cloud API 兼容的自托管服务端 Streamlit 前端验证了 Agent 应用的可移植部署路径。无论你是想快速理解某一种 Agent 架构模式可运行 agent-design-patterns 下的独立 Notebook在本地用 FastAPI Streamlit 跑通一个多 Agent 演示参考 backend README 与 frontend README还是基于 Terraform 在 Google Cloud 上完成一键端到端部署scripts/cli都可以在该项目中找到完整的参考实现与可运行的代码依据。说明本 Demo 并非 Google 官方支持的产品仓库代码仅用于演示目的。【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 基于 LangGraph 的生成式 AI 智能体设计模式实践：Gen AI Experience Concierge 全解析
基于 LangGraph 的生成式 AI 智能体设计模式实践Gen AI Experience Concierge 全解析【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai本文基于仓库 gemini/agents/genai-experience-concierge/README.md 及其配套源码撰写介绍一个以 LangGraph 为核心编排框架、面向 Google Cloud 生成式 AI 场景的智能体Agent设计模式集合。文章涵盖四种可直接复用的 Agent 架构模式Guardrail Classifier、Semantic Router、Function Calling、Task Planner、自建 LangGraph Cloud API 兼容服务端的原理以及从本地 Quickstart 到 Terraform 一键端到端部署的完整路径。读完本文你将掌握在自托管环境FastAPI Streamlit中构建、调试与部署 LangGraph 多智能体应用的方法论与工程细节。项目定位与核心思想Gen AI Experience Concierge 是一套智能体设计模式Agent Design Patterns的参考实现集合所有设计模式均使用LangGraph 框架完成智能体编排Orchestration与会话管理Session Management。它解决的工程问题是在真实业务中Agent 应用往往需要组合多个智能体、接入多种工具并保证会话状态可控而这些能力需要一套可复用、可部署、可观测的实现范式。整个项目由两大组成部分协同工作独立 Notebook位于 agent-design-patterns/每个模式配套一个自包含的 Notebook如 guardrail-classifier.ipynb用于在无需部署任何服务端的前提下交互式地搭建与理解每种 Agent 模式。可一键部署的 Demo 应用将上述模式打包为 click-to-deploy 应用使用FastAPI承载 LangGraph Agent 服务端并用Streamlit提供前端演示界面。Agent 服务端兼容 LangGraph Cloud API Spec 目录。仓库结构速览部署型 Demo 的源码采用前后端分离 基础设施即代码的组织方式langgraph-demo │ ├── backend ; 后端 Agent 服务端 │ ├── concierge │ │ ├── agents ; 所有 Agent 定义 │ │ ├── langgraph_server ; LangGraph - fastapi.APIRouter 适配器 │ │ ├── nodes ; 所有 LangGraph 节点定义 │ │ │ └── task_planning │ │ │ └── ops │ │ └── tools ; LLM 工具定义 │ └── notebooks ; 与 Agent 交互的 Notebook │ ├── frontend ; 前端 Streamlit 服务端 │ └── concierge_ui │ └── agents ; 每个 Agent 的聊天处理逻辑 │ └── terraform ; 部署所需的基础设施代码其中 backend 与 frontend 各自包含独立的 README提供更深入的本机环境搭建说明。从源码结构看server.py服务端在启动时依次加载了 5 个 Agent基础 Gemini 聊天、带 Guardrails 的聊天、Function Calling、Semantic Router、Task Planner并将每个 Agent 通过build_agent_router注册为独立路由前缀路由前缀标签对应 Agent/geminiGemini Chat基础 Gemini 聊天 Agent/gemini-with-guardrailsGemini with GuardrailsGuardrail Classifier Agent/function-callingFunction CallingFunction Calling Agent/semantic-routerSemantic RouterSemantic Router Agent/task-plannerTask PlannerTask Planner Agent四种核心 Agent 设计模式以下四种模式是该项目的主体内容均可在 agent-design-patterns/README.md 中找到背景说明与架构图并有对应的独立 Notebook 与 Demo 源码模式独立 NotebookDemo 源码Guardrail Classifier Agentguardrail-classifier.ipynbguardrails.pySemantic Router Agentsemantic-router.ipynbsemantic_router.pyFunction Calling Agentfunction-calling.ipynbfunction_calling.pyTask Plannertask-planner.ipynbtask_planner.py模式一Guardrail Classifier护栏分类器在构建 Agentic 应用时仅依赖模型内置的 Safety Settings 往往不够通常还需要额外的护栏来约束交互范围避免离题off-topic或对抗性adversarial查询。该模式实现了一个基于 LLM 的护栏分类器对每条用户输入判定回答或拒绝。实现上存在两种路线在计算成本与延迟之间取舍顺序执行该 Demo 采用先生成分类结果再生成回复。如果判定为拒绝则直接跳过回复生成阶段因此延迟更高但成本更低。并行执行分类器与回复生成同时进行延迟更低但由于即便要拦截也需启动生成成本更高且护栏可以在判定被拦截时更快地打断生成。该 Demo 采用第一种方案顺序执行若你的场景对延迟敏感可自行修改为并行执行。在源码层面guardrails.py 定义了一个面向 Cymbal 零售公司的护栏系统提示词明确给出分类任务、使用场景与拦截标准Blocking Criteria例如输入与用例涵盖的主题无关输入试图诱导不当回复或篡改指令讨论 Cymbal 的具体员工、竞争对手企业、公众人物讨论法律或有争议的话题要求生成创意性回复、玩笑或任何不专业的语气。值得注意的是护栏系统提示词也特别说明与零售无关但属于正常对话的输入仍然是合法的Appropriate conversational inputs are valid even if they are not specifically about retail以避免护栏过度拦截。在图的编排上guardrails.py整个 Agent 由 3 个节点构成guardrails入口→ 判定放行则进入chat→ 最后统一进入save-turn保存会话若护栏判定拦截则guardrails节点直接跳转save-turn跳过回复生成。save-turn节点把当前轮次写回会话状态实现多轮记忆。这也印证了顺序执行方案中护栏拦截即可避免后续生成成本的核心收益。模式二Semantic Router语义路由器语义路由器模式用于从一组候选专家 Agent 中动态挑选最合适的一个来响应用户输入。该 Demo 使用基于 LLM 的意图检测分类器将每条用户查询路由到以下三种目标之一见 semantic_router.py 中的RouterTarget枚举Customer Support Assistant退货、政策、投诉、FAQ、升级等客服类问题Conversational Retail Search Assistant寒暄/日常对话以及 Cymbal 零售商品、门店、库存含实时数据的讨论Unsupported与上述 Agent 均无关的离题查询。路由系统提示词semantic_router.py中包含一组 few-shot 示例用于稳定分类行为例如询问商品如 Is the Meinl Byzance Jazz Ride 18 available?→ Retail Search发起退货 → Customer Support地球离太阳多远→ Unsupported。关键设计要点Demo 中的两位专家客服与零售搜索被简化为仅含系统提示词的 Gemini 调用但它们代表的是任意可以与其他子 Agent 共享会话历史的执行体。例如真实的客服 Agent 可能基于 Contact Center as a ServiceCCaaS实现而零售搜索助手可以基于 Gemini 部署在 Cloud Run 上。因此语义路由器层可以作为一个 Facade门面用统一接口屏蔽多个截然不同的 Agent 后端这也是该模式最具工程价值的应用场景。在图结构上semantic_router.pysemantic-router节点作为入口通过class_node_mapping把分类结果映射到customer-service、retail-search、unsupported三个聊天节点各节点最终统一汇聚到save-turn。路由节点还通过max_router_turn_history控制用于意图判定的历史轮数默认 3见 settings.py因为多轮对话中的意图往往依赖上下文。模式三Function Calling函数调用函数调用是实现结构化检索增强生成RAG以及让 LLM 在现实世界采取行动的流行技术。该 Demo 面向一家虚构公司 Cymbal Retail利用一组函数声明在合成的 BigQuery 数据集上执行受控查询。数据集包含商品、门店位置以及商品-门店库存三类信息。其核心价值在于用受控的结构化查询取代任意的 NL2SQL函数声明让 LLM 生成结构化的查询参数从而以安全、受控的方式查询数据库而 NL2SQL 虽然更灵活但会生成并执行任意 SQL存在更大的安全风险。该模式的 Retail Search Assistant 覆盖三类用例每类都支持丰富的过滤与排序维度门店搜索Store Search可按门店名称、搜索半径、商品 ID、结果数量过滤商品搜索Product Search可按门店 ID、价格区间、结果数量过滤并按商品名称/描述的语义相似度排序指定商品-门店对的库存查询Inventory Search。工具层由三个文件组成find_stores.py、find_products.py、find_inventory.py。每个工具由两部分构成*_fdgenai_types.FunctionDeclaration声明与generate_*_handler可调用的执行器在 function_calling.py 的load_function_specs中打包为FunctionSpec列表注入聊天节点。以 find_products.py 为例其函数声明包含参数max_results返回结果数上限默认 3硬上限MAX_PRODUCT_RESULTS 10product_search_query用于语义相似度检索的文本查询可匹配名称、描述、品牌、类别store_ids必须持有该商品的门店 ID 列表min_price/max_price价格下限 / 上限美元。该工具内部实现了两条 SQL 路径无语义查询时走_build_query_without_vector_search基于库存表INNER JOIN做门店过滤并支持IFNULL(sale_price, list_price)的价格区间过滤有语义查询时走_build_query_with_vector_search调用 BigQueryVECTOR_SEARCHML.GENERATE_TEXT_EMBEDDING对商品名/描述做语义相似度检索top_k取max_results * 3以留出后置过滤余量再叠加价格与门店过滤条件。这是 BQML 内建 Embedding 能力在 Agent 工具中的典型落地。在流式体验上聊天节点chat.py通过utils.generate_content_stream流式生成内容并将文本、function_call、function_response三类分片实时通过stream_writer推送出去前端因此可以看到调用工具 → 拿到结果 → 生成最终回复的完整过程。注意运行该 Demo 或独立 Notebook 前必须先创建 Cymbal Retail 数据集见下文创建 Cymbal Retail 数据集。模式四Task Planner任务规划器Task Planner 是一种与 Deep Research 类似的多智能体架构适用于需要更复杂推理、规划与多工具协同的任务。它由三个核心 Agent 构成Planner规划器接收用户输入后要么直接回应简单问题如 Hi要么生成一份研究计划包括待执行任务列表Executor执行器接收计划使用自己的工具执行每个任务并用执行结果更新计划Reflector反思器审查已执行的计划要么生成最终回复给用户要么生成新计划并跳回第 2 步形成 规划 → 执行 → 反思 → 再规划 的循环。图结构在 task_planner.py 中一目了然planner为入口简单查询直接 gotosave-turn复杂查询 gotoexecutorexecutor完成后 gotoreflectorreflector决定 gotoexecutor生成新计划还是save-turn生成最终回复。三个节点的模型名分别由planner_model_name、executor_model_name、reflector_model_name独立配置。节点实现位于 nodes/task_planning其中ops子目录下的 generate_plan.py、execute_plan.py、reflect_plan.py 分别承载这三类核心运算。两个需要了解的工程事实性能取舍该架构通常比单 Agent 设计慢得多因为单个回合可能包含大量 LLM 调用与工具使用。该 Demo 中的 Executor 仅支持线性计划linear plans且任务顺序执行因此尤其慢。业界已有研究如 LLM Compiler通过构造 DAG 来支持并行任务执行以改进这一设计。实时联网能力Demo 中的 Executor 是配备Google Search Grounding 工具的 Gemini 模型可在执行任务时进行实时网络搜索。为什么采用 LangGraph Cloud API SpecLangGraph Cloud API Spec 是标准 LangGraph 客户端 SDK 与已部署 Agent 交互所依赖的接口规范。本项目实现了langgraph_sdk.RemoteGraph接口所需的最小端点子集。RemoteGraph支持与本地 LangGraph 类CompiledGraph相同的协议这意味着你不需要为每个新 Agent 设计自定义路由只需依赖一套一致、可预测的接口即可在开发与部署阶段与 LangGraph Agent 交互下游团队如前端开发者只需学习一个客户端实现就能快速集成新部署的 Agent。目前LangGraph 官方仅在托管的 LangGraph Platform 上提供 LangGraph Cloud API 兼容部署方案。为了让自托管self-hosted部署也具备这一能力项目编写了一个小模块 langgraph_server把 LangGraph Agent 转换为 FastAPI 路由。它不支持 LangGraph Platform 的许多高级特性但足以支撑RemoteGraph客户端使用。模块内部的核心类是LangGraphAgentlanggraph_agent.py它封装了一个StateGraph并对外提供与RemoteGraph对齐的方法get_graph获取图的 JSON 结构支持xray深度检查get_state/get_state_history/get_state_checkpoint读取会话thread当前状态、历史状态与指定 checkpoint 状态update_state以指定节点身份更新会话状态stream流式执行支持stream_mode默认values、interrupt_before/interrupt_after、subgraphs等参数并将 langgraph_sdk 的流模式转换为 langgraph 类型后转发到compiled_graph.astream。适配层fastapi_app.py通过build_agent_router为每个 Agent 生成独立的fastapi.APIRouter。此外checkpoint_saver.py 提供可插拔的 Checkpointer 配置默认内存后端MemoryBackendConfig用于会话状态持久化。可移植性验证Streamlit 前端 Demo 共托管 5 个不同的聊天 Agent其唯一依赖就是标准的langgraph包通过RemoteGraph调用远端 Agent——这恰好证明了该方案的可移植性。每个 Agent 的前端聊天处理器位于 frontend/concierge_ui/agents。本地快速开始Quickstart Demo环境准备克隆仓库并配置 Google Application Default CredentialsADC# 克隆仓库并进入项目根目录 git clone https://github.com/GoogleCloudPlatform/generative-ai.git cd generative-ai/gemini/agents/genai-experience-concierge # 配置 Google Application Default Credentials gcloud auth login gcloud auth application-default login可选创建 Cymbal Retail 数据集Function Calling Demo Agent 需要存在一个 BigQuery 数据集和 Embedding 模型连接才能查询虚构的零售数据集。该数据集在 Demo 部署过程中会自动创建但如果目标 Demo 项目尚不存在则需要手动创建这些表和 Embedding 模型uv run --frozen concierge langgraph create-dataset --project-id $PROJECT_ID从 CLI 实现langgraph_demo.py可见该命令接受--project-id必填与--location可选多区域位置如 US/EU默认US两个参数内部调用dataset.create完成数据集创建。启动后端 Agent 服务端打开一个新终端进入langgraph-demo/backend并运行CONCIERGE_PROJECT$PROJECT_ID uv run --frozen uvicorn concierge.server:app \ --port 3000 \ --reload启动后可在https://localhost:3000/docs查看 Swagger 文档文档中为每个 Agent 的路由器提供了独立分区即上文表格中列出的 5 组路由。CONCIERGE_PROJECT环境变量对应 settings.py 中的concierge_环境变量前缀大小写不敏感嵌套配置用__分隔。该模块同时负责在启动前自动补齐 Cymbal 数据集相关资源的默认 URIsettings.py若未显式提供则按{project}.{cymbal_dataset}.{表名}的规则推导 embedding 模型、库存表、商品表与门店表的完整 URI。启动 Streamlit 前端服务端再打开一个新终端进入langgraph-demo/frontend并运行uv run --frozen streamlit run concierge_ui/server.py \ --server.port 8080 \ --server.runOnSave true随后访问https://localhost:8080/即可使用 Streamlit 演示界面。端到端部署End-to-End Deployment端到端部署工具concierge langgraph deploy会完成三件事创建新的 Demo 项目、供给必要的基础设施、部署后端 LangGraph 服务端与前端 Streamlit 应用。Google Cloud 架构整个 Demo 在 Google Cloud 上的架构可以归纳为以下关键组件以 terraform 目录下的.tf文件为证项目与网络project.tf 基于 terraform-google-modules 的 project-factory 模块创建 Demo 项目network.tf 创建 VPC 与子网数据层databases.tf 创建 BigQuery 数据集/连接与 AlloyDB 等依赖资源服务账号service_accounts.tf 为 Cloud Build、后端 Cloud Run、前端 App Engine 分别创建服务账号后端运行时后端 Agent 服务端以 Cloud Run 服务concierge形式部署通过 AlloyDB 连接密钥保存会话数据前端运行时前端 Streamlit 应用以 App Engine 服务部署并通过服务账号被授权为后端的 invoker。准备 Seed 项目Click-to-deploy 的 LangGraph Demo 使用 project-factory Terraform 模块自动化 Demo 项目创建与基础设施供给。该模块提供了辅助脚本用于检查 seed 项目是否配置正确。官方建议在正式部署前先运行该脚本避免部署中途报错。配置 LangGraph Demo 部署CLI 参数既可以写在命令行上也可以通过配置文件提供。一个典型的配置文件如下langgraph: deploy: # Seed project to use for the terraform project factory. seed_project: seed-project-id # Target demo project to create. project_id: target-project-id # Billing account to attach to the target project. billing_account: 000000-000000-000000 # Support email to appear in the OAuth consent screen. support_email: supportemail.com # Terraform state bucket for infrastructure provisioning state_bucket: bucket-name # demo users that should have access to the deployed frontend demo. demo_users: [group:testemail.com] # (Optional) state bucket prefix state_bucket_prefix: concierge/langgraph # (Optional) organization ID to create the target project org_id: 000000000000 # (Optional) folder ID to create the target project folder_id: 000000000000各字段与 CLI 选项一一对应见 langgraph_demo.py 的deploy命令配置字段对应 CLI 选项必填说明seed_project--seed-project是创建 Demo 项目时使用的 seed 项目 IDproject_id--project-id是要创建的 Demo 目标项目 IDbilling_account--billing-account是附加到目标项目的计费账号 IDsupport_email--support-email是显示在 Demo OAuth 同意屏幕上的支持邮箱demo_users--demo-users可多次是授予托管 Demo 访问权限的成员需带成员类型前缀如user:*、group:*state_bucket--state-bucket是用于 Terraform 状态管理的 GCS 桶state_bucket_prefix--state-bucket-prefix否Terraform 状态存储的 GCS 路径前缀org_id--org-id否创建目标项目所属的组织 IDfolder_id--folder-id否创建目标项目所属的文件夹 IDregion--region否创建资源的默认区域默认us-central1random_project_suffix--random-project-suffix/--no-random-project-suffix否是否为项目 ID 追加随机后缀默认否auto_approve--auto-approve/--no-auto-approve否Terraform 是否自动应用变更默认否执行部署创建好 seed 项目与配置后即可执行uv run --frozen concierge -f $CONFIG_YAML_FILE langgraph deploy从 deploy 的实现可以看到完整的自动化流水线terraform init指定状态桶与前缀→terraform apply创建项目与网络、数据库、服务账号等→ 读取 Terraform 输出真实项目 ID、数据集、连接、服务账号、Artifact Registry 仓库、VPC/子网、AlloyDB 密钥等→ 通过dataset.create创建 Cymbal Retail 数据集 → 使用 Cloud Build 构建后端镜像并推送至 Artifact Registry → 将后端部署为 Cloud Run 服务 → 为前端服务账号授予后端 invoker 权限 → 构建并部署前端到 App Engine。最后以 YAML 形式输出本次部署生成的关键资源项目、后端服务地址、前端地址、BigQuery 数据集等。运行时配置参数详解后端服务的运行时配置集中在 settings.py 的RuntimeSettings基于 pydantic-settings全部可通过CONCIERGE_*环境变量覆盖主要参数如下环境变量CONCIERGE_前缀默认值说明PROJECTunspecifiedGoogle Cloud 项目 ID必须指定且项目必须存在REGIONus-central1模型调用与资源创建区域CYMBAL_DATASETcymbal_retailBigQuery 数据集名CYMBAL_DATASET_LOCATIONUSBigQuery 数据集位置多区域CYMBAL_EMBEDDING_MODEL_URI自动推导Embedding 模型 URI默认{project}.{dataset}.text_embeddingCYMBAL_INVENTORY_TABLE_URI自动推导库存表 URI默认{project}.{dataset}.cymbal_inventoryCYMBAL_PRODUCTS_TABLE_URI自动推导商品表 URI默认{project}.{dataset}.cymbal_productCYMBAL_STORES_TABLE_URI自动推导门店表 URI默认{project}.{dataset}.cymbal_storeCHAT_MODEL_NAMEgemini-3.5-flash基础聊天模型FUNCTION_CALLING_MODEL_NAMEgemini-3.5-flashFunction Calling 模型ROUTER_MODEL_NAMEgemini-3.5-flash语义路由模型GUARDRAIL_MODEL_NAMEgemini-3.5-flash护栏分类模型PLANNER_MODEL_NAMEgemini-3.5-flashTask Planner 的 Planner 模型EXECUTOR_MODEL_NAMEgemini-3.5-flashTask Planner 的 Executor 模型REFLECTOR_MODEL_NAMEgemini-3.5-flashTask Planner 的 Reflector 模型MAX_ROUTER_TURN_HISTORY3路由判断使用的历史轮数CHECKPOINTER内存后端MemoryBackendConfigCheckpointer 配置会话持久化后端从代码注释可见这些默认值是合理默认sane default values仅需按需调整而 Cymbal 四类资源 URI 若不显式提供则由模型校验器在启动时自动补齐降低配置成本。小结Gen AI Experience Concierge 通过四种可复用的 Agent 设计模式示范了 LangGraph 在多智能体编排、护栏、意图路由、受控工具调用与复杂任务规划上的工程实践同时以LangGraph Cloud API 兼容的自托管服务端 Streamlit 前端验证了 Agent 应用的可移植部署路径。无论你是想快速理解某一种 Agent 架构模式可运行 agent-design-patterns 下的独立 Notebook在本地用 FastAPI Streamlit 跑通一个多 Agent 演示参考 backend README 与 frontend README还是基于 Terraform 在 Google Cloud 上完成一键端到端部署scripts/cli都可以在该项目中找到完整的参考实现与可运行的代码依据。说明本 Demo 并非 Google 官方支持的产品仓库代码仅用于演示目的。【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考