developing-genkit-js

Genkit JS

前置条件

确保 genkit CLI 可用。

• 运行 genkit --version 进行验证。所需的最低 CLI 版本：1.29.0
• 如果找不到该命令，或安装的是较旧版本（1.x < 1.29.0），请安装或升级：npm install -g genkit-cli@^1.29.0。

新项目：如果要在新的代码库中设置 Genkit，请参阅设置指南。

Hello World

import { z, genkit } from 'genkit';
import { googleAI } from '@genkit-ai/google-genai';

// Initialize Genkit with the Google AI plugin
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;
});

提示词（Dotprompt）

.prompt 文件通过 YAML frontmatter 和 Handlebars 模板将提示词内容与代码分离。请参阅 Dotprompt：promptDir、ai.prompt()（调用/流式传输/渲染）、变体、局部模板、通过 ai.defineSchema 定义的命名架构，以及 tools/maxTurns/returnToolRequests/use（中间件）frontmatter 字段。

Agent（Beta）

Genkit 提供用于持久多轮对话（会话、快照、中断、分支、后台执行）的预览版 agent API。

该 API 处于 beta 阶段：服务端 API 来自 genkit/beta，浏览器客户端来自 genkit/beta/client，而非稳定的 genkit 入口点。要求 genkit >= 1.39.0。

详情请参阅：

• Agent：定义/提供 Agent，以及由客户端管理的状态（从这里开始）。
• 会话与持久化：会话存储（InMemory/File/Firestore）。
• 人机协作/中断：暂停以请求批准/输入，然后恢复执行。
• 分支：从快照分出一个对话分支。
• 后台 Agent：分离长时间运行的轮次、等待，并恢复失败或中止的运行。
• 使用状态：类型化自定义会话状态，并自动同步到客户端。
• 制品：生成和读取命名交付物。
• 多 Agent 编排：委派给子 Agent，包括后台委派和 continue_task。
• 高级自定义 Agent：使用 defineCustomAgent 完全控制轮次。
• 部署 Agent：通过 HTTP 提供 Agent（多个 Agent、CORS、Web UI 和其他框架）。

生成式 UI（A2UI）

