developing-genkit-go

Genkit Go

Genkit Go 是一款面向 Go 的 AI SDK，提供生成、结构化输出、流式处理、工具调用、提示词和流程，并通过统一接口支持不同模型提供商。

Hello World

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"

	"github.com/firebase/genkit/go/ai"
	"github.com/firebase/genkit/go/genkit"
	"github.com/firebase/genkit/go/plugins/googlegenai"
	"github.com/firebase/genkit/go/plugins/server"
)

func main() {
	ctx := context.Background()
	g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}))

	genkit.DefineFlow(g, "jokeFlow", func(ctx context.Context, topic string) (string, error) {
		return genkit.GenerateText(ctx, g,
			ai.WithModelName("googleai/gemini-flash-latest"),
			ai.WithPrompt("Tell me a joke about %s", topic),
		)
	})

	mux := http.NewServeMux()
	for _, f := range genkit.ListFlows(g) {
		mux.HandleFunc("POST /"+f.Name(), genkit.Handler(f))
	}
	log.Fatal(server.Start(ctx, "127.0.0.1:8080", mux))
}

核心功能

根据需求加载相应的参考文档：

功能	参考文档	适用场景
初始化	references/getting-started.md	设置 genkit.Init、插件，以及 *Genkit 实例模式
生成	references/generation.md	Generate、GenerateText、GenerateData、流式处理、输出格式
提示词	references/prompts.md	DefinePrompt、DefineDataPrompt、.prompt 文件、架构
工具	references/tools.md	DefineTool、DefineResumableTool 中断（Interrupted 声明、Restart/Respond、WithResume）、ai/tool 辅助函数（tool.Interrupt、tool.Fail、tool.AttachParts）
中间件	references/middleware.md	ai.Middleware、ai.WithUse、Hooks（Generate/Model/Tool）、内置功能（Retry、Fallback、ToolApproval、Filesystem、Skills、SoftToolErrors、ContextCompression、Budget）
可观测性	references/observability.md	OpenTelemetry 导出（otelgenai）、tracing.SetInstrumentation、aix.Observer、开发环境之外的反射 API
流程与 HTTP	references/flows-and-http.md	DefineFlow、DefineStreamingFlow、genkit.Handler、HTTP 服务
模型提供商	references/providers.md	Google AI、Vertex AI、Anthropic、兼容 OpenAI 的提供商、Ollama 设置

Agent（实验性）

Genkit Go 提供一个实验性 Agent API，用于持久化、多轮对话（会话、快照、中断、分支、后台执行）。 该功能受限制：使用 genkit.Init(ctx, genkit.WithExperimental()) 初始化，否则构造函数会触发 panic。服务端构造函数来自 genkit/exp（别名为 genkitx）；类型和选项来自 ai/exp（别名为 aix）；会话存储来自 ai/exp/localstore。

• Agent 还是流程？ 如果任务是对话式、多轮的，或被描述为“Agent”“助手”或“聊天机器人”，请使用 genkitx.DefineAgent 构建，而不要在流程中手动编写 Generate + 工具循环。只有在单次、无状态生成时才使用普通流程。

详情请参阅：

• Agent：定义/提供 Agent、运行轮次，以及客户端管理与服务端管理的状态（从这里开始）。
• 会话与持久化：会话存储（localstore.NewInMemorySessionStore/NewFileSessionStore、PostgreSQL）、快照，以及 sessionstoretest 一致性测试套件。
• 人在回路中 / 中断：暂停以等待批准/输入并恢复。
• 分支：从快照派生对话分支。
• 后台 Agent：将长时间运行的轮次分离到后台并轮询。
• 使用状态：类型化的自定义会话状态，以 JSON 补丁形式流式传输。
• 制品：生成和读取命名交付物。
• 多 Agent 编排：委派给子 Agent、后台委派、continue_task 和远程 Agent（DefineRemoteAgent）。
• 高级自定义 Agent：使用 DefineCustomAgent 完全控制轮次。
• 部署 Agent：使用 genkit.Handler 通过 HTTP 提供 Agent 服务。

生成式 UI（A2UI）

Genkit Go 提供一个 A2UI（Agent-to-UI）插件 （github.com/firebase/genkit/go/plugins/a2ui/exp，导入名为 a2uix）， 可让 Agent 流式传输交互式 UI 界面（卡片、列表、表单、按钮），而不仅仅是文字。完整集成方式是在生成调用或 Agent 内联提示词中，通过 ai.WithUse 添加 &a2uix.Surfaces{} 模型中间件。**Go 仅用于服务端：它没有 A2UI 客户端或渲染器。**请使用 JS 或 Dart/Flutter 客户端渲染界面，并通过 HTTP 与 Go Agent 通信（服务端和客户端在线路协议上兼容）。

• A2UI：服务端中间件、选项、自定义目录和安全性。客户端（渲染界面）相关内容，请参阅 Genkit JS 或 Dart 技能中的 A2UI 参考文档。

Genkit CLI（推荐）

genkit start 会以非侵入方式包装任何使用 Genkit 库的 Go 程序，在原样运行程序的同时，捕获每个 Genkit 操作的跟踪记录，让你能确认工具确实被调用，并在终端检查模型 I/O，即使是无头检查也可以。它会转发标准输入输出，因此依赖 stdin/stdout 的交互式 CLI 工具也能正常工作。直接运行应用（go run .）不会捕获跟踪记录，因此调试时无从得知情况。使用 genkit --version 检查是否已安装。

安装：

curl -sL cli.genkit.dev | bash

**主要用法（默认）：**在常规运行命令前加上 genkit start --。此命令会收集程序运行的所有 Genkit 代码产生的遥测数据，无论其由开发者 UI、你自己的 Web 服务器/Web UI 还是普通脚本触发。它会启动 Developer UI（通常位于 http://localhost:4000），用于运行流程、体验模型和 Agent Playground，以及浏览跟踪记录：

genkit start -- go run .
genkit start --noui -- go run .   # same, without the Dev UI (still a persistent server)
genkit start -o -- go run .       # also opens the browser

genkit start 会持续运行，直到你按 Ctrl+C 停止。这是常见场景下的预期行为，也是正确的做法：例如 Web/移动应用调用的服务器，或由你主动退出的交互式 CLI。--noui 只会关闭 Dev UI；它不是一次性命令，也不会自行退出。自动化/非交互环境中，不要将 genkit start 用作阻塞步骤；这类场景请使用 flow:run（见下文）。

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

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

genkit flow:run myFlow '{"data": "input"}' -- go run .
genkit flow:run myFlow '{"data": "input"}' --stream -- go run .   # with streaming
genkit flow:run myFlow '{"data": "input"}' --wait -- go run .     # wait for completion

此命令运行完成后会自行退出：它会运行一次流程，打印 Trace ID，然后退出，因此适合快速的非交互式检查（不同于 genkit start）。此次运行的跟踪记录可使用下方的跟踪命令检查。

**通过跟踪记录调试：**这是查看提示词、模型输入/输出、工具调用、延迟和错误最快的方法。使用 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 或 Dev UI 跟踪查看器。

文档：

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

完整的 CLI 和 Developer UI 详情，请参阅 references/getting-started.md。

关键指导

• 显式传入 g。 genkit.Init 返回的 *Genkit 实例是中央注册表。将其传递给所有 Genkit 函数，而不是将其存储为全局变量。这是贯穿整个 SDK 的核心模式。
• 将 AI 逻辑封装在流中。 流可提供追踪、可观测性、通过 genkit.Handler 进行 HTTP 部署的能力，以及从 Developer UI 和 CLI 进行测试的能力。任何值得保留的生成调用都应放在流中。
• 通过追踪验证，而不是盲目运行。 直接运行应用（go run .）不会捕获开发追踪。有关如何运行应用并捕获追踪，请参阅 Genkit CLI（推荐）部分。
• 在输出类型上使用 jsonschema:"description=..." 结构体标签。 模型会利用这些描述理解每个字段应包含什么内容。没有这些描述，结构化输出质量会显著下降。
• 编写优质的工具描述。 模型会根据描述字符串决定调用哪些工具。描述含糊会导致遗漏或错误的工具调用。
• 复杂提示词请使用 .prompt 文件。 这样可以将提示词内容与 Go 代码分开，支持 Handlebars 模板，并且无需重新编译即可进行迭代。代码定义的提示词更适合简单的单行场景。
• 中断场景请使用 DefineResumableTool。 使用工具的 Interrupted 方法接管暂停的调用，并通过 ai.WithResume 恢复。ai.InterruptWith、RestartWith/RespondWith 和 WithToolRestarts 已弃用；genkitx.DefineInterruptibleTool 和 ai/exp/tool 已在 v1.14.0 中移除。请参阅 references/tools.md。
• 优先考虑内置中间件，再编写自定义中间件。 Retry、Fallback、ToolApproval、Filesystem、Skills 和 SoftToolErrors 涵盖了常见的横切需求，并可通过 ai.WithUse 组合使用。请参阅 references/middleware.md。编写自定义中间件时，应在 New 捕获的闭包中分配每次调用的状态，并保护 WrapTool 会修改的所有内容，因为工具可能会并发运行。
• 查阅最新的模型 ID。 模型名称经常变更。请查看提供方文档获取当前模型 ID，而不要依赖硬编码的名称。请参阅 references/providers.md。