Genkit JS 开发指南从快速入门到结构化输出、流式生成、工具调用与中断机制【免费下载链接】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/genkitGenkit 是 Google 开源并已在生产环境中使用的 AI 应用框架同时提供 JavaScript、Go、Dart、Python 实现本文聚焦其JavaScript 库的 API 参考文档仓库 js/index.typedoc.md系统讲解从环境搭建、首个生成请求到结构化输出、流式生成、工具调用Function Calling、人工介入中断Interrupts、Dotprompt 提示词管理、Flow 工作流与模型中间件等核心能力。读完本文你将掌握 Genkit JS 的完整上手路径并能够结合仓库源码理解其底层实现机制直接在自己的项目中落地可运行的 AI 应用。一、快速开始环境搭建与首个生成请求Genkit 是面向 AI 驱动应用的开源框架其 JS 库的 API 参考文档为js/index.typedoc.md对应的源码位于 js/genkit 与 js/ai、js/core 三个包中。安装 Genkit 依赖非常简单只需两个步骤genkit—— 框架核心能力包一个模型插件例如使用 Google AI Gemini 模型的genkit-ai/google-genai。在项目目录下执行npm install genkit genkit-ai/google-genai随后配置 API 密钥以 Google AI 为例export GOOGLE_API_KEYyour-api-key接着发起第一个生成请求import { genkit } from genkit; import { googleAI } from genkit-ai/google-genai; const ai genkit({ plugins: [googleAI()] }); const { text } await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: Why is Genkit awesome?, }); console.log(text);从源码看js/genkit/src/index.ts 将Genkit类、genkit()工厂函数及GenkitOptions类型作为主入口导出Genkit类封装了Registry注册表统一管理 actions、flows、tools 等组件、ReflectionServer反射服务器暴露注册表检查与 action 执行 API与FlowServer将 flow 暴露为 HTTP 端点详见 js/genkit/src/genkit.ts。GenkitOptions支持plugins、model默认模型、promptDirdotprompt 目录设为null可禁用自动加载、context、name、clientHeader等配置项见 js/genkit/src/genkit.ts。特别值得注意的是Genkit构造函数在开发环境isDevEnv()下会自动启动 ReflectionServer这正是 Genkit CLI 与开发者工具能够动态发现 actions 的基础。二、包体系与子路径导入js/index.typedoc.md以表格形式列出了当前仓库中全部 JS 包每个包对应一个独立模块文档包名说明genkit核心框架——生成、flows、工具、提示词、流式等genkit-ai/google-genaiGoogle AIGemini模型插件genkit-ai/vertexaiVertex AI 模型插件genkit-ai/firebaseFirebase 集成认证、Firestore、Cloud Functionsgenkit-ai/express将 flows 作为 Express 端点提供genkit-ai/google-cloudGoogle Cloud 监控与遥测genkit-ai/nextNext.js 集成genkit-ai/checksGoogle Checks 安全评估插件genkit-ai/dev-local-vectorstore本地向量库开发用genkit-ai/evaluators内置评估器测试 AI 输出质量genkit-ai/ollamaOllama 本地模型插件genkit-ai/chromaChromaDB 向量库插件genkit-ai/pineconePinecone 向量库插件genkit-ai/mcpModel Context ProtocolMCP插件genkit-ai/anthropicAnthropicClaude模型插件genkit-ai/compat-oaiOpenAI 兼容模型插件genkit-ai/fetch插件用 HTTP fetch 工具genkit-ai/middleware模型中间件插件retry、caching 等genkit-ai/a2uiA2UIAgent-to-UI流式生成式 UI 插件genkit主包还提供针对具体功能的子路径导入便于按需引入、优化打包体积导入路径用途genkit主入口——Genkit类、generate、defineFlow、defineTool、schemas、typesgenkit/betaBeta 特性包括中断defineInterruptgenkit/beta/client客户端辅助函数runFlow、streamFlowgenkit/model/middleware模型中间件retry、fallback、augmentWithContext等genkit/plugin插件编写工具model、embedder、retriever等genkit/model模型类型与辅助函数genkit/embedderEmbedder 类型genkit/retrieverRetriever 与 Indexer 类型genkit/rerankerReranker 类型genkit/evaluatorEvaluator 类型genkit/tool工具类型genkit/schemaSchema 工具以genkit/beta为例js/genkit/src/beta.ts 从genkit主包扩展出了GenkitBeta类、Session、InMemorySessionStore、FileSessionStore、defineInterrupt相关类型以及diff/applyPatchJSON Patch 工具等 Beta 能力同时保留了genkit主入口的全部导出。三、核心特性一结构化输出Structured Output通过 Zod schema 可以生成强类型、经过 schema 校验的结构化输出。Zod schema 由genkit包直接导出import { genkit, z } from genkit无需额外安装import { genkit, z } from genkit; import { googleAI } from genkit-ai/google-genai; const ai genkit({ plugins: [googleAI()] }); const RecipeSchema z.object({ title: z.string(), ingredients: z.array(z.string()), instructions: z.array(z.string()), }); const { output } await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: Invent a new pasta recipe, output: { schema: RecipeSchema }, }); console.log(output?.title); // fully typed当output.schema提供后output字段会严格匹配RecipeSchema的类型定义获得完整 TypeScript 类型推导。这与genkit包中的defineSchema/defineJsonSchemajs/genkit/src/genkit.ts机制一致schema 可注册到 registry 中并在 prompt 里按名称引用从而在提示词与代码之间复用统一的 schema 定义。四、核心特性二流式生成Streaming使用generateStream可以实时接收模型输出流逐块chunk处理文本const { response, stream } ai.generateStream({ model: googleAI.model(gemini-flash-latest), prompt: Write a short story about a robot, }); for await (const chunk of stream) { process.stdout.write(chunk.text); }generateStream返回的stream是异步可迭代对象每个 chunk 暴露text字段response为最终的完整响应对象。流式输出常用于打字机效果、长文本生成与进度反馈场景。此外GenerateOptions还支持onChunk回调见 js/ai/src/generate.ts模型流式生成过程中每个 chunk 都会触发该回调可用于在流式场景中记录日志或更新 UI 状态。五、核心特性三工具调用Function Calling通过ai.defineTool定义工具模型即可在生成过程中自动调用以访问外部数据或执行动作const getWeather ai.defineTool( { name: getWeather, description: Gets the current weather for a given city, inputSchema: z.object({ city: z.string() }), outputSchema: z.object({ temperature: z.number(), condition: z.string() }), }, async ({ city }) { // your implementation here return { temperature: 72, condition: sunny }; } ); const { text } await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: What should I wear in Tokyo today?, tools: [getWeather], });工具的inputSchema/outputSchema不仅提供类型安全还会在运行时对输入输出做校验。Genkit.defineTool底层委托给genkit-ai/ai的defineTool并将工具注册到 registryjs/genkit/src/genkit.ts因此工具可以按名称或引用传入tools数组。GenerateOptions.tools支持传注册的工具名或 action 值js/ai/src/generate.tsmaxTurns控制单次generate调用中工具调用迭代的最大轮数默认 5见 js/ai/src/generate.ts。若希望手动处理工具调用而非自动解析可设置returnToolRequests: true。六、核心特性四中断机制Interrupts人类介入流程Beta 特性Interrupts 需要从genkit/beta导入而不是genkitimport { genkit } from genkit/beta;中断Interrupt会暂停模型处理流程并将控制权交还给调用方从而支持“人在回路”human-in-the-loop工作流。源码层面中断通过抛出一个ToolInterruptError实现js/ai/src/tool.ts框架捕获该错误后将 toolRequest 放入响应并返回给调用方defineInterrupt本质上创建的是一个元数据标记为restartable: false的工具js/ai/src/tool.ts。中断有两种模式6.1 基础中断Basic Interrupts使用defineInterrupt创建一个始终暂停的工具调用方通过.respond()提供响应const confirmAction ai.defineInterrupt({ name: confirmAction, description: Confirm an action with the user before proceeding, inputSchema: z.object({ action: z.string(), reason: z.string() }), outputSchema: z.object({ approved: z.boolean() }), }); let response await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: Book a table for 2 at 7pm tonight, tools: [confirmAction], }); // The model triggered an interrupt — get user approval if (response.interrupts.length) { const interrupt response.interrupts[0]; console.log(interrupt.toolRequest.input); // { action: ..., reason: ... } // Resume with the users response (bypasses tool execution) response await ai.generate({ model: googleAI.model(gemini-flash-latest), messages: response.messages, tools: [confirmAction], resume: { respond: confirmAction.respond(interrupt, { approved: true }), }, }); }流程拆解首次generate触发中断后response.interrupts携带中断详情应用层例如 UI可据此向用户展示确认信息用户批准后通过resume.respond将confirmAction.respond(interrupt, { approved: true })作为人工回复注入新一轮生成该回复会绕过工具执行直接作为 toolResponse 返回给模型。resume选项的完整语义见 js/ai/src/generate.tsrespond中的每条 toolResponse 都必须与最近模型消息中的 toolRequest 的name和ref匹配工具提供的.respond辅助方法会自动完成 schema 校验。6.2 可重启工具Restartable Tools普通工具可以条件性调用interrupt()发起中断并在获得批准后通过.restart()重新执行。resumed标志告知工具其已被批准const sendEmail ai.defineTool( { name: sendEmail, description: Sends an email, inputSchema: z.object({ to: z.string(), body: z.string() }), outputSchema: z.object({ sent: z.boolean() }), }, async (input, { interrupt, resumed }) { if (!resumed) { interrupt({ message: Send email to ${input.to}? }); } // Approved — proceed with sending return { sent: true }; } ); let response await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: Send a hello email to aliceexample.com, tools: [sendEmail], }); if (response.interrupts.length) { const interrupt response.interrupts[0]; // Restart re-executes the tool, this time with resumedtrue response await ai.generate({ model: googleAI.model(gemini-flash-latest), messages: response.messages, tools: [sendEmail], resume: { restart: [sendEmail.restart(interrupt)] }, }); }重启语义在ResumeOptions.restart中定义js/ai/src/generate.tsrestart会以额外元数据再次运行该工具元数据通过第二个参数的resumed选项传递从而支持“先确认 LLM 的工具请求、再执行”的典型审批场景。两种模式的差异在于defineInterrupt创建的工具永远暂停、必须人工回复而可重启工具默认继续执行仅在显式调用interrupt()时才暂停且批准后会自动重新执行同一工具。七、核心特性五Prompt 管理DotpromptGenkit 支持将提示词作为代码进行管理通过 frontmatter 内嵌 schema、模型配置并使用 Handlebars 模板语法--- model: googleai/gemini-flash-latest input: schema: topic: string output: schema: title: string summary: string --- Write a blog post about {{topic}}.在代码中通过名称加载并执行const blogPrompt ai.prompt(blog); const { output } await blogPrompt({ topic: AI safety });ai.prompt(blog)默认从promptDirGenkitOptions.promptDir默认指向项目中的 prompts 目录查找.prompt文件Genkit.prompt还支持通过{ variant }参数选择变体js/genkit/src/genkit.ts。frontmatter 中声明的model、input.schema、output.schema会被自动解析并应用模板中的{{topic}}由 Handlebars 渲染blogPrompt({ topic: AI safety })即为一次带类型校验的提示词调用。仓库中的真实示例可参考 samples/js-prompts 与 js/testapps/prompt-file。八、核心特性六Flows可观测工作流与 API 服务Flow 用于构建强类型、完全可观测的工作流既能作为 API 提供服务也能从客户端访问import { genkit, z } from genkit; import { googleAI } from genkit-ai/google-genai; const ai genkit({ plugins: [googleAI()], model: googleAI.model(gemini-flash-latest), }); const RecipeSchema z.object({ title: z.string(), ingredients: z.array(z.string()), instructions: z.array(z.string()), }); export const recipeFlow ai.defineFlow( { name: recipeFlow, inputSchema: z.object({ ingredient: z.string() }), outputSchema: RecipeSchema, }, async (input) { const { output } await ai.generate({ prompt: Create a recipe using ${input.ingredient}, output: { schema: RecipeSchema }, }); if (!output) throw new Error(Failed to generate recipe); return output; } );ai.defineFlow将 flow 注册进 registry 并追加到Genkit.flows列表js/genkit/src/genkit.ts每个 flow 拥有独立的输入/输出 schema 校验与分布式追踪能力。8.1 作为 API 服务使用 Express 插件把 flow 暴露为 HTTP 端点import { startFlowServer } from genkit-ai/express; // npm i genkit-ai/express startFlowServer({ flows: [recipeFlow] });startFlowServer定义于 js/plugins/express/src/index.ts默认监听http://localhost:3400Express 插件端口将传入的 flows 数组逐一映射为对应路径的 HTTP 端点。除 Express 外仓库还提供 Fastifyjs/plugins/fastify与 Hono 等适配方案详见 js/testapps/hono。8.2 客户端访问与流式消费使用genkit/beta/client中的streamFlow从客户端消费 flowimport { streamFlow } from genkit/beta/client; const { stream } streamFlow({ url: http://localhost:3500/recipeFlow, input: { ingredient: avocado }, }); for await (const chunk of stream) { console.log(chunk); }streamFlow以流式方式拉取 flow 的输出配合runFlow一次性获取完整结果使用让浏览器/客户端能够实时展示 flow 执行进度。默认端口示例:3500为 Express flow server 的常见端口实际端口以startFlowServer配置为准。九、核心特性七模型中间件Middleware中间件可为 AI 请求统一附加通用能力来源于genkit/model/middleware与genkit-ai/middleware两个入口。以重试中间件为例import { retry } from genkit/model/middleware; const { text } await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: Why is Genkit awesome?, use: [ retry({ maxRetries: 3, initialDelayMs: 1000, backoffFactor: 2, }), ], });retry中间件的完整默认值与行为可结合源码 js/ai/src/model/middleware.ts 理解maxRetries最大重试次数默认3statuses可重试的 HTTP 状态码集合默认DEFAULT_RETRY_STATUSES主要是 429/5xx 等瞬时错误initialDelayMs首次重试前的延迟默认1000毫秒maxDelayMs延迟上限默认60000毫秒backoffFactor指数退避系数默认2noJitter是否禁用抖动jitter默认false启用时会在延迟中加入随机量以避免惊群效应onError每次重试前的回调钩子。特别地AbortError与ToolInterruptError被列入NEVER_RETRY_ERROR_NAMESjs/ai/src/model/middleware.ts即中止请求与工具中断导致的错误永远不会重试。中间件通过GenerateOptions.use传入js/ai/src/generate.ts除retry外还包括fallback、augmentWithContext等可在 js/ai/src/model/middleware.ts 中查阅完整清单。十、更多资源与深入阅读在仓库内可以继续深入以下内容完整 API 参考与教程以本文对应的 js/index.typedoc.md 为索引逐包阅读模块文档开发者工具CLI 与 Developer UICLI 源码位于 genkit-tools/cli开发者工具服务器实现见 genkit-tools/common/src/server模型插件实现Gemini 插件源码见 js/plugins/google-genaiOpenAI 兼容插件见 js/plugins/compat-oaiOllama 本地模型插件见 js/plugins/ollamaFlow 服务部署Express 插件 js/plugins/express、Fastify 插件 js/plugins/fastify、Firebase 集成 js/plugins/firebaseMCP 集成Model Context Protocol 插件 js/plugins/mcp可运行示例仓库内置大量可直接运行的测试应用涵盖工具调用、中断、流式、多 Agent 等场景见 js/testapps 与 samples 目录。综上从一次简单的ai.generate调用出发Genkit JS 通过注册表驱动的组件体系将模型、工具、Flow、Prompt、中间件统一纳入一个可观测、可调试、可扩展的框架之中genkit主包负责核心编排genkit/beta提供人类介入等前沿能力各genkit-ai/*插件则按需接入模型、向量库、框架适配器与可观测性服务。这正是 Genkit 在 Google 内部及外部生产环境中被广泛使用的原因所在。【免费下载链接】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），仅供参考 Genkit JS 开发指南：从快速入门到结构化输出、流式生成、工具调用与中断机制
Genkit JS 开发指南从快速入门到结构化输出、流式生成、工具调用与中断机制【免费下载链接】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/genkitGenkit 是 Google 开源并已在生产环境中使用的 AI 应用框架同时提供 JavaScript、Go、Dart、Python 实现本文聚焦其JavaScript 库的 API 参考文档仓库 js/index.typedoc.md系统讲解从环境搭建、首个生成请求到结构化输出、流式生成、工具调用Function Calling、人工介入中断Interrupts、Dotprompt 提示词管理、Flow 工作流与模型中间件等核心能力。读完本文你将掌握 Genkit JS 的完整上手路径并能够结合仓库源码理解其底层实现机制直接在自己的项目中落地可运行的 AI 应用。一、快速开始环境搭建与首个生成请求Genkit 是面向 AI 驱动应用的开源框架其 JS 库的 API 参考文档为js/index.typedoc.md对应的源码位于 js/genkit 与 js/ai、js/core 三个包中。安装 Genkit 依赖非常简单只需两个步骤genkit—— 框架核心能力包一个模型插件例如使用 Google AI Gemini 模型的genkit-ai/google-genai。在项目目录下执行npm install genkit genkit-ai/google-genai随后配置 API 密钥以 Google AI 为例export GOOGLE_API_KEYyour-api-key接着发起第一个生成请求import { genkit } from genkit; import { googleAI } from genkit-ai/google-genai; const ai genkit({ plugins: [googleAI()] }); const { text } await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: Why is Genkit awesome?, }); console.log(text);从源码看js/genkit/src/index.ts 将Genkit类、genkit()工厂函数及GenkitOptions类型作为主入口导出Genkit类封装了Registry注册表统一管理 actions、flows、tools 等组件、ReflectionServer反射服务器暴露注册表检查与 action 执行 API与FlowServer将 flow 暴露为 HTTP 端点详见 js/genkit/src/genkit.ts。GenkitOptions支持plugins、model默认模型、promptDirdotprompt 目录设为null可禁用自动加载、context、name、clientHeader等配置项见 js/genkit/src/genkit.ts。特别值得注意的是Genkit构造函数在开发环境isDevEnv()下会自动启动 ReflectionServer这正是 Genkit CLI 与开发者工具能够动态发现 actions 的基础。二、包体系与子路径导入js/index.typedoc.md以表格形式列出了当前仓库中全部 JS 包每个包对应一个独立模块文档包名说明genkit核心框架——生成、flows、工具、提示词、流式等genkit-ai/google-genaiGoogle AIGemini模型插件genkit-ai/vertexaiVertex AI 模型插件genkit-ai/firebaseFirebase 集成认证、Firestore、Cloud Functionsgenkit-ai/express将 flows 作为 Express 端点提供genkit-ai/google-cloudGoogle Cloud 监控与遥测genkit-ai/nextNext.js 集成genkit-ai/checksGoogle Checks 安全评估插件genkit-ai/dev-local-vectorstore本地向量库开发用genkit-ai/evaluators内置评估器测试 AI 输出质量genkit-ai/ollamaOllama 本地模型插件genkit-ai/chromaChromaDB 向量库插件genkit-ai/pineconePinecone 向量库插件genkit-ai/mcpModel Context ProtocolMCP插件genkit-ai/anthropicAnthropicClaude模型插件genkit-ai/compat-oaiOpenAI 兼容模型插件genkit-ai/fetch插件用 HTTP fetch 工具genkit-ai/middleware模型中间件插件retry、caching 等genkit-ai/a2uiA2UIAgent-to-UI流式生成式 UI 插件genkit主包还提供针对具体功能的子路径导入便于按需引入、优化打包体积导入路径用途genkit主入口——Genkit类、generate、defineFlow、defineTool、schemas、typesgenkit/betaBeta 特性包括中断defineInterruptgenkit/beta/client客户端辅助函数runFlow、streamFlowgenkit/model/middleware模型中间件retry、fallback、augmentWithContext等genkit/plugin插件编写工具model、embedder、retriever等genkit/model模型类型与辅助函数genkit/embedderEmbedder 类型genkit/retrieverRetriever 与 Indexer 类型genkit/rerankerReranker 类型genkit/evaluatorEvaluator 类型genkit/tool工具类型genkit/schemaSchema 工具以genkit/beta为例js/genkit/src/beta.ts 从genkit主包扩展出了GenkitBeta类、Session、InMemorySessionStore、FileSessionStore、defineInterrupt相关类型以及diff/applyPatchJSON Patch 工具等 Beta 能力同时保留了genkit主入口的全部导出。三、核心特性一结构化输出Structured Output通过 Zod schema 可以生成强类型、经过 schema 校验的结构化输出。Zod schema 由genkit包直接导出import { genkit, z } from genkit无需额外安装import { genkit, z } from genkit; import { googleAI } from genkit-ai/google-genai; const ai genkit({ plugins: [googleAI()] }); const RecipeSchema z.object({ title: z.string(), ingredients: z.array(z.string()), instructions: z.array(z.string()), }); const { output } await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: Invent a new pasta recipe, output: { schema: RecipeSchema }, }); console.log(output?.title); // fully typed当output.schema提供后output字段会严格匹配RecipeSchema的类型定义获得完整 TypeScript 类型推导。这与genkit包中的defineSchema/defineJsonSchemajs/genkit/src/genkit.ts机制一致schema 可注册到 registry 中并在 prompt 里按名称引用从而在提示词与代码之间复用统一的 schema 定义。四、核心特性二流式生成Streaming使用generateStream可以实时接收模型输出流逐块chunk处理文本const { response, stream } ai.generateStream({ model: googleAI.model(gemini-flash-latest), prompt: Write a short story about a robot, }); for await (const chunk of stream) { process.stdout.write(chunk.text); }generateStream返回的stream是异步可迭代对象每个 chunk 暴露text字段response为最终的完整响应对象。流式输出常用于打字机效果、长文本生成与进度反馈场景。此外GenerateOptions还支持onChunk回调见 js/ai/src/generate.ts模型流式生成过程中每个 chunk 都会触发该回调可用于在流式场景中记录日志或更新 UI 状态。五、核心特性三工具调用Function Calling通过ai.defineTool定义工具模型即可在生成过程中自动调用以访问外部数据或执行动作const getWeather ai.defineTool( { name: getWeather, description: Gets the current weather for a given city, inputSchema: z.object({ city: z.string() }), outputSchema: z.object({ temperature: z.number(), condition: z.string() }), }, async ({ city }) { // your implementation here return { temperature: 72, condition: sunny }; } ); const { text } await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: What should I wear in Tokyo today?, tools: [getWeather], });工具的inputSchema/outputSchema不仅提供类型安全还会在运行时对输入输出做校验。Genkit.defineTool底层委托给genkit-ai/ai的defineTool并将工具注册到 registryjs/genkit/src/genkit.ts因此工具可以按名称或引用传入tools数组。GenerateOptions.tools支持传注册的工具名或 action 值js/ai/src/generate.tsmaxTurns控制单次generate调用中工具调用迭代的最大轮数默认 5见 js/ai/src/generate.ts。若希望手动处理工具调用而非自动解析可设置returnToolRequests: true。六、核心特性四中断机制Interrupts人类介入流程Beta 特性Interrupts 需要从genkit/beta导入而不是genkitimport { genkit } from genkit/beta;中断Interrupt会暂停模型处理流程并将控制权交还给调用方从而支持“人在回路”human-in-the-loop工作流。源码层面中断通过抛出一个ToolInterruptError实现js/ai/src/tool.ts框架捕获该错误后将 toolRequest 放入响应并返回给调用方defineInterrupt本质上创建的是一个元数据标记为restartable: false的工具js/ai/src/tool.ts。中断有两种模式6.1 基础中断Basic Interrupts使用defineInterrupt创建一个始终暂停的工具调用方通过.respond()提供响应const confirmAction ai.defineInterrupt({ name: confirmAction, description: Confirm an action with the user before proceeding, inputSchema: z.object({ action: z.string(), reason: z.string() }), outputSchema: z.object({ approved: z.boolean() }), }); let response await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: Book a table for 2 at 7pm tonight, tools: [confirmAction], }); // The model triggered an interrupt — get user approval if (response.interrupts.length) { const interrupt response.interrupts[0]; console.log(interrupt.toolRequest.input); // { action: ..., reason: ... } // Resume with the users response (bypasses tool execution) response await ai.generate({ model: googleAI.model(gemini-flash-latest), messages: response.messages, tools: [confirmAction], resume: { respond: confirmAction.respond(interrupt, { approved: true }), }, }); }流程拆解首次generate触发中断后response.interrupts携带中断详情应用层例如 UI可据此向用户展示确认信息用户批准后通过resume.respond将confirmAction.respond(interrupt, { approved: true })作为人工回复注入新一轮生成该回复会绕过工具执行直接作为 toolResponse 返回给模型。resume选项的完整语义见 js/ai/src/generate.tsrespond中的每条 toolResponse 都必须与最近模型消息中的 toolRequest 的name和ref匹配工具提供的.respond辅助方法会自动完成 schema 校验。6.2 可重启工具Restartable Tools普通工具可以条件性调用interrupt()发起中断并在获得批准后通过.restart()重新执行。resumed标志告知工具其已被批准const sendEmail ai.defineTool( { name: sendEmail, description: Sends an email, inputSchema: z.object({ to: z.string(), body: z.string() }), outputSchema: z.object({ sent: z.boolean() }), }, async (input, { interrupt, resumed }) { if (!resumed) { interrupt({ message: Send email to ${input.to}? }); } // Approved — proceed with sending return { sent: true }; } ); let response await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: Send a hello email to aliceexample.com, tools: [sendEmail], }); if (response.interrupts.length) { const interrupt response.interrupts[0]; // Restart re-executes the tool, this time with resumedtrue response await ai.generate({ model: googleAI.model(gemini-flash-latest), messages: response.messages, tools: [sendEmail], resume: { restart: [sendEmail.restart(interrupt)] }, }); }重启语义在ResumeOptions.restart中定义js/ai/src/generate.tsrestart会以额外元数据再次运行该工具元数据通过第二个参数的resumed选项传递从而支持“先确认 LLM 的工具请求、再执行”的典型审批场景。两种模式的差异在于defineInterrupt创建的工具永远暂停、必须人工回复而可重启工具默认继续执行仅在显式调用interrupt()时才暂停且批准后会自动重新执行同一工具。七、核心特性五Prompt 管理DotpromptGenkit 支持将提示词作为代码进行管理通过 frontmatter 内嵌 schema、模型配置并使用 Handlebars 模板语法--- model: googleai/gemini-flash-latest input: schema: topic: string output: schema: title: string summary: string --- Write a blog post about {{topic}}.在代码中通过名称加载并执行const blogPrompt ai.prompt(blog); const { output } await blogPrompt({ topic: AI safety });ai.prompt(blog)默认从promptDirGenkitOptions.promptDir默认指向项目中的 prompts 目录查找.prompt文件Genkit.prompt还支持通过{ variant }参数选择变体js/genkit/src/genkit.ts。frontmatter 中声明的model、input.schema、output.schema会被自动解析并应用模板中的{{topic}}由 Handlebars 渲染blogPrompt({ topic: AI safety })即为一次带类型校验的提示词调用。仓库中的真实示例可参考 samples/js-prompts 与 js/testapps/prompt-file。八、核心特性六Flows可观测工作流与 API 服务Flow 用于构建强类型、完全可观测的工作流既能作为 API 提供服务也能从客户端访问import { genkit, z } from genkit; import { googleAI } from genkit-ai/google-genai; const ai genkit({ plugins: [googleAI()], model: googleAI.model(gemini-flash-latest), }); const RecipeSchema z.object({ title: z.string(), ingredients: z.array(z.string()), instructions: z.array(z.string()), }); export const recipeFlow ai.defineFlow( { name: recipeFlow, inputSchema: z.object({ ingredient: z.string() }), outputSchema: RecipeSchema, }, async (input) { const { output } await ai.generate({ prompt: Create a recipe using ${input.ingredient}, output: { schema: RecipeSchema }, }); if (!output) throw new Error(Failed to generate recipe); return output; } );ai.defineFlow将 flow 注册进 registry 并追加到Genkit.flows列表js/genkit/src/genkit.ts每个 flow 拥有独立的输入/输出 schema 校验与分布式追踪能力。8.1 作为 API 服务使用 Express 插件把 flow 暴露为 HTTP 端点import { startFlowServer } from genkit-ai/express; // npm i genkit-ai/express startFlowServer({ flows: [recipeFlow] });startFlowServer定义于 js/plugins/express/src/index.ts默认监听http://localhost:3400Express 插件端口将传入的 flows 数组逐一映射为对应路径的 HTTP 端点。除 Express 外仓库还提供 Fastifyjs/plugins/fastify与 Hono 等适配方案详见 js/testapps/hono。8.2 客户端访问与流式消费使用genkit/beta/client中的streamFlow从客户端消费 flowimport { streamFlow } from genkit/beta/client; const { stream } streamFlow({ url: http://localhost:3500/recipeFlow, input: { ingredient: avocado }, }); for await (const chunk of stream) { console.log(chunk); }streamFlow以流式方式拉取 flow 的输出配合runFlow一次性获取完整结果使用让浏览器/客户端能够实时展示 flow 执行进度。默认端口示例:3500为 Express flow server 的常见端口实际端口以startFlowServer配置为准。九、核心特性七模型中间件Middleware中间件可为 AI 请求统一附加通用能力来源于genkit/model/middleware与genkit-ai/middleware两个入口。以重试中间件为例import { retry } from genkit/model/middleware; const { text } await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: Why is Genkit awesome?, use: [ retry({ maxRetries: 3, initialDelayMs: 1000, backoffFactor: 2, }), ], });retry中间件的完整默认值与行为可结合源码 js/ai/src/model/middleware.ts 理解maxRetries最大重试次数默认3statuses可重试的 HTTP 状态码集合默认DEFAULT_RETRY_STATUSES主要是 429/5xx 等瞬时错误initialDelayMs首次重试前的延迟默认1000毫秒maxDelayMs延迟上限默认60000毫秒backoffFactor指数退避系数默认2noJitter是否禁用抖动jitter默认false启用时会在延迟中加入随机量以避免惊群效应onError每次重试前的回调钩子。特别地AbortError与ToolInterruptError被列入NEVER_RETRY_ERROR_NAMESjs/ai/src/model/middleware.ts即中止请求与工具中断导致的错误永远不会重试。中间件通过GenerateOptions.use传入js/ai/src/generate.ts除retry外还包括fallback、augmentWithContext等可在 js/ai/src/model/middleware.ts 中查阅完整清单。十、更多资源与深入阅读在仓库内可以继续深入以下内容完整 API 参考与教程以本文对应的 js/index.typedoc.md 为索引逐包阅读模块文档开发者工具CLI 与 Developer UICLI 源码位于 genkit-tools/cli开发者工具服务器实现见 genkit-tools/common/src/server模型插件实现Gemini 插件源码见 js/plugins/google-genaiOpenAI 兼容插件见 js/plugins/compat-oaiOllama 本地模型插件见 js/plugins/ollamaFlow 服务部署Express 插件 js/plugins/express、Fastify 插件 js/plugins/fastify、Firebase 集成 js/plugins/firebaseMCP 集成Model Context Protocol 插件 js/plugins/mcp可运行示例仓库内置大量可直接运行的测试应用涵盖工具调用、中断、流式、多 Agent 等场景见 js/testapps 与 samples 目录。综上从一次简单的ai.generate调用出发Genkit JS 通过注册表驱动的组件体系将模型、工具、Flow、Prompt、中间件统一纳入一个可观测、可调试、可扩展的框架之中genkit主包负责核心编排genkit/beta提供人类介入等前沿能力各genkit-ai/*插件则按需接入模型、向量库、框架适配器与可观测性服务。这正是 Genkit 在 Google 内部及外部生产环境中被广泛使用的原因所在。【免费下载链接】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），仅供参考