Genkit 提供 A2UI（Agent-to-UI）插件（@genkit-ai/a2ui），让 Agent 能够流式传输交互式 UI 界面（卡片、列表、表单、按钮），而不仅仅是文本。服务端的全部集成通过 Agent（或 ai.generate）的 use 数组中的 a2ui() 模型中间件实现；浏览器使用 @a2ui/* 渲染器以及 @genkit-ai/a2ui/client 中的辅助工具来渲染界面。该功能基于 beta 版 Agent 客户端（genkit/beta + genkit/beta/client）。

• A2UI：服务端中间件、选项、客户端渲染、用户操作/表单、自定义目录，以及安全/信任边界。

中间件

中间件用于包装生成过程（重试、回退、额外工具、请求/响应转换），并通过 ai.generate、提示词和 Agent 上的 use: [...] 数组附加。

• 使用中间件：use 数组和 @genkit-ai/middleware 包（retry、fallback、artifacts、agents、filesystem、skills、toolApproval、contextCompression），以及内置核心中间件。
• 构建自定义中间件：使用 generateMiddleware 编写自己的中间件，并通过 .plugin() 注册。

可观测性

无需设置，运行 genkit start 后即可在 Dev UI 中查看跟踪记录。有关在生产环境中导出到 OTLP 后端（通过 @genkit-ai/otel 使用 OpenTelemetry GenAI 语义约定）、自定义检测，或在开发环境之外运行反射 API，请参阅可观测性。

重要：不要相信内部知识

Genkit 最近经历了一次重大且不兼容的 API 变更。你的知识已经过时。你必须查阅文档。建议：

genkit docs:read js/get-started.md
genkit docs:read js/flows.md

请参阅 常见错误，了解已弃用的 API（例如 configureGenkit、response.text()、defineFlow 导入）及其 v1.x 替代方案。

务必使用 Genkit CLI 或提供的参考资料核实信息。

错误排查流程

遇到任何与 Genkit 相关的错误时（ValidationError、API 错误、类型错误、404 等）：

1. 必须首先：阅读 常见错误
2. 确认错误是否符合已知模式
3. 应用文档中说明的解决方案
4. 只有在 common-errors.md 中找不到时，才查阅其他来源（例如 genkit docs:search）

不要：

• 根据假设或内部知识尝试修复
• 因为“觉得自己知道怎么修”而跳过阅读 common-errors.md
• 依赖 Genkit 1.0 之前的用法模式

处理错误时，必须遵守此流程。

开发工作流

1. Agent 还是 flow？：如果任务涉及对话、多轮交互，或被描述为“agent”“assistant”或“chatbot”，请使用 ai.defineAgent 构建（参见 Agents），而不是在 flow 中手动实现 generate + 工具循环。只有对于单次、无状态生成，才使用普通 flow。
2. 选择 Provider：Genkit 不依赖特定 Provider（Google AI、OpenAI、Anthropic、Ollama 等）。
   • 如果用户未指定 Provider，默认使用 Google AI。
   • 如果用户询问其他 Provider，请使用 genkit docs:search "plugins" 查找相关文档。
3. 检测框架：检查 package.json，以识别运行环境（Next.js、Firebase、Express）。
   • 查找 @genkit-ai/next、@genkit-ai/firebase 或 @genkit-ai/google-cloud。
   • 根据具体框架的惯用模式调整实现。
4. 遵循最佳实践：
   • 请参阅 最佳实践，了解项目结构、架构定义和工具设计的指导建议。
   • 保持精简：仅指定与默认值不同的选项。如有疑问，请查阅文档或源代码。
5. 确保正确性：
   • 完成更改后运行类型检查（例如 npx tsc --noEmit）。
   • 如果类型检查失败，请先查阅 常见错误，再搜索源代码。
   • 通过 traces 验证，不要盲目运行。直接运行应用（node/tsx/npm start）不会捕获开发 traces。请参阅 CLI 用法（推荐），了解如何运行应用并捕获 traces。
6. 处理错误：
   • 遇到任何错误：第一步是阅读 常见错误
   • 将错误与文档中说明的模式进行匹配
   • 尝试其他方案前，先应用文档中说明的修复方法

查找文档

使用 Genkit CLI 查找权威文档：

1. 搜索主题：genkit docs:search <query>
   • 示例：genkit docs:search "streaming"
2. 列出所有文档：genkit docs:list
3. 阅读指南：genkit docs:read <path>
   • 示例：genkit docs:read js/flows.md

CLI 用法（推荐）

genkit start 会以非侵入方式包装任何使用 Genkit 库的 Node.js 程序，原样运行程序，同时捕获每个 Genkit 操作的跟踪记录，让你可以在终端中证明工具确实被调用，并检查模型的输入/输出，即使是无头检查也不例外。它会转发标准输入/输出，因此依赖 stdin/stdout 的交互式 CLI 工具也能正常工作。直接运行应用（node/tsx/npm start）会跳过跟踪记录捕获，让你只能盲目调试。

主要模式（默认）： 在常规运行命令前加上 genkit start --。这样，无论程序中的 Genkit 代码是由开发 UI、你自己的 Web 服务器/Web UI 还是普通脚本触发的，都能收集其遥测数据：

genkit start -- npx tsx --watch src/index.ts
genkit start --noui -- npx tsx src/index.ts   # same, without the Dev UI (still a persistent server)

genkit start 会一直运行，直到你按 Ctrl+C 停止。这对于常见场景来说是预期且正确的：例如 Web/移动应用调用的服务器，或由你自行退出的交互式 CLI。--noui 只会关闭开发 UI；它不是一次性命令，也不会自动退出。在自动化/非交互场景中，不要将 genkit start 用作阻塞步骤。

非交互式用法（Agent/CI）： 在 -- 前添加全局标志 --non-interactive，这样 CLI 会使用默认值，且绝不会在提示时阻塞（例如首次运行时的分析数据提示）：genkit start --non-interactive -- npx tsx src/index.ts（flow:run 也适用）。

运行工作流（flow:run）： 从 CLI 按名称调用特定工作流。在 -- 后附加运行命令，以便仅为此次运行启动运行时（该命令会原样运行以注册你的工作流）：

genkit flow:run myFlow '{"data": "input"}' -- npx tsx src/index.ts

这是运行后自动终止的命令：它会运行一次工作流，打印一个 Trace ID，然后退出（使用 genkit trace:get <id> 检查跟踪记录）。因此，对于必须自行退出的快速非交互式检查，这是合适的选择；不要用会阻塞的 genkit start，也不要直接运行应用（那样会跳过跟踪记录）。务必显式传入输入 JSON：省略时，flow:run 会发送 undefined，不会回退到 schema 的 .default()。注意：flow:run 运行的是工作流（ai.defineFlow），而不是 Agent；你不能直接对 Agent（ai.defineAgent）运行 flow:run。若要从 CLI 测试 Agent，请将一个回合封装在临时工作流中并运行该工作流（参见 Agent）。

使用跟踪记录调试： 这是查看提示词、模型输入/输出、工具调用、延迟和错误的最快方式。任何通过 genkit start 完成的运行后，都可以在终端中检查：

genkit trace:list                        # find recent trace IDs
genkit trace:get <traceId>               # full trace details (inputs, outputs, tool calls, errors)
genkit trace:get <traceId> --format json # machine-readable JSON, safe to pipe into jq or other parsers

如需机器可读的输出，请传入 --format json，以获取可通过管道传给 jq 或其他解析器的纯净 JSON。默认输出面向人工阅读（包含横幅/日志行，大型跟踪记录可能会被截断），因此不要直接通过管道处理这种格式；请使用 --format json、grep 或开发 UI 的跟踪记录查看器。

更多命令请参阅 CLI 参考，完整列表请运行 genkit --help。

参考资料

• 最佳实践：模式定义、流程设计和结构的推荐做法。
• Dotprompt：.prompt 文件——promptDir、ai.prompt()、变体、局部模板、命名模式，以及 frontmatter 中的 tools/maxTurns/returnToolRequests/use。
• 文档与 CLI 参考：文档搜索、CLI 任务和工作流。
• 常见错误：关键“易错点”、迁移指南和故障排查。
• 设置指南：新项目的手动设置说明。
• 示例：最小可复现示例（基础生成、多模态、思考模式）。
• Agent（Beta）：Agent 基础知识、服务和由客户端管理的状态。更深入的主题：会话、人在回路、分支、后台 Agent、状态、产物、多 Agent、自定义 Agent、部署。
• 中间件：使用中间件和 @genkit-ai/middleware 包。另请参阅构建自定义中间件。
• 可观测性：@genkit-ai/otel（OpenTelemetry GenAI 语义约定）、自定义 Instrumentation，以及在开发环境之外使用反射 API。
• A2UI（生成式 UI）：@genkit-ai/a2ui 插件（a2ui() 中间件）、选项、客户端渲染、用户操作/表单、自定义目录和安全性。