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 フロントマターと Handlebars テンプレートを使って、プロンプトの内容をコードの外に記述できます。Dotpromptでは、promptDir、ai.prompt()（call／stream／render）、バリアント、パーシャル、ai.defineSchema による名前付きスキーマ、さらに tools／maxTurns／returnToolRequests／use（ミドルウェア）のフロントマターフィールドについて説明しています。

エージェント（ベータ版）

Genkit には、永続的な複数ターンの会話（セッション、スナップショット、中断、分岐、バックグラウンド実行）に対応するプレビュー版のエージェント API があります。これはベータ版 API です。サーバー API は genkit/beta から、ブラウザクライアントは genkit/beta/client から利用できます。安定版の genkit エントリーポイントからは利用できません。genkit >= 1.39.0 が必要です。

詳しくは、以下をご覧ください。

• エージェント：エージェントの定義と提供、およびクライアント管理の状態（まずはこちらをご覧ください）。
• セッションと永続化：セッションストア（InMemory／File／Firestore）。
• Human-in-the-loop／中断：承認や入力のための一時停止と再開。
• 分岐：スナップショットから会話を分岐します。
• バックグラウンドエージェント：長時間実行されるターンの切り離し、待機、失敗または中断した実行の再開。
• 状態の操作：クライアントと自動同期される、型付きのカスタムセッション状態。
• アーティファクト：名前付き成果物の生成と読み取り。
• マルチエージェントオーケストレーション：バックグラウンド委任や continue_task を含む、サブエージェントへの委任。
• 高度なカスタムエージェント：ターンを完全に制御する defineCustomAgent。
• エージェントのデプロイ：HTTP 経由でのエージェントの提供（複数のエージェント、CORS、Web UI、その他のフレームワーク）。

生成 UI（A2UI）

Genkit には、エージェントが文章だけでなく、インタラクティブな UI サーフェス（カード、リスト、フォーム、ボタン）をストリーミングできる A2UI（Agent-to-UI）プラグイン（@genkit-ai/a2ui）があります。サーバー側の統合はすべて、エージェント（または ai.generate）の use 配列に指定する a2ui() モデルミドルウェアです。ブラウザでは、@a2ui/* レンダラーと @genkit-ai/a2ui/client のヘルパーを使ってサーフェスを描画します。これはベータ版エージェントクライアント（genkit/beta + genkit/beta/client）を基盤としています。

• A2UI：サーバーミドルウェア、オプション、クライアントでの描画、ユーザー操作／フォーム、カスタムカタログ、セキュリティ／信頼境界。

ミドルウェア

ミドルウェアは生成処理をラップし（再試行、フォールバック、追加ツール、リクエスト／レスポンスの変換）、ai.generate、プロンプト、エージェントの 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. エージェントかフローか？：タスクが会話形式、複数ターン、または「エージェント」「アシスタント」「チャットボット」と表現されている場合は、フロー内でgenerateとツールのループを独自に組み立てるのではなく、ai.defineAgentで構築します（エージェントを参照）。単発のステートレスな生成には、通常のフローを使用します。
2. プロバイダーを選択する：Genkitはプロバイダーを問いません（Google AI、OpenAI、Anthropic、Ollamaなど）。
   • ユーザーがプロバイダーを指定しない場合は、Google AIをデフォルトにします。
   • ユーザーが他のプロバイダーについて尋ねた場合は、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）を実行します。
   • 型チェックが失敗した場合は、ソースコードを検索する前によくあるエラーを確認します。
   • トレースを使って検証し、ただ実行するだけにしないでください。アプリを直接実行（node／tsx／npm start）しても、開発トレースは記録されません。アプリを実行してトレースを記録する方法については、CLIの使い方（推奨）を参照してください。
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 アクションのトレースを取得します。そのため、ヘッドレスチェックでも、ツールが実際に呼び出されたことを証明し、モデルの入出力をターミナルから確認できます。stdio を転送するため、stdin/stdout に依存する対話型 CLI ツールも問題なく動作します。アプリを直接実行（node／tsx／npm start）するとトレースが取得されず、手探りでデバッグすることになります。

基本パターン（デフォルト）： 通常の実行コマンドの前に genkit start -- を付けます。これにより、開発 UI、自前の Web サーバー／Web UI、または単純なスクリプトのいずれから起動された場合でも、プログラムが実行するすべての Genkit コードのテレメトリが収集されます。

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 は Dev UI を無効にするだけで、1 回限りのコマンドではなく、自動的に終了することもありません。自動化された環境や非対話型の環境では、ブロッキングステップとして genkit start を使用しないでください。

非対話型での使用（エージェント／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

これは実行後に自動終了します。フローを 1 回実行し、Trace ID を表示してから終了します（genkit trace:get <id> で確認できます）。そのため、genkit start のようにブロックしたり、トレースが取得されないアプリの直接実行をしたりせずに、自動終了が必要な、すばやく非対話型のチェックを行うのに適しています。入力 JSON は必ず明示的に指定してください。省略すると flow:run は undefined を送信し、スキーマの .default() にはフォールバックしません。注：flow:run が実行するのはフロー（ai.defineFlow）であり、エージェントではありません。エージェント（ai.defineAgent）を直接 flow:run することはできません。CLI からエージェントを実行するには、1 ターン分を一時的なフローでラップし、そのフローを実行してください（エージェントを参照）。

トレースを使ったデバッグ： プロンプト、モデルの入力／出力、ツールの呼び出し、レイテンシ、エラーを確認する最もすばやい方法です。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 のトレースビューアーを使用してください。

コマンドの詳細についてはCLI リファレンスを、一覧については genkit --help を参照してください。

参考資料

• ベストプラクティス：スキーマ定義、フロー設計、構造に関する推奨パターンです。
• Dotprompt：.prompt ファイルについて説明します。promptDir、ai.prompt()、バリアント、パーシャル、名前付きスキーマ、tools／maxTurns／returnToolRequests／use のフロントマターを扱います。
• ドキュメントと CLI リファレンス：ドキュメントの検索、CLI タスク、ワークフローについて説明します。
• よくあるエラー：重大な「落とし穴」、移行ガイド、トラブルシューティングについて説明します。
• セットアップガイド：新しいプロジェクト向けの手動セットアップ手順です。
• 例：最小限の再現可能な例（基本的な生成、マルチモーダル、思考モード）です。
• エージェント（ベータ）：エージェントの基礎、サービング、クライアントが管理する状態について説明します。詳しいトピック：セッション、ヒューマン・イン・ザ・ループ、分岐、バックグラウンドエージェント、状態、アーティファクト、マルチエージェント、カスタムエージェント、デプロイ。
• ミドルウェア：ミドルウェアと @genkit-ai/middleware パッケージの使い方について説明します。カスタムミドルウェアの構築も参照してください。
• 可観測性：@genkit-ai/otel（OpenTelemetry GenAI のセマンティック規約）、カスタムの Instrumentation、開発環境以外でのリフレクション API について説明します。
• A2UI（生成 UI）：@genkit-ai/a2ui プラグイン（a2ui() ミドルウェア）、オプション、クライアントでのレンダリング、ユーザーアクション／フォーム、カスタムカタログ、セキュリティについて説明します。