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 を設定するとき

エージェント（実験的）

Genkit Go には、永続的な複数ターンの会話（セッション、スナップショット、割り込み、分岐、バックグラウンド実行）に対応する実験的なエージェント API があります。この機能はゲート付きです。genkit.Init(ctx, genkit.WithExperimental()) で初期化しない場合、コンストラクターはパニックを起こします。サーバーのコンストラクターは genkit/exp（genkitx としてエイリアス）から、型とオプションは ai/exp（aix としてエイリアス）から、セッションストアは ai/exp/localstore から取得します。

• エージェントかフローか？ タスクが会話形式、複数ターン、または「エージェント」「アシスタント」「チャットボット」として説明される場合は、フロー内で Generate とツールのループを独自に組み立てるのではなく、genkitx.DefineAgent を使って構築してください。単発のステートレスな生成には、通常のフローを使用してください。

詳しくは、以下を参照してください。

• エージェント：エージェントの定義と提供、ターンの実行、クライアント管理とサーバー管理の状態（ここから始めてください）。
• セッションと永続化：セッションストア（localstore.NewInMemorySessionStore／NewFileSessionStore、PostgreSQL）、スナップショット、sessionstoretest 適合性テストスイート。
• 人間参加型ワークフロー／割り込み：承認や入力のために一時停止し、再開する方法。
• 分岐：スナップショットから会話をフォークする方法。
• バックグラウンドエージェント：長時間実行されるターンを切り離して、ポーリングする方法。
• 状態の操作：JSON パッチとしてストリーミングされる、型付きのカスタムセッション状態。
• 成果物：名前付きの成果物を生成して読み取る方法。
• マルチエージェントオーケストレーション：サブエージェントへの委任、バックグラウンドでの委任、continue_task、リモートエージェント（DefineRemoteAgent）。
• 高度なカスタムエージェント：ターンを完全に制御する DefineCustomAgent。
• エージェントのデプロイ：genkit.Handler を使用して HTTP 経由でエージェントを提供する方法。

生成 UI（A2UI）

Genkit Go には A2UI（Agent-to-UI）プラグイン （github.com/firebase/genkit/go/plugins/a2ui/exp。a2uix としてインポート）があり、 エージェントは文章だけでなく、インタラクティブな UI サーフェス（カード、リスト、フォーム、ボタン）をストリーミングできます。統合全体は、生成呼び出しまたはエージェントのインラインプロンプトで ai.WithUse を介して追加する、&a2uix.Surfaces{} モデルミドルウェアです。Go はサーバー専用です。A2UI クライアント／レンダラーはありません。 サーフェスは、HTTP 経由で Go エージェントと通信する JS または Dart/Flutter クライアントでレンダリングします（サーバーとクライアントはワイヤー互換です）。

• A2UI：サーバーミドルウェア、オプション、カスタムカタログ、セキュリティについて説明します。クライアント（サーフェスのレンダリング）については、Genkit JS または Dart のスキルにある A2UI リファレンスを参照してください。

Genkit CLI（推奨）

genkit start は、Genkit ライブラリを使用する任意の Go プログラムを目立たない形でラップし、プログラムを変更せずに実行しながら、すべての Genkit アクションのトレースを取得します。これにより、ツールが実際に呼び出されたことを確認し、ヘッドレスチェックでもターミナルからモデルの入出力を調べられます。標準入出力を転送するため、標準入力／標準出力に依存するインタラクティブな CLI ツールも問題なく動作します。アプリを直接実行（go run .）するとトレースを取得できず、デバッグ時に状況を把握できません。genkit --version でインストールを確認してください。

インストール：

curl -sL cli.genkit.dev | bash

主なパターン（デフォルト）： 通常の実行コマンドの前に genkit start -- を付けます。これにより、開発 UI、自分のウェブサーバー／ウェブ UI、単純なスクリプトのいずれから起動された場合でも、プログラムが実行する Genkit コードのテレメトリが収集されます。フローの実行、モデルとエージェントのプレイグラウンド、トレースの閲覧に使用する Developer UI（通常は http://localhost:4000）も起動します：

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 で停止するまで実行されます。ウェブ／モバイルアプリから呼び出されるサーバーや、自分で終了するインタラクティブな CLI など、一般的なケースではこれが想定どおりの動作です。--noui は Dev UI を無効にするだけです。単発実行のコマンドではなく、自動的に終了することもありません。 自動化された環境や非インタラクティブな環境では、ブロッキング処理として genkit start を使用しないでください。その場合は flow:run（以下を参照）を使用してください。

非インタラクティブな使用（エージェント／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 テンプレートをサポートし、再コンパイルせずに反復改善できます。単純な 1 行のケースには、コードで定義するプロンプトが適しています。
• 割り込みには 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を参照してください。