用 Genkit Go 构建 AI 应用时如何初始化、定义…

在 Go 中使用 Genkit 开发 AI 生成、工具调用、流式输出、Agent 与 A2UI 功能时的完整实践指南。

适用场景

解决思路

1. 用 genkit.Init(ctx, genkit.WithPlugins(...)) 初始化，并把返回的 *Genkit 实例显式传给所有 Genkit 函数，不要存为全局变量。
2. 把 AI 逻辑包进 flow：用 genkit.DefineFlow 定义，用 genkit.ListFlows 枚举，用 genkit.Handler 挂到 HTTP mux 上部署。
3. 用 genkit.GenerateText / Generate / GenerateData 做生成，通过 ai.WithModelName、ai.WithPrompt 等选项传参。
4. 按需加载对应参考文档：初始化、生成、提示词、工具、中间件、flows 与 HTTP、模型提供商。
5. 对话式、多轮、被描述为 agent/assistant/chatbot 的任务用实验性 agent API（genkitx.DefineAgent），单次无状态生成才用普通 flow。
6. 使用实验性 agent API 时用 genkit.Init(ctx, genkit.WithExperimental()) 开启，否则构造函数会 panic；服务端构造函数来自 genkit/exp（别名 genkitx），类型与选项来自 ai/exp（别名 aix），会话存储来自 ai/exp/localstore。
7. Agent 相关能力按主题查阅参考：定义与运行、会话与持久化、human-in-the-loop 中断、分支、后台 agent、状态、artifacts、多 agent 编排、自定义 agent、部署。
8. 需要流式交互 UI 时用 A2UI 插件（plugins/a2ui/exp，别名 a2uix），在 generate 调用或 agent 内联提示上通过 ai.WithUse 加 &a2uix.Surfaces{} 模型中间件；Go 仅服务端，客户端用 JS 或 Dart/Flutter 渲染。
9. 用 genkit start -- <run command> 包裹运行程序以捕获所有 Genkit action 的 trace，并启动 Developer UI（默认 http://localhost:4000）。
10. 在自动化/CI 中用 genkit start --non-interactive -- go run . 避免阻塞在提示上；不要把它当作阻塞步骤。
11. 用 genkit flow:run <flowName> '<json>' -- go run . 单次运行指定 flow，可加 --stream 或 --wait；它是自终止的，适合非交互检查。
12. 用 genkit trace:list 找 trace ID，用 genkit trace:get <traceId> 查看输入输出、工具调用、延迟与错误；机器可读时加 --format json 再管道给 jq。
13. 用 genkit docs:search、genkit docs:list、genkit docs:read # 查询文档。
14. 在输出类型的 struct tag 上写 jsonschema:"description=..."，帮助模型理解每个字段含义。
15. 为工具写清晰的 description，模型据此决定调用哪个工具。
16. 复杂提示词用 .prompt 文件（支持 Handlebars 模板、无需重新编译），简单单行提示词用代码定义。
17. 优先使用内置中间件 Retry、Fallback、ToolApproval、Filesystem、Skills，通过 ai.WithUse 组合；自定义中间件时在 New 的闭包里分配每次调用状态，并对 WrapTool 会修改的内容加并发保护。
18. 查阅提供商文档获取最新模型 ID，不要硬编码模型名。
19. 用 genkit --version 检查 CLI 是否安装，未安装时用 curl -sL cli.genkit.dev | bash 安装。

适用边界 · 注意事项

• 不要直接 go run . 运行程序，那样不会捕获 trace，等于盲调。
• 不要在自动化或非交互场景把 genkit start 当作阻塞步骤使用，应改用 flow:run。
• 不要依赖硬编码的模型名，模型 ID 变化频繁。
• 不要把 *Genkit 实例存为全局变量，应显式传参。