adk-samples 仓库 TypeScript 智能体示例实战环境搭建、customer_service 运行与源码解析【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples本指南以 adk-samples 仓库中的typescript/目录为线索系统讲解基于 Agent Development KitADKTypeScript 的示例智能体如何安装依赖、配置环境变量并运行并以该目录下唯一保留的customer_serviceCymbal Home Garden 客服智能体为实例深入其 agent.ts、config.ts、tools 与 callbacks 等源码帮助读者掌握从零启动一个 ADK TypeScript 智能体并理解其工具调用、回调与状态注入机制的完整链路。目录现状该目录已进入冻结状态在开始动手之前需要先了解仓库对该目录的定位。typescript/README.md的开头以醒目的 [!IMPORTANT] 提示声明typescript/agents/不再接受新增 recipe也不再修改已有 recipe新的 TypeScript 示例统一迁移到contrib/typescript/目录当前仓库中该目录尚未有内容如果你要贡献新 recipe请先阅读 docs/recipe-checklist.md配方检查清单如果你已有 recipe 在此目录请将其移动到contrib/typescript/name并遵循同一份检查清单详见 docs/README.md贡献者指南任何新增或修改typescript/agents/下文件的 Pull Request 都会导致 CI 失败。也就是说当前typescript/目录是一个被冻结的历史示例集合它的意义在于查看与运行既有的示例代码而不是继续在此提交新内容。这一点在阅读下述结构时需牢记。仓库结构与示例总览typescript/README.md中给出了目录的设计意图typescript/存放所有 TypeScript 示例代码每个示例智能体位于独立的子目录中并自带各自的README.md说明。对照当前仓库实际结构与文档描述的略有差异文档中的agent1/agent2为示意占位当前真实结构如下typescript/ ├── README.md # 本指南对应的总览文档 └── agents/ └── customer_service/ # 唯一的示例智能体家居园艺客服 ├── README.md # 智能体专属说明 ├── customer_service_workflow.webp ├── package.json ├── tsconfig.json └── customer_service/ ├── agent.ts # 智能体入口rootAgent ├── config.ts # 环境变量与模型配置 ├── prompts.ts # 全局指令与角色指令 ├── entities/ │ └── customer.ts # 客户实体与模拟数据 ├── tools/ │ ├── tools.ts # 12 个工具的业务实现Mock │ └── function_tools.ts# FunctionTool 包装与 Zod Schema └── shared_libraries/ └── callbacks.ts # 限流、鉴权、前后置回调需要指出的是原文档中提到的agents/README.md对全部智能体的总览与分类在当前仓库中并不存在——typescript/agents/下目前仅有 customer_service/README.md 一份智能体说明。因此本指南将以 customer_service 作为唯一且完整的实战对象进行讲解。前置条件运行 TypeScript 示例需要什么根据 typescript/README.md 与 customer_service/README.md 的说明运行这些示例需要满足以下条件Node.js v20 或更高版本customer_service 的package.json的 devDependencies 中使用了types/node^20.19.26、typescript^5.3.3与ts-node^10.9.2配合tsconfig.json中target: es2020、module: commonjs、strict: true的编译配置v20 是文档明确给出的最低版本要求。ADK TypeScript 运行时安装google/adk示例锁定在^0.2.0与google/adk-devtools提供adk run等 CLI 能力。示例的 package.json 依赖即包含这两个包npx adk run命令正是依赖google/adk-devtools提供的命令行入口。环境变量每个示例依赖.env文件或 shell 导出变量来做配置如 API Key、Google Cloud 项目 ID、区域等从而把密钥隔离在代码之外。原文档建议在所需运行的智能体目录下创建.env通常是复制仓库提供的.env.example。需要说明的是当前 customer_service 目录下并未附带.env.example其 README.md 给出的方式是直接使用export导出环境变量这一点以实际仓库为准。Google Cloud 项目推荐虽然部分智能体仅凭 API Key 即可本地运行但绝大多数示例会用到 Vertex AI、BigQuery 等 Google Cloud 服务。customer_service 默认通过 Vertex AI 调用 Gemini 模型GOOGLE_GENAI_USE_VERTEXAI1因此一个配置好的 Google Cloud 项目能显著降低运行门槛。克隆、安装与运行三步上手原文档给出了标准的启动流程结合当前仓库可整理为以下可复现的步骤。1. 克隆仓库并进入目录git clone https://gitcode.com/GitHub_Trending/ad/adk-samples.git cd adk-samples/typescript2. 安装依赖并构建进入 customer_service 示例目录后安装依赖cd typescript/agents/customer_service npm installpackage.json中提供了三个脚本build执行tsc编译到dist/、startnode dist/agent.js运行编译产物、prestart启动前自动构建。因此你也可以用npm start一条命令完成先编译再运行。3. 配置环境变量customer_service 的配置读取逻辑集中在 config.ts其中getEnv(key, defaultValue)使用node:process.env读取环境变量并回退默认值。需要导出的变量及默认值如下export GOOGLE_CLOUD_PROJECTYOUR_PROJECT_ID export GOOGLE_CLOUD_LOCATIONus-central1 export GOOGLE_GENAI_USE_VERTEXAI1 export GOOGLE_API_KEYMY_GOOGLE_API_KEY各变量的语义依据config.ts的Config类环境变量默认值说明GOOGLE_CLOUD_PROJECTmy_projectGoogle Cloud 项目 ID用于 Vertex AI 调用GOOGLE_CLOUD_LOCATIONus-central1Vertex AI 的模型部署区域GOOGLE_GENAI_USE_VERTEXAI1是否走 Vertex AI 端点1表示启用GOOGLE_API_KEYGOOGLE_API_KEYAPI Key使用 Vertex AI 时通常以服务账号凭据替代4. 运行智能体customer_service 的入口是customer_service/agent.ts其中导出的rootAgent即为运行入口。使用 ADK CLI 启动交互式会话npx adk run customer_service/agent.ts深入 customer_service一个零售客服智能体的源码解剖customer_service 是一个面向 Cymbal Home Garden家居园艺大卖场的 AI 客服智能体原文档用一张表概括了它的定位特性说明交互类型Interaction Type会话式Conversational复杂度Complexity中级Intermediate智能体类型Agent Type单智能体Single Agent组件Components工具Tools、多模态Multimodal行业Vertical零售Retail它的核心能力包括识别老顾客并致意、通过视频等视觉手段识别植物、查看与修改购物车、推荐商品与增值服务、预约种植服务、发送养护说明与生成折扣二维码。下面逐一从源码印证这些能力的实现方式。智能体定义LlmAgent 与回调挂载agent.ts 中通过new LlmAgent({...})构造根智能体export const rootAgent new LlmAgent({ model: config.agentSettings.model, name: config.agentSettings.name, instruction: COMBINED_INSTRUCTION, tools: [ /* 12 个 FunctionTool */ ], beforeToolCallback: beforeTool, afterToolCallback: afterTool, beforeAgentCallback: beforeAgent, beforeModelCallback: rateLimitCallback, });这里体现了 ADK 的四个关键扩展点模型与名称来自配置config.agentSettings默认name: customer_service_agent、model: gemini-2.5-flash见 config.ts指令拼接COMBINED_INSTRUCTION将GLOBAL_INSTRUCTION客户档案与INSTRUCTION角色指令拼成一个字符串传入工具列表全部 12 个工具以FunctionTool形式挂载回调挂载beforeTool/afterTool/beforeAgent/beforeModel四个回调分别负责工具调用前校验、工具调用后处理、会话开始前的状态注入以及模型请求前的限流。指令系统全局指令 角色指令prompts.ts 将指令拆分为两部分GLOBAL_INSTRUCTION动态注入客户档案。它通过Customer.getCustomer(123)取得模拟客户并序列化为 JSON拼入当前客户档案是……的全局上下文INSTRUCTION定义Project Pro助手的完整角色行为包括六大能力域个性化客户服务、产品识别与推荐、订单管理、增值服务与折扣审批、预约排期、售后互动并明确约束优先使用工具获取信息而非依赖模型内部知识修改购物车前必须先调用access_cart_information查看现有内容推荐商品前先查购物车避免重复推荐折扣需遵循公司政策必要时走sync_ask_for_approval经理审批对用户隐藏tool_code、tool_outputs等内部机制表格一律用 Markdown 渲染操作前必须与用户确认。客户实体与模拟数据entities/customer.ts 定义了Customer实体字段覆盖账户号、联系方式、账单地址、购买历史、忠诚度积分、首选门店、沟通偏好与花园档案园子类型、光照、土壤等。Customer.getCustomer(123)返回一个虚构客户 Alex Johnson含三笔购买历史、133 积分、full sun光照的花园档案注释明确指出真实场景中应替换为数据库查询。toJson()以 4 空格缩进序列化整个档案供指令系统注入。12 个工具Mock 实现与安全护栏工具的业务逻辑集中在 tools/tools.ts共 12 个均以console.info打日志并返回模拟数据注释中标注MOCK API RESPONSE - Replace with actual API call工具功能关键实现细节sendCallCompanionLink向用户手机发送视频连接链接接受phoneNumberapproveDiscount审批折扣限定额度内value 10时拒绝并返回原因供模型纠错syncAskForApproval向经理请求折扣审批同步版本默认返回approvedupdateSalesforceCrm更新 Salesforce 客户记录接受customerIddetails字典accessCartInformation获取购物车内容返回两件商品的 Mock 购物车与subtotalmodifyCart增删购物车商品接受itemsToAdd/itemsToRemovegetProductRecommendations按植物类型推荐商品对petunias返回专门推荐组合checkProductAvailability查询门店库存返回available/quantity/storeschedulePlantingService预约种植服务用uuidv4()生成appointment_id与确认时间getAvailablePlantingTimes查询可用时段返回[9-12, 13-16]sendCareInstructions通过 email/SMS 发送养护说明接受deliveryMethodgenerateQrCode生成折扣二维码含防滥用护栏百分比折扣 10% 或固定折扣 20 时拒绝其中approveDiscount与generateQrCode内置了自动审批限额超过阈值时返回错误字符串而非成功对象让模型可以读取原因并自行恢复这是典型的护栏 可恢复错误设计模式。工具暴露给模型的部分由 function_tools.ts 完成每个工具用Zod Schema声明输入参数含describe描述供模型理解再包装为FunctionTool实现类型安全的参数校验 可执行的函数体分离。例如GenerateQrCodeInput声明discountValue: z.number()、discountType: z.string()、expirationDays: z.number()与tools.ts中的实现签名一一对应。回调层限流、参数归一化与客户校验shared_libraries/callbacks.ts 实现了四个回调是理解 ADK 生命周期的重要样例rateLimitCallbackbeforeModel以会话状态为计数载体实现每分钟 10 次RPM_QUOTA 10RATE_LIMIT_SECS 60的请求限流。首次请求在state中记录timer_start与request_count当请求数超过配额时await new Promise(setTimeout(...))异步休眠直到窗口重置。它还会把空文本 part 替换为空格避免空内容影响模型请求。beforeTool工具调用前将入参递归小写化后原地写回args若入参含customer_id则调用validateCustomerId与会话状态中的customer_profile比对不匹配时直接返回{ error: ... }阻断执行对折扣审批类工具若金额 ≤10 则直接返回无需经理审批的结果对购物车修改类工具则返回已增删商品的摘要。afterTool工具调用后针对审批成功status: approved/ok的工具结果在注释位置预留将折扣应用到购物车的真实业务挂载点。beforeAgent智能体执行前若会话状态中尚无customer_profile则用Customer.getCustomer(123)生成客户档案并写入state实现每个会话自动注入客户上下文。这套回调组合展示了 ADK TypeScript 中状态State贯穿会话、回调分阶段介入的编程模型限流、鉴权、参数清洗都可以在不修改工具实现的前提下通过回调以横切方式完成。小结从示例到自建智能体通过本文你可以完成一次完整的 ADK TypeScript 示例体验克隆 adk-samples 仓库、在 customer_service 目录安装依赖、导出环境变量、用npx adk run启动会话并从源码层面理解LlmAgent构造、Zod Schema 工具包装、指令注入与四类回调的执行时机。这个示例虽未接入真实后端工具全部为 Mock但其工具与实现解耦、回调横切、状态驱动会话的骨架完全可以作为你自己构建零售、客服类智能体的起点。如果你打算贡献新的 TypeScript 示例请务必遵循仓库的冻结规则新内容放入contrib/typescript/并参照 docs/recipe-checklist.md 与 docs/README.md 完成配方检查仓库还提供了 docs/recipe-handbook/languages/typescript.md 等技术手册供进一步研读。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考