developing-genkit-dart

Genkit Dart

Genkit Dart 是一个面向 Dart 的 AI SDK，为代码生成、结构化输出、工具、工作流和 AI Agent 提供统一接口。

核心功能与用法

如果你需要了解如何初始化 Genkit（Genkit()）、生成内容（ai.generate）、配置工具（ai.defineTool）、定义工作流（ai.defineFlow）、生成嵌入（ai.embed）、进行流式处理，或调用远程工作流端点，请加载核心框架参考文档： references/genkit.md

1.0 与 pre-1.0 API 的区别

此技能面向 Genkit Dart 1.0（genkit: ^1.0.0）。旧代码和 训练数据使用的 pre-1.0 名称已无法编译；常见情况如下：

• HTTP：startFlowServer / 每条路由的 shelfHandler / shelf_cors_headers 现在替换为 GenkitRouter + serve() 或 asShelfHandler()，并使用 CorsOptions； 上下文提供程序接收 RequestData（genkit_shelf.md）。
• StatusCodes.UNAUTHENTICATED 改为 StatusCode.unauthenticated（lowerCamelCase， EvalStatus.pass、ToolChoice.required 也同理）。
• 没有 RetryPlugin；内置了 retry()，并接收 Duration（initialDelay、maxDelay，其他位置也有 cacheTtl）。
• 重命名：GenerateResponseHelper -> GenerateResult（modelResponse、 chunk.modelChunk），ExecutablePrompt -> Prompt<Input, Output>， embedMany -> embed，ToolFnArgs -> ToolFnArg，toolOutputSchema -> outputSchema，underlyingException -> cause，modelInfo: -> info:， RemoteAction.dispose() -> close()，prompt(input, PromptGenerateOptions(config: ...)) -> prompt(input, config: ...)（命名选项，与 generate 一样），defineMiddleware -> ai.defineGenerateMiddleware（应用）/ generateMiddleware（插件）。
• 提供方配置类型带有前缀：GeminiThinkingConfig、 GeminiSafetySettings、GeminiGoogleSearch、GeminiSpeechConfig、 GoogleGenAiEmbedderOptions、AnthropicThinkingConfig。
• 已移除：ToolInterruptException / ctx.interrupt()（返回 .interrupt(...)）、 GoogleAiModels / OpenAIModels 常量（改用 googleAI.gemini('...')、 openAI.model('...')）。通过 simulateConstrainedGeneration() 可选择启用模拟受限输出。
• .prompt Picoschema 符合规范：name: type, description，绝不能使用 name(description): type（dotprompt.md）。

提示词（Dotprompt）

.prompt 文件通过 YAML frontmatter 和 Handlebars 模板，将提示词内容从 Dart 代码中分离出来。请参阅 references/dotprompt.md：promptDir、ai.prompt()（调用/流式处理/渲染）、变体、局部模板、通过 defineSchema 定义的命名架构，以及 tools/maxTurns/returnToolRequests/use （中间件）这些 frontmatter 字段。.prompt 文件也可以通过 definePromptAgent 直接用于 Agent。

Agent

Genkit Dart 提供了用于持久化多轮对话的 Agent API（会话、快照、中断、分支、后台执行、自定义状态、工件和多 Agent 委派）。Agent／会话／快照 API 尚处于实验阶段，需通过选择性导入启用：服务端 API 来自 package:genkit/experimental.dart（与 package:genkit/genkit.dart 一起导入）；浏览器／HTTP 客户端来自 package:genkit/experimental_client.dart（与 package:genkit/client.dart 一起导入）；FileSessionStore 等 dart:io 扩展来自 package:genkit/experimental_io.dart。这些入口标记为 @experimental，导入后会触发 experimental_member_use 分析器警告，可在 analysis_options.yaml 中将其关闭。remoteAgent 客户端可在任何 Dart 应用中使用，包括 Flutter；后端完全可互换，能够通过同一 HTTP 协议与使用 Dart、JS/TypeScript 或 Go 实现的 Genkit Agent 通信。Dart 的一些特性：中断通过 ai.defineInterrupt(...) 或返回 .interrupt(...) 的工具实现（没有 ctx.interrupt()）；子 Agent 委派使用 package:genkit_middleware 中的 agents() 中间件；目前还没有 artifacts() 中间件（请直接定义工件工具）。

更多详情请参阅：

• Agent：定义／提供 Agent，以及由客户端管理的状态（从这里开始）。
• 会话与持久化：会话存储（InMemorySessionStore／FileSessionStore／FirestoreSessionStore）。
• 人在回路中／中断：通过 .interrupt(...) 暂停以等待批准／输入，并恢复执行。
• 分支：从快照分叉对话。
• 后台 Agent：分离长时间运行的轮次并轮询状态。
• 使用状态：带类型的自定义会话状态，并自动同步到客户端。
• 工件：生成和读取带名称的交付物。
• 多 Agent 编排：使用 agents() 中间件委派给子 Agent。
• 高级自定义 Agent：使用 defineCustomAgent 完全控制轮次。
• 部署 Agent：通过 HTTP 提供 Agent，使用 GenkitRouter.addAgent（多个 Agent、shelf、CORS）。

生成式 UI（A2UI）

Genkit Dart 提供了 A2UI（Agent-to-UI）插件（genkit_a2ui），可让 Agent 流式传输交互式 UI 界面（卡片、列表、表单、按钮），而不只是文本。服务端集成全部通过 Agent（或 ai.generate）的 use 列表中的 a2ui() 模型中间件实现；Flutter 客户端使用 genui 包以及 package:genkit_a2ui/client.dart 中的辅助工具来渲染界面。Dart 特有要求：必须在 Genkit(plugins: [...]) 中注册 A2uiPlugin()（与 JS 不同，中间件会按名称从注册表中解析）。

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

Genkit CLI（推荐）

genkit start 会以非侵入式方式包装任何使用 Genkit 库的 Dart 程序，在不修改程序的情况下运行它，同时捕获每个 Genkit 操作的跟踪信息，让你能够证明工具确实被调用，并在终端中检查模型输入/输出，即使是在无头检查中也可以。它会转发标准输入输出，因此依赖 stdin/stdout 的交互式 CLI 工具也能正常工作。直接运行应用（dart run）会跳过跟踪信息捕获，让你只能盲目调试。使用 genkit --version 检查是否已安装。

安装：

curl -sL cli.genkit.dev | bash # Native CLI
# OR
npm install -g genkit-cli # Via npm
# OR run commands directly with npx without a global install (prefix every genkit command):
# npx genkit-cli start -- dart run main.dart

主要用法（默认）： 在常用运行命令前加上 genkit start --。无论程序中的 Genkit 代码是由开发者 UI、你自己的 Web 服务/Web UI 还是普通脚本触发，这都会收集遥测数据。它会启动开发者 UI（通常为 http://localhost:4000），供你运行流程、使用模型和 Agent Playground，以及浏览跟踪信息：

genkit start -- dart run main.dart
genkit start --noui -- dart run main.dart   # same, without the Dev UI (still a persistent server)

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

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

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

genkit flow:run myFlow '{"data": "input"}' -- dart run main.dart

该命令会自行终止：它运行一次流程，打印 Trace ID，然后退出，因此适合快速、非交互式检查（与 genkit start 不同）。注意：flow:run 运行的是流程（ai.defineFlow），而不是 Agent；你不能直接对 Agent（ai.defineAgent）使用 flow:run。如需从 CLI 调用 Agent，可将一轮交互封装到临时流程中并运行该流程（参见 Agent）。本次运行的跟踪信息可通过下方的跟踪命令进行检查。

注意：顶层 final 声明采用惰性求值。 定义为顶层 final 的流程和 Agent，只有在首次求值对应符号时才会向 Genkit 注册。空的 main() 不会注册任何内容，因此 flow:run 会报错 Process exited before runtime was ready。请在 main() 中引用流程/Agent 符号（或导入会引用它们的模块），确保其 define* 调用确实执行。

使用跟踪信息调试： 查看提示词、模型输入/输出、工具调用、延迟和错误的最快方式。在 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 跟踪查看器。

文档：

genkit docs:search "streaming" dart
genkit docs:list dart
genkit docs:read dart/flows.md

插件生态系统

Genkit 依赖一套丰富的插件来执行生成式 AI 操作、连接外部大模型，或托管 Web 服务。

当被要求使用任何给定插件时，请务必参考下方对应的参考文档来确认用法。需要了解插件的具体初始化参数、工具、模型和使用模式时，应加载相应的参考文档：

插件名称	参考链接	描述
genkit_google_genai	references/genkit_google_genai.md	加载此文档以了解 Google Gemini 插件接口的用法。
genkit_vertexai	references/genkit_vertexai.md	加载此文档以了解通过 Vertex AI 使用 Gemini（Google Cloud 身份验证、带版本的模型 ID、多模态嵌入）。
genkit_anthropic	references/genkit_anthropic.md	加载此文档以了解用于 Claude 模型的 Anthropic 插件接口。
genkit_openai	references/genkit_openai.md	加载此文档以了解用于 GPT 模型、Groq 和自定义兼容端点的 OpenAI 插件接口。
genkit_middleware	references/genkit_middleware.md	加载此文档以了解特定 Agent 行为的工具：filesystem、skills 和 toolApproval 中断。
genkit_mcp	references/genkit_mcp.md	加载此文档以了解模型上下文协议集成（服务端、Host 和客户端功能）。
genkit_chrome	references/genkit_chrome.md	加载此文档以了解如何使用 Prompt API 在 Chrome 浏览器中本地运行 Gemini Nano。
genkit_shelf	references/genkit_shelf.md	加载此文档以了解如何通过 HTTP 提供 flows/models/agents：GenkitRouter（核心 package:genkit/io.dart、独立的 dart:io），以及如何将其挂载到 Shelf 应用中。
genkit_firebase_ai	references/genkit_firebase_ai.md	加载此文档以了解 Firebase AI 插件接口（通过 Vertex AI 使用 Gemini API）。
genkit_a2ui	references/a2ui.md	加载此文档以了解 A2UI（Agent-to-UI）：通过 a2ui() 中间件流式传输生成式 UI 界面，并在客户端使用 genui 渲染。

外部依赖项

在 Tools、Flows 和 Prompts 中定义映射架构时，必须使用 schemantic 库。 要了解如何使用 schemantic，请务必阅读 references/schemantic.md，了解如何实现类型安全的生成式 Dart 代码。当遇到 @Schema()、SchemanticType 等符号或带 $ 前缀的类时，这一点尤其重要。Genkit Dart 的所有数据模型都使用 schemantic，因此要使用 Genkit Dart，理解它是一项至关重要的技能。

最佳实践

• Agent 还是 flow？ 如果任务具有对话性质、需要多轮交互，或被描述为“Agent”“助手”或“聊天机器人”，请使用 ai.defineAgent 构建（参见 Agents），而不是在 flow 中手动编写 generate + 工具循环。只有在单次、无状态生成时，才使用普通 flow。
• 生成最终响应前，务必使用 dart analyze 确认代码可以顺利编译。
• 本地开发和调试时，务必使用 Genkit CLI。
• 使用跟踪记录进行验证，而不是盲目运行。直接运行应用（dart run）不会捕获开发跟踪记录。有关如何运行应用并捕获跟踪记录，请参见 Genkit CLI（推荐）部分。