使用 Genkit JS 开发 AI 应用Flow、Agent、Dotprompt 与 CLI 调试实战指南【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills导读本文以开源仓库 skills29/skills 中的 Genkit JS Skill 为核心系统讲解如何在 Node.js/TypeScript 中使用 Google 官方 AI 编排框架Genkit开发 AI 应用从genkit实例初始化、defineFlow定义首个生成式流程到 Dotprompt 提示词工程、Beta 版 Agent 多轮对话、中间件Middleware横切能力再到genkit start/flow:run/trace系列 CLI 的调试与验证工作流。读完本文你将掌握一套可复制、可验证的 Genkit 开发闭环编写代码 → CLI 捕获 Trace → 依据 Trace 定位错误 → 依据官方文档修复并清楚区分 v1.x 与 pre-1.0 的破坏性 API 差异避免踩坑。注意本文所有能力均以仓库文档与源码为事实依据。Genkit 正处于快速演进期Agent API 为 Beta 预览状态相关导入路径、函数签名与版本号以文中标注的版本要求为准。环境前置genkit CLI 版本要求开发 Genkit JS 应用的第一步是确保命令行工具genkit可用且版本满足要求。运行genkit --version验证版本最低要求为 1.29.0若命令不存在或版本为 1.x 且低于 1.29.0请升级npm install -g genkit-cli^1.29.0新项目接入如果是在全新代码库中初始化 Genkit不要跳过配置步骤建议直接阅读仓库中的 Setup 指南——它给出了完整的项目脚手架流程创建ai/genkit.ts、ai/flows、ai/tools目录结构、将genkit-cli加入 devDependencies 并添加genkit:dev脚本等。CLI 版本说明同样记录在 Docs CLI Reference 中若不想全局安装也可以用npx -y genkit-cli^1.29.0前缀临时指定版本运行。Hello World用defineFlow定义第一个生成流程Genkit v1.x 的入口是genkit()工厂函数。它接收插件列表返回一个ai实例所有能力生成、流程、提示词、工具、Agent都挂在该实例上。以下是最小可运行示例import { z, genkit } from genkit; import { googleAI } from genkit-ai/google-genai; // 初始化 Genkit挂载 Google AI 插件 const ai genkit({ plugins: [googleAI()], }); export const myFlow ai.defineFlow({ name: myFlow, inputSchema: z.string().default(AI), outputSchema: z.string(), }, async (subject) { const response await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: Tell me a joke about ${subject}, }); return response.text; });几个值得注意的 v1.x 要点z必须从genkit包导入而不是直接引zodinputSchema/outputSchema用 Zod 描述输入输出flow:run时会对入参做校验模型引用使用插件工厂googleAI.model(gemini-flash-latest)优先使用*-latest别名而非带版本号的旧模型详见后文迁移一节响应对象属性是直接访问response.text不是response.text()。更多可复现的最小示例基础文本生成、结构化输出、流式生成、思考模式、Google Search Grounding、图像生成/编辑、TTS 语音生成可在 Examples 中找到例如结构化输出用output: { schema: JokeSchema }让response.output获得强类型。Dotprompt把提示词搬进.prompt文件把提示词内联在 TypeScript 里不利于迭代与变体管理。Genkit 的Dotprompt用.prompt文件承载提示词YAML frontmatter 描述模型、输入输出 schema、工具与中间件正文用 Handlebars 模板渲染。加载位置与promptDir默认从./prompts目录自动加载.prompt文件可通过promptDir选项配置设为null可关闭自动加载import { genkit } from genkit; import { googleAI } from genkit-ai/google-genai; const ai genkit({ plugins: [googleAI()], promptDir: ./prompts, // default });文件格式示例prompts/recipe.prompt--- model: googleai/gemini-pro-latest input: schema: food: string ingredients?(array): string # ? optional output: schema: Recipe # 引用通过 ai.defineSchema 注册的命名 schema --- You are a chef famous for creative recipes. Generate a recipe for {{food}}. {{#if ingredients}} Make sure to include the following ingredients: {{list ingredients}} {{/if}}Schema 字段既可使用紧凑的 Picoschema 语法如上也可通过ai.defineSchema注册命名 schema 后在 frontmatter 中按名引用。详细说明见 Dotprompt 参考。加载与调用ai.prompt()ai.prompt(name, { variant? })返回可调用的ExecutablePrompt同时提供.stream()、.render()、.asTool()// 非流式直接以输入对象调用 const recipePrompt ai.prompt(recipe); const { output } await recipePrompt({ food: banana bread }); // 流式 const storyPrompt ai.prompt(story); const { response, stream } storyPrompt.stream({ subject: a robot }); for await (const chunk of stream) { console.log(chunk.text); } const final await response; // 只渲染不生成适合拼 ai.generate 或 LLM-judge 评测 const rendered await ai.prompt(recipe).render({ food: banana bread }); // rendered 是一个 GenerateOptions 对象messages、model、config、...变体、Partials 与 Helper变体Variants命名文件为name.variant.prompt如recipe.robot.prompt调用时传{ variant: robot }Partials以_name.prompt命名可复用片段模板中用{{name paramvalue}}引入Helper用ai.defineHelper(list, fn)注册模板内可调用的函数如{{list ingredients}}。frontmatter 中的工具与控制字段.prompt的 frontmatter 可直接声明工具调用与中间件让Agent 风格的提示词在文件内自洽描述--- model: googleai/gemini-flash-latest input: schema: tone: string tools: - getAttractions - getFlightInfo toolChoice: auto # auto | required | none maxTurns: 20 # 最大工具调用循环轮数 returnToolRequests: false # true 时返回工具请求而不实际执行 use: - name: retry # 也支持裸字符串- retry config: maxRetries: 4 --- {{role system}} You are a friendly trip planning assistant. Help users plan trips by suggesting attractions and looking up flight information. Keep your tone {{tone}}. {{history}}use中的中间件名会解析到注册在 Genkit 实例上的中间件因此需要把中间件以插件形式注册import { retry } from genkit-ai/middleware; const ai genkit({ plugins: [googleAI(), retry.plugin()], promptDir: ./prompts, });注意AgentdefineAgent与.prompt共享同一套 frontmatter 字段system/prompt、tools、maxTurns、returnToolRequests、use一个带{{history}}和工具声明的.prompt文件可以直接支撑一个 Agent。AgentsBeta持久化多轮对话Genkit 提供了预览版AgentAPI用于持久化、多轮对话场景会话、快照、中断、分支、后台执行。⚠️Beta 说明Agent API 尚未稳定。服务端 API 从genkit/beta导入浏览器客户端从genkit/beta/client导入——不是稳定的genkit入口。要求genkit 1.39.0。导入路径与函数签名可能变动始终使用genkit/beta前缀。与裸ai.generate 工具循环相比Agent 额外提供Sessions以不可变**快照snapshot**形式记录多轮历史State类型化会话状态消息 自定义数据 artifactsInterrupts人机协同的暂停/恢复Branching从任意快照分叉对话Detaching后台运行一轮并轮询结果。定义与使用 Agent// genkit.ts —— 注意 agents 需要从 genkit/beta 导入 import { genkit } from genkit/beta; import { googleAI } from genkit-ai/google-genai; export const ai genkit({ plugins: [googleAI()], model: googleAI.model(gemini-flash-latest), });import { z } from genkit; import { ai } from ./genkit.js; const getWeather ai.defineTool( { name: getWeather, description: Look up the current weather for a city., inputSchema: z.object({ city: z.string() }), outputSchema: z.object({ tempC: z.number(), summary: z.string() }), }, async ({ city }) ({ tempC: 21, summary: Sunny }) ); export const weatherAgent ai.defineAgent({ name: weatherAgent, system: You are a helpful weather assistant. Use the getWeather tool. Be concise., tools: [getWeather], // store 可选。省略即采用客户端托管状态见下文。 });常用defineAgent选项name必填action 名称system/prompt/ dotprompt 字段与definePrompt相同toolsAgent 可用的工具与中断model覆盖默认模型store服务端持久化的SessionStorestateSchemaz.ZodTypeState描述自定义会话状态设置后State在加载时被推断并校验input/inputSchema提示词模板的输入变量。const chat weatherAgent.chat(); // 非流式一轮历史自动延续 const res await chat.send(Weather in Tokyo?); console.log(res.text); console.log(res.snapshotId); // 本轮不可变检查点 id const res2 await chat.send(What about Paris?); // 流式一轮 const turn chat.sendStream(And London?); for await (const chunk of turn.stream) { process.stdout.write(chunk.text ?? ); } const final await turn.response;会话持久化Session Store当 Agent 配置了store时服务端持有会话历史每轮产生不可变快照快照链承载对话状态同时支持分支与后台执行。内置三种存储import { InMemorySessionStore, FileSessionStore } from genkit/beta; // 内存适合测试/开发重启即丢失 const memStore new InMemorySessionStore(); // 文件快照持久化到 dir/global/snapshotId.json const fileStore new FileSessionStore(./.snapshots); // 文件 链裁剪每条链只保留最近 N 个快照 const pruning new FileSessionStore(./.snapshots, { maxPersistedChainLength: 3, });挂载到 Agent 后可用chat({ snapshotId })从某快照恢复会话stateSchema可为会话附加类型化自定义状态存于SessionState的.custom字段const profileAgent ai.defineAgent({ name: profileAgent, system: Greet the user by name and tailor answers to their tier., store: new InMemorySessionStorez.infertypeof Profile(), stateSchema: Profile, }); const chat profileAgent.chat({ state: { custom: { name: Ada, tier: pro } }, });生产级方案FirestoreSessionStore来自genkit-ai/google-cloud/beta将每轮持久化为增量 JSON Patch diff锚定在周期性分片检查点上避免单个文档触及 Firestore 1 MiB 上限每轮读写量由checkpointInterval默认 25 轮全量检查点约束适合长会话的聊天/编码 Agent。也支持实现自定义SessionStore接口getSnapshot/saveSnapshot/onSnapshotStateChange。详见 Sessions persistence。客户端托管状态无 store如果 Agent不配store服务端完全无状态会话状态 blob消息 自定义数据 artifacts归调用方所有。remoteAgent客户端来自genkit/beta/client会自动在每轮请求间往返携带状态无需管理快照 id// 服务端无 store → 无状态客户端持有状态 blob export const weatherAgentStateless ai.defineAgent({ name: weatherAgentStateless, system: You are a helpful weather assistant. Use getWeather. Be concise., tools: [getWeather], });// 客户端复用同一个 chat状态自动串接 import { remoteAgent, type AgentChat } from genkit/beta/client; const agent remoteAgent({ url: /api/weatherAgentStateless }); const chat: AgentChat agent.chat(); await chat.send(Weather in London?); await chat.send(Is it sunny in Tokyo?); // 记得之前的轮次 const res await chat.send(And Paris?); console.log(JSON.stringify(res.raw.state, null, 2));选择建议不想在服务端运行存储客户端自行持久化历史时用客户端托管状态希望服务端持有历史或需要分支/后台执行时用 Session Store中断两种方式都支持。通过 HTTP 提供 Agent用genkit-ai/express的expressHandler暴露 Agent可选挂载配套的getSnapshotDataAction快照查找/恢复与abortAgentAction后台中断import { expressHandler } from genkit-ai/express; import express from express; import { weatherAgent } from ./weather-agent.js; const app express(); app.use(express.json()); app.post(/api/weatherAgent, expressHandler(weatherAgent)); app.post( /api/weatherAgent/getSnapshot, expressHandler(weatherAgent.getSnapshotDataAction) ); app.post( /api/weatherAgent/abort, expressHandler(weatherAgent.abortAgentAction) ); app.listen(8080);浏览器端通过remoteAgent拿到类型化 HTTP 客户端getSnapshotUrl/abortUrl默认指向${url}/getSnapshot与${url}/abort。多 Agent 服务、CORS/流式响应头、静态 Web UI 及 Next.js/Firebase 等宿主框架的细节见 Deploying agents。Agent 生态的其余主题——人机协同中断agents-human-in-the-loop.md、分支agents-branching.md、后台执行agents-background.md、类型化状态agents-state.md、Artifactsagents-artifacts.md、多 Agent 编排agents-multi-agent.md、defineCustomAgent全控制agents-custom.md——均在 Agents 参考 中有渐进式指引。Middleware给生成过程叠加横切能力中间件包装生成过程以增加横切行为——重试、回退、附加工具、请求/响应变换等。通过use: [...]数组挂载该数组在ai.generate/ai.generateStream、可执行提示词definePrompt和 AgentdefineAgent上都可用import { retry } from genkit-ai/middleware; const res await ai.generate({ model: googleAI.model(gemini-flash-latest), prompt: Say hello, use: [retry({ maxRetries: 2 })], });务必通过.plugin()注册中间件——不注册时在use: [...]中也能工作但不会出现在 Genkit Dev UI 中import { genkit } from genkit; import { googleAI } from genkit-ai/google-genai; import { retry, artifacts } from genkit-ai/middleware; export const ai genkit({ plugins: [googleAI(), retry.plugin(), artifacts.plugin()], });genkit-ai/middleware内置工厂npm i genkit-ai/middleware中间件作用关键选项retry(options?)瞬时错误指数退避重试maxRetries: 3、initialDelayMs: 1000、maxDelayMs: 60000、backoffFactor: 2、noJitter: false默认状态码UNAVAILABLE, DEADLINE_EXCEEDED, RESOURCE_EXHAUSTED, ABORTED, INTERNALfallback(options)主模型失败时回退到其他模型models: [...]按序尝试、isolateConfig: false默认状态码额外含NOT_FOUND, UNIMPLEMENTEDartifacts(options?)注入write_artifact/read_artifact工具readonly: falsetrue 时仅read_artifactagents(options)子 Agent 委派每个子 Agent 注入一个delegate_to_name工具agents: [researcher, coder]、maxDelegations: 5filesystem(options)授予模型list_files/read_file/write_file/search_and_replace工具沙箱限定根目录rootDirectory必填、allowWriteAccess: false、toolNamePrefix: skills(options?)扫描目录中的 skill 文件frontmattername/description向系统提示词注入清单并提供use_skill工具skillPaths: [skills]toolApproval(options)工具执行白名单白名单外抛ToolInterruptError可经中断恢复approved: [getWeather, search]核心内置模型中间件部分中间件随genkit核心提供无需额外包从genkit/model/middleware导入downloadRequestMedia({ maxBytes? })——抓取 URL 媒体并内联validateSupport({ name, ... })——断言模型支持所请求的特性simulateSystemPrompt({ preface? })——为不支持 system prompt 的模型模拟augmentWithContext(options?)——注入检索到的上下文文档simulateConstrainedGeneration(options?)——模拟受约束/JSON 输出。import { simulateConstrainedGeneration } from genkit/model/middleware; await ai.generate({ model: someModel, prompt: ..., use: [simulateConstrainedGeneration()], });Agent 与中间件的组合Agent 与中间件是天然搭配use: [...]数组是叠加复杂行为的入口。一个完整的编码助手 Agent 几乎全是配置import { filesystem, retry, skills, toolApproval } from genkit-ai/middleware; import { FileSessionStore } from genkit/beta; import { ai } from ./genkit.js; export const codingAgent ai.defineAgent({ name: codingAgent, system: You are an expert AI coding assistant working in a sandboxed workspace., tools: [runShell, askUser], // 你自己的工具/中断 use: [ // 风险工具执行前要求用户批准中断读取类自动放行。 // 顺序很重要toolApproval 需放在 filesystem 之前。 toolApproval({ approved: [list_files, read_file, use_skill, run_shell, ask_user], }), // list_files / read_file / write_file / search_and_replace沙箱限定。 filesystem({ rootDirectory: WORKSPACE_DIR, allowWriteAccess: true }), // 通过 use_skill 工具按需加载编码规范。 skills({ skillPaths: [SKILLS_DIR] }), // 模型瞬时错误自动重试。 retry(), ], store: new FileSessionStore(./.snapshots-coding), // toolApproval 需要 maxTurns: 30, });编写自定义中间件用generateMiddleware编写可复用、具名的中间件。它返回一个在use: [...]中调用的工厂与genkit-ai/middleware包内中间件的构建方式一致工厂可接收可选的 Zod 校验配置并拿到ai实例// timing.ts import { generateMiddleware, z } from genkit; const OptionsSchema z.object({ label: z.string().optional() }); export const timing generateMiddleware( { name: timing, description: Logs how long the model call takes., configSchema: OptionsSchema, }, ({ config, ai }) { // 每次 generate() 调用执行一次。返回下述任一 hook。 return { model: async (req, ctx, next) { const start Date.now(); const res await next(req, ctx); console.log([${config?.label ?? timing}] ${Date.now() - start}ms); return res; }, }; } );可用 hook 共四类generate(envelope, ctx, next)包装整个 generate actionenvelope 携带{ request, currentTurn, messageIndex }适合注入请求参数、后处理响应或捕获工具循环错误model(req, ctx, next)包装底层模型调用缓存、重试、请求/响应改写tool(req, ctx, next)包装单个工具调用校验输入、缓存或覆盖工具输出tools: ToolAction[]静态注入工具artifacts()/filesystem()即通过此方式加工具。钩子选择建议与完整签名见 Building custom middleware。关键警告不要依赖内部知识务必查文档Genkit 近期经历了一次重大破坏性 API 变更v1.x。训练知识很可能已过时必须查阅文档再动手genkit docs:read js/get-started.md genkit docs:read js/flows.md详见 Common Errors 中列出的已废弃 API 及其 v1.x 替代写法。始终通过 Genkit CLI 或仓库内参考文档核实信息。v1.x 与 pre-1.0 迁移对照速查项目正确v1.x错误pre-1.0包导入import { z, genkit } from genkit; 插件各自导入import { genkit } from genkit-ai/coreimport { defineFlow } from genkit-ai/flow模型引用googleAI.model(gemini-flash-latest)或带插件前缀字符串googleai/gemini-flash-latest直接使用导入的模型对象或不带插件前缀的裸字符串gemini-flash-latestGemini 模型选择使用gemini-flash-latest/gemini-pro-latest别名版本化旧模型gemini-1.5-flash、gemini-2.5-flash已废弃响应访问直接属性response.text、response.output方法调用response.text()、response.output()流式生成不 awaitgenerateStream直接迭代streamawait response取最终结果for await (const chunk of stream())await response()初始化const ai genkit({ plugins: [...] })全局配置configureGenkit(...)Flow 定义ai.defineFlow({...}, fn)挂在实例上从genkit-ai/flow全局导入defineFlow永远不要直接导入genkit-ai/flow、genkit-ai/ai或genkit-ai/core包。Zod 与 Schema 常见错误导入来源始终import { z } from genkit直接引zod包可能导致实例不匹配或兼容性问题支持类型坚持标量string/number/boolean、object、array等基础类型避免除非必要且已验证的复杂 Zod 特性描述字段输出 schema 的字段务必使用.describe(...)引导 LLM 正确填充。多模态与音频注意事项使用图像生成模型如gemini-2.5-flash-image时必须在 config 中指定responseModalities: [TEXT, IMAGE]否则会报错或输出格式不正确语音生成的返回内容可能是裸 PCM 数据如 Google GenAI而非 MP3/WAVOpenAI 返回 MP3。不要假设是 MP3不要直接把裸 PCM 塞进 HTML audio 标签先运行genkit docs:search speech audio查找提供商特定的转换步骤如 PCM 转 WAV。参考 Examples 中的 TTS 完整示例。错误排查协议不可协商遇到任何与 Genkit 相关的错误ValidationError、API 错误、类型错误、404 等时强制第一步阅读 Common Errors判断错误是否匹配已知模式应用文档中记录的解决方案仅当在 common-errors.md 中找不到时再查阅其他来源如genkit docs:search。禁止基于假设或内部知识尝试修复因为你觉得你知道答案而跳过阅读 common-errors.md依赖 pre-1.0 Genkit 的模式。此协议对错误处理不可协商。开发工作流Agent 场景推荐流程判断 Agent 还是 Flow任务是对话式、多轮的或被称为agent / assistant / chatbot时用ai.defineAgent见 Agents构建而不是在 flow 内手搓generate 工具循环只有单次、无状态的生成才用普通 flow。选择 ProviderGenkit 是 provider 无关的Google AI、OpenAI、Anthropic、Ollama 等。用户未指定时默认 Google AI询问其他 provider 时用genkit docs:search plugins查文档。识别框架检查package.json确定运行时Next.js、Firebase、Express。查找genkit-ai/next、genkit-ai/firebase或genkit-ai/google-cloud并按对应框架模式适配实现。遵循最佳实践项目结构上把 flows 和 tools 分目录存放如src/flows、src/tools用index.ts统一导出Google AI 场景始终使用最新别名gemini-flash-latest通用、gemini-pro-latest复杂任务敏感 key如GEMINI_API_KEY存入环境变量或.env绝不硬编码保持最小化只指定与默认值不同的选项不确定时查文档/源码。详见 Best Practices。确保正确性修改后运行类型检查如npx tsc --noEmit类型检查失败时先查 Common Errors 再搜源码用 Trace 验证而不是盲跑。直接运行应用node/tsx/npm start不会捕获开发 Trace必须用genkit start启动见下节。处理错误任何错误的第一步都是阅读 Common Errors匹配文档模式先应用文档修复再尝试其他方案。CLI 使用指南用 Trace 证明工具真的被调用查找文档的命令genkit docs:search query # 例genkit docs:search streaming genkit docs:list # 列出全部文档 genkit docs:read path # 例genkit docs:read js/flows.mdgenkit start无侵入式包装捕获一切 Tracegenkit start无侵入地包装任何使用 Genkit 库的 Node.js 程序程序原样运行同时捕获每个 Genkit action 的 Trace让你在终端里证明工具确实被调用、检查模型输入输出即使是无头检查也可以。它会转发 stdio因此依赖 stdin/stdout 的交互式 CLI 工具也能正常工作。直接运行应用node/tsx/npm start会跳过 Trace 捕获等于盲调。主要模式默认在正常运行命令前加genkit start --前缀genkit start -- npx tsx --watch src/index.ts genkit start --noui -- npx tsx src/index.ts # 不带 Dev UI仍是常驻服务genkit start会一直运行直到按 CtrlC。这对常见场景Web/移动应用调用的服务端、你自行退出的交互式 CLI是预期且正确的。--noui只去掉 Dev UI不是一次性命令不会自行退出。不要把genkit start当作自动化/非交互环境中的阻塞步骤。非交互使用Agent/CI在--前加全局--non-interactive标志让 CLI 使用默认值、绝不阻塞等待提示如首次运行的 analytics 通知genkit start --non-interactive -- npx tsx src/index.ts其他框架示例Next.js 用genkit start -- npx next dev。开发期推荐加 watcher 自动重载tsx --watch/node --watch。flow:run运行单个 Flow自动退出按名称从 CLI 调用指定 flow。在--后追加运行命令来为本次运行拉起运行时genkit flow:run myFlow {data: input} -- npx tsx src/index.ts这是自终止的运行一次 flow打印Trace ID后退出用genkit trace:get id检查。因此它是必须自行退出的快速非交互检查的正确选择不会像genkit start那样阻塞。始终显式传输入 JSON省略时flow:run会发送undefined不会回退到 schema 的.default()带默认值输入参数的 flow 会因此校验失败。注意flow:run运行的是flowai.defineFlow不能直接flow:run一个 agentai.defineAgent。要从 CLI 验证 Agent把一轮对话包进一个一次性 flow 再运行import { z } from genkit; import { weatherAgent } from ./weather-agent.js; import { ai } from ./genkit.js; export const tryWeatherAgent ai.defineFlow( { name: tryWeatherAgent, inputSchema: z.string(), outputSchema: z.string() }, async (message) (await weatherAgent.chat().send(message)).text ); // genkit flow:run tryWeatherAgent Weather in Tokyo? -- npx tsx src/index.tsTrace 调试最快看到提示词与模型 I/O 的方式在genkit start下运行任意程序后从终端检查 Tracegenkit trace:list # 查找最近的 Trace ID genkit trace:get traceId # 完整 Trace 详情输入、输出、工具调用、错误 genkit trace:get traceId --format json # 机器可读 JSON可直接管道给 jq 等解析器机器可读输出请加--format json默认输出面向人类横幅/日志行、大 Trace 可能截断不要直接管道用--format json、grep 或 Dev UI 的 Trace 查看器。genkit trace:get对调试失败的模型调用、检查工具执行、分析 flow 中某一步的确切输入输出尤其有用。更多命令见 CLI Reference完整命令列表用genkit --help。评测eval:flow与eval:rungenkit eval:flow flowName [data] -- run cmd运行 flow 并针对已配置的 evaluator 评估输出。单输入示例genkit eval:flow answerQuestion [{testCaseId: 1, input: {question: What is Genkit?}}] -- npx tsx src/index.ts批量输入用--input inputs.jsongenkit eval:run dataset对数据集运行已配置的 evaluator示例genkit eval:run dataset.json --output results.json。新项目落地从 Setup 到开发闭环仓库中的 Setup 指南 给出了完整的初始化步骤摘要如下检查代码库中是否已安装 provider 插件如genkit-ai/google-genai、genkit-ai/oai-compat、genkitx-*无偏好时默认genkit-ai/google-genaiNext.js 项目还需装genkit-ai/next在源码目录创建ai/genkit.ts只挂模型 provider 插件不要加 next 插件import { genkit, z } from genkit; // 在此导入所选 provider 插件。示例 import { googleAI } from genkit-ai/google-genai; export const ai genkit({ plugins: [ googleAI(), // 在此添加 provider 插件 ], model: googleAI.model(gemini-flash-latest), // 在此设置模型 }); export { z };创建ai/tools、ai/flows目录暂空以及ai/index.tsimport 各 flow/tool 供 Dev UI 使用将genkit-cli加入 devDependencies如npm install -D genkit-cli锁定版本并在 CI 中可用然后在package.json添加genkit:dev脚本genkit start -- npx tsx --watch {sourceDir}/ai/index.ts开发期运行npm run genkit:dev常驻、Dev UI 在 http://localhost:4000并设置环境变量Google provider 需GEMINI_API_KEY。总结Genkit JS 开发闭环围绕 Genkit JS 的核心心智模型可以浓缩为四点一切挂在ai实例上genkit()工厂返回的实例提供generate、defineFlow、definePrompt、defineTool、defineAgent、defineSchema、defineHelper等全部能力提示词与 Agent 配置即代码.prompt文件用 frontmatter 承载模型、schema、工具与中间件Agent 的复杂行为文件系统、技能、审批、重试通过use中间件数组以声明式方式叠加先查文档再动手v1.x 经历了破坏性 API 变更任何错误的第一步都是查阅 Common Errors日常开发用genkit docs:search/docs:read获取权威信息用 Trace 证明一切genkit start捕获每次模型 I/O 与工具调用flow:run提供可自动退出的非交互验证trace:get --format json让调试结果可管道、可机器解析。按此闭环开发你可以在保持代码最小化的同时获得完整的可观测性让每次模型调用、每个工具执行都有据可查。更深入的参考资料Agent 生态、中间件目录、CLI 全量命令、最小可复现示例、错误速查均可在本仓库 genkit-js 目录 下继续探索。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考