Genkit × Angular：用流式 Flow 在 Angular 应用中构建 Gemini 驱动的角色生成器与聊天机器人

Genkit × Angular用流式 Flow 在 Angular 应用中构建 Gemini 驱动的角色生成器与聊天机器人【免费下载链接】genkitOpen-source framework for building agentic apps in JavaScript, Go, Dart, and Python, built and used in production by Google项目地址: https://gitcode.com/GitHub_Trending/ge/genkit本文基于 Genkit 仓库中samples/js-angular/示例及其 README 编写讲解如何在 Angular 前端中通过 Genkit 流式 Flow 消费 Gemini 的逐块输出既能实现RPG 角色 JSON 逐字段流式渲染也能实现带工具调用tool request/response的会话式聊天机器人。读完本文你将掌握该示例的完整安装运行流程、服务端 Flow 定义方式defineFlow、defineAgent、generateStreampartial-json以及 Angular 侧streamFlow客户端消费流式数据的完整链路。一、示例概览samples/js-angular/是一个演示在 Angular 应用中实现流式 AI 响应的完整前后端示例核心能力包括两部分RPG 角色生成器streamCharactersFlow按指定数量生成角色档案以 JSON 格式流式返回前端逐块渲染交互式聊天机器人chatbotFlow基于 Gemini 的会话式 Agent支持系统提示词、工具调用与内存级会话历史。技术栈组合为Angular前端框架GenkitAI 编排层Gemini模型代码中通过googleAI.model(gemini-flash-latest)调用README 标注为 Gemini 2.5 Flash。整体架构是一个经典的前后端分离双端口结构server/基于 Express 的 Genkit Flow 服务通过genkit-ai/express的startFlowServer暴露 HTTP 端点监听127.0.0.1:3400genkit-app/Angular 18 单页应用开发服务器监听http://localhost:4200/通过 Genkit JS 客户端的streamFlow直接调用 Flow 端点。二、前置条件与安装按 README 的要求安装Node.js v20和 npm准备一个Google Developer Gemini API Key可从 Google AI Studio 创建并设置环境变量export GEMINI_API_KEYyour_api_key_here然后在samples/js-angular/目录下安装依赖npm i npm run setup从根目录 package.json 的脚本定义可以看到setup会在根目录、server/、genkit-app/三个子项目下分别执行npm isetup: npm i cd server npm i cd ../genkit-app npm i其中 server/package.json 的关键依赖包括依赖作用genkit(^1.0.4)核心 SDK提供defineFlow、defineAgent、ai.generateStream等genkit-ai/google-genai(^1.17.0)Google Gemini 模型插件genkit-ai/express(^1.17.0)将 Flow 挂载到 Express 的 Flow Serverpartial-json(^0.1.7)解析尚未生成完的残缺 JSON支撑 JSON 流式渲染tsx/genkit-cli开发时以tsx --watch方式热启动 TypeScript 服务三、启动方式与端口启动开发服务器npm run genkit:dev该脚本通过concurrently并行拉起两个进程见根 package.jsongenkit:dev: concurrently npm:start:server npm:start:ng, start:server: cd server npm run genkit:dev, start:ng: cd genkit-app npm run startstart:server执行的是genkit start -- tsx --watch src/index.ts见 server/package.json即通过 Genkit CLI 启动 Flow Server默认监听3400 端口并附带 Genkit Dev UI 与热重载start:ng执行 Angular CLI 的ng serve监听4200 端口。启动后访问http://localhost:4200/即可进入应用。前端路由定义在 app.routes.ts 中包含三个页面/home、/samples/streaming-json角色生成器、/samples/chatbot聊天机器人未匹配路径重定向到 home。四、服务端Flow Server 与两个核心 Flow4.1 Genkit 实例与插件注册服务端入口 server/src/index.ts 只有两件事import { startFlowServer } from genkit-ai/express; import { chatbotFlow } from ./chatbot.js; import { streamCharacters } from ./jsonStreaming.js; startFlowServer({ flows: [chatbotFlow, streamCharacters], });startFlowServer来自genkit-ai/express会把传入的 flows 挂载为 HTTP 端点即前端调用的/chatbotFlow、/streamCharacters。Genkit 实例在 server/src/genkit.ts 中创建并注册 Gemini 插件import { googleAI } from genkit-ai/google-genai; import { genkit } from genkit; export const ai genkit({ plugins: [googleAI()], });4.2 流式 JSON 生成器streamCharacterssamples/js-angular/server/src/jsonStreaming.ts 演示了结构化输出的流式增量渲染是全文技术含量最高的部分。它定义了一个带streamSchema的 Flowconst GameCharactersSchema z.object({ characters: z .array( z.object({ name: z.string().describe(Name of a character), abilities: z .array(z.string()) .describe(Various abilities (strength, magic, archery, etc.)), }).describe(Game character) ).describe(Characters), }); export const streamCharacters ai.defineFlow( { name: streamCharacters, inputSchema: z.number(), // 输入要生成的角色数量 outputSchema: z.string(), // 最终输出完整 JSON 文本 streamSchema: GameCharactersSchema, // 中间流块遵循的结构 }, async (count, { sendChunk }) { const { response, stream } await ai.generateStream({ model: googleAI.model(gemini-flash-latest), output: { format: json, schema: GameCharactersSchema }, config: { temperature: 1 }, prompt: Respond as JSON only. Generate ${count} different RPG game characters., }); let buffer ; for await (const chunk of stream) { buffer chunk.content[0].text!; if (buffer.length 10) { sendChunk(parse(maybeStripMarkdown(buffer), Allow.ALL)); } } return (await response).text; } );实现要点streamSchema是关键机制它声明 Flow 的中间流块chunk符合GameCharactersSchema结构Genkit 会据此向客户端逐块发送部分结构ai.generateStream以output: { format: json, schema: ... }让 Gemini 按约束输出 JSONtemperature: 1保证角色创意多样性partial-json库的parse(buffer, Allow.ALL)负责把还没生成完的残缺 JSON如{characters:[{name:Ar解析为部分对象从而实现前端角色字段逐个长出来的视觉效果sendChunk把每个部分对象推给客户端还有一个防御性细节maybeStripMarkdown用正则剥离模型可能包裹的json代码围栏保证 partial 解析不被 Markdown 标记干扰。4.3 带工具与历史的聊天 AgentchatbotFlowsamples/js-angular/server/src/chatbot.ts 基于通用工厂defineAgent组装出一个具备人设、工具与会话记忆的 Agent Flowexport const chatbotFlow defineAgent(ai, { name: chatbotFlow, model: googleAI.model(gemini-flash-latest), tools: [weatherTool, datePicker], returnToolRequests: true, systemPrompt: You are a helpful agent. You have the personality of Agent Smith from Matrix. ..., historyStore: inMemoryStore(), });它注册了两个UI 型工具weatherTool入参为date与location实现体是空函数async () undefined——真正的天气卡片由前端渲染工具仅作为模型与 UI 之间的信号datePicker一个 UI 工具模型可请求打开日期选择器前端用 Angular Material 的mat-datepicker采集日期后回传。defineAgent的通用逻辑在 server/src/agent.ts 中流程为定义统一的AgentInputconversationIdpromptprompt 可为字符串或 Part 数组兼容工具响应Flow 执行时先用ai.run(retrieve-history, ...)从HistoryStore按conversationId加载历史若无历史且配置了systemPrompt则以系统消息初始化上下文调用ai.generate({ prompt, messages: history, model, tools, returnToolRequests, streamingCallback })发起流式生成streamingCallback来自defineFlow的第二参数是服务端流式输出的直接管道再用ai.run(save-history, ...)把resp.messages写回存储完成多轮记忆的闭环。本示例的historyStore是一个进程内Recordstring, MessageData[]字典inMemoryStore()重启即清空接口HistoryStore { load(id); save(id, history) }是明确的抽象可以推断替换为 Firestore、数据库等持久实现只需实现这两个方法。五、Angular 前端用streamFlow消费流式响应两个页面组件都来自genkit/beta/client的streamFlow发起调用URL 分别指向 Flow Server 的/streamCharacters与/chatbotFlow硬编码http://127.0.0.1:3400/...见组件源码。5.1 流式 JSON 页面StreamingJSONComponentsamples/js-angular/genkit-app/src/app/samples/streaming-json/streaming-json.component.ts 的逻辑非常直接const response streamFlow({ url, // http://127.0.0.1:3400/streamCharacters input: Number.parseInt(this.count), }); for await (const chunk of response.stream) { this.characters chunk; // 每个部分 JSON 对象直接驱动模板渲染 } console.log(streamConsumer done, await response.output);for await...of response.stream持续消费服务端sendChunk推来的部分对象每次更新都会触发 Angular 变更检测实现字段级的渐进渲染流结束后response.output才是服务端最终返回的完整 JSON 文本。5.2 聊天机器人页面ChatbotComponentsamples/js-angular/genkit-app/src/app/samples/chatbot/chatbot.component.ts 演示了带工具交互的完整循环发起提问ask()把用户消息压入history调用callFlow({ role: user, text })流式消费streamFlow({ url, input: { prompt, conversationId: this.id } })逐块消费chunk.content——content.text增量拼接到同一条 model 气泡上首块创建气泡后续追加content.toolRequest则作为独立条目插入历史触发工具 UI工具 UI 渲染模板 chatbot.component.html 用switch (entry.toolRequest.name)按工具名分发——weatherTool渲染一个固定的天气卡片展示请求中的locationdatePicker渲染 Angular Material 日期选择器工具响应回传用户在日期选择器中确认后datePicked()以{ role: user, toolResponse: { name, ref, output } }再次调用callFlow把用户选择作为工具输出送回服务端模型在既有会话上下文中继续回答。这一请求 → 流式文本/工具请求 → UI 收集 → 工具响应的闭环正是returnToolRequests: true服务端与前端toolRequest/toolResponse消息结构组件内定义的InputSchema/OutputSchema接口协同工作的结果服务端把工具调用交还给前端渲染与应答而不是在服务端自行执行示例中两个工具的实现体也是空函数从代码结构看其职责纯粹是信号传递。六、工程结构与延伸阅读samples/js-angular/ ├── package.json # 根脚本setup / genkit:devconcurrently 双进程 ├── server/ │ ├── package.json # genkit genkit-ai/express partial-json │ └── src/ │ ├── index.ts # startFlowServer 入口端口 3400 │ ├── genkit.ts # genkit 实例 googleAI 插件 │ ├── agent.ts # defineAgent 通用工厂历史加载/保存 流式 generate │ ├── chatbot.ts # chatbotFlow工具 人设 内存历史 │ └── jsonStreaming.ts # streamCharactersJSON 约束输出 partial-json 增量流 └── genkit-app/ ├── angular.json # Angular CLI 工程配置 └── src/app/ ├── app.routes.ts # /home、/samples/streaming-json、/samples/chatbot └── samples/ ├── streaming-json/ # 流式 JSON 角色生成器组件 └── chatbot/ # 聊天 工具 UI 组件需要注意的运行前提与限制前端调用地址硬编码为http://127.0.0.1:3400因此要求 Flow Server 与浏览器处于可直连的本机环境跨机器部署时需修改组件内的url常量聊天历史为进程内存级inMemoryStore服务端重启会丢失全部会话示例依赖genkit/beta/client的streamFlowAPI属于示例锁定版本的客户端能力升级 SDK 时应以仓库中package.json声明的版本genkit^1.0.4为准验证兼容性。该示例完整覆盖了 Genkit JS 侧服务端定义流式 Flow → Express 挂载 → 浏览器streamFlow消费的链路是研究 Genkit 流式协议streamSchema、sendChunk、streamingCallback、tool request/response 消息结构的一个高信息密度参照实现。【免费下载链接】genkitOpen-source framework for building agentic apps in JavaScript, Go, Dart, and Python, built and used in production by Google项目地址: https://gitcode.com/GitHub_Trending/ge/genkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考