developing-genkit-dart

Genkit Dart

Genkit Dart は、コード生成、構造化出力、ツール、フロー、AI エージェントのための統一インターフェースを提供する、Dart 向け AI SDK です。

コア機能と使い方

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）を対象としています。古いコードや トレーニングデータでは、コンパイルできなくなった 1.0 より前の名称が使われています。よくある例は次のとおりです。

• HTTP：startFlowServer／ルートごとの shelfHandler／shelf_cors_headers は、 GenkitRouter と serve() または asShelfHandler()、および CorsOptions に変更されています。 コンテキストプロバイダーでは RequestData を使用します （genkit_shelf.md）。
• StatusCodes.UNAUTHENTICATED は StatusCode.unauthenticated です（EvalStatus.pass、ToolChoice.required も同様に lowerCamelCase です）。
• 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 フロントマターと Handlebars テンプレートによって、プロンプトの内容を Dart コードの外に保持できます。references/dotprompt.md を参照してください。 promptDir、ai.prompt()（呼び出し／ストリーミング／レンダリング）、バリアント、パーシャル、defineSchema による名前付きスキーマ、およびフロントマターの tools／maxTurns／returnToolRequests／use（ミドルウェア）フィールドについて説明しています。.prompt ファイルは、definePromptAgent` を使ってエージェントを直接構成することもできます。

エージェント

Genkit Dart には、永続的な複数ターンの会話（セッション、スナップショット、中断、分岐、バックグラウンド実行、カスタム状態、アーティファクト、複数エージェントへの委譲）に対応する エージェント API があります。エージェント／セッション／スナップショット API は 実験的 で、オプトイン形式のインポートを通じて利用できます。サーバー API は package:genkit/genkit.dart と併せて package:genkit/experimental.dart から、ブラウザー／HTTP クライアントは package:genkit/client.dart と併せて package:genkit/experimental_client.dart から、FileSessionStore などの dart:io 用追加機能は package:genkit/experimental_io.dart から利用できます。これらのエントリーポイントは @experimental であるため、インポートすると experimental_member_use アナライザー警告が発生します。この警告は analysis_options.yaml で抑制できます。remoteAgent クライアントは Flutter を含むあらゆる Dart アプリで動作し、バックエンドは完全に互換性があります。同じ HTTP プロトコルを使って、Dart、JS/TypeScript、または Go で実装された Genkit エージェントと通信できます。Dart 固有の点として、中断には ai.defineInterrupt(...) または .interrupt(...) を返すツールを使います（ctx.interrupt() はありません）。サブエージェントへの委譲には package:genkit_middleware の agents() ミドルウェアを使います。また、現時点では artifacts() ミドルウェアはありません（アーティファクト用ツールを直接定義してください）。

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

• エージェント：エージェントの定義と提供、クライアント管理の状態（まずはこちらから）。
• セッションと永続化：セッションストア（InMemorySessionStore／FileSessionStore／FirestoreSessionStore）。
• Human-in-the-loop／中断：.interrupt(...) による承認／入力待ちと再開。
• 分岐：スナップショットから会話を分岐。
• バックグラウンドエージェント：長時間のターンを切り離してポーリング。
• 状態の操作：クライアントと自動同期される、型付きのカスタムセッション状態。
• アーティファクト：名前付き成果物の生成と読み取り。
• 複数エージェントのオーケストレーション：agents() ミドルウェアを使ったサブエージェントへの委譲。
• 高度なカスタムエージェント：ターンを完全に制御する defineCustomAgent。
• エージェントのデプロイ：GenkitRouter.addAgent を使って HTTP 経由でエージェントを提供（複数エージェント、shelf、CORS）。

生成 UI（A2UI）

Genkit Dart には A2UI（Agent-to-UI）プラグイン（genkit_a2ui）があり、エージェントが文章だけでなく、インタラクティブな UI サーフェス（カード、リスト、フォーム、ボタン）をストリーミングできます。サーバー側の統合はすべて、エージェント（または 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 アクションのトレースを取得できるため、ツールが実際に呼び出されたことを確認し、ヘッドレスのチェックでもターミナルからモデルの入出力を調べられます。stdio を転送するので、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 -- を付けます。これにより、開発用 UI、自分の Web サーバー／Web UI、または単純なスクリプトのいずれから起動されたかにかかわらず、プログラムが実行するすべての Genkit コードからテレメトリーが収集されます。フローの実行、モデルとエージェントのプレイグラウンド、トレースの閲覧に使う Developer UI（通常は http://localhost:4000）も起動します。

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 は Dev UI を無効にするだけです。単発実行用のコマンドではなく、それだけで終了することはありません。自動化された環境や非対話型の環境で、ブロッキング処理として genkit start を使用しないでください。その場合は、以下の flow:run を使用してください。

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

これは実行後に終了します。フローを 1 回実行して Trace ID を出力し、その後終了するため、手早く非対話型のチェックを行う場合に適しています（genkit start とは異なります）。注：flow:run が実行するのはフロー（ai.defineFlow）であり、エージェントではありません。エージェント（ai.defineAgent）を直接 flow:run で実行することはできません。CLI からエージェントを試すには、1 ターンだけ実行する一時的なフローでラップして、そのフローを実行してください（エージェントを参照）。この実行のトレースは、以下のトレースコマンドで確認できます。

注意点：トップレベルの final 宣言は遅延評価されます。 トップレベルで定義されたフローとエージェントは、シンボルが初めて評価されたときにのみ Genkit に登録されます。空の main() では何も登録されないため、flow:run は Process exited before runtime was ready というエラーで失敗します。フロー／エージェントのシンボルを main() から参照するか、それらを参照するモジュールをインポートして、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、または Dev UI のトレースビューアーを使用してください。

ドキュメント：

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

プラグインのエコシステム

Genkit は、生成 AI アクションの実行、外部 LLM との連携、ウェブサーバーのホスティングに、多数のプラグインを利用します。

特定のプラグインを使うよう求められた場合は、必ず以下の対応するリファレンスを参照して、使い方を確認してください。プラグインの初期化引数、ツール、モデル、使用パターンを確認する必要があるときは、リファレンスを読み込んでください。

プラグイン名	リファレンスリンク	説明
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	特定のエージェント的な動作のためのツール（filesystem、skills、toolApproval 割り込み）を確認するために読み込みます。
genkit_mcp	references/genkit_mcp.md	Model Context Protocol との統合（Server、Host、Client の機能）を確認するために読み込みます。
genkit_chrome	references/genkit_chrome.md	Prompt API を使って Chrome ブラウザー内で Gemini Nano をローカル実行する方法を確認するために読み込みます。
genkit_shelf	references/genkit_shelf.md	HTTP 経由でフロー／モデル／エージェントを提供する方法を確認するために読み込みます。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 を使ってレンダリングします。

外部依存関係

ツール、フロー、プロンプト内でスキーマのマッピングを定義する場合は、必ず schemantic ライブラリを使用してください。 schemantic の使い方を学ぶには、型安全な生成 Dart コードの実装方法について、必ず references/schemantic.md を読んでください。これは、@Schema()、SchemanticType、または $ が接頭辞に付くクラスなどのシンボルが登場する場合に特に重要です。Genkit Dart はすべてのデータモデルに schemantic を使用するため、Genkit Dart を使ううえで理解しておくべき重要なスキルです。

ベストプラクティス

• エージェントとフローのどちらを使うべきですか？ タスクが会話形式、複数ターン、または「エージェント」「アシスタント」「チャットボット」と説明されている場合は、フロー内で generate とツールのループを独自に実装するのではなく、ai.defineAgent（Agents を参照）を使ってください。単発でステートレスな生成には、通常のフローを使用してください。
• 最終回答を生成する前に、dart analyze を使ってコードが問題なくコンパイルされることを必ず確認してください。
• ローカルでの開発とデバッグには、必ず Genkit CLI を使用してください。
• 実行するだけでなく、トレースで検証してください。アプリを直接実行（dart run）しても、開発トレースは記録されません。アプリの実行方法とトレースの記録方法については、Genkit CLI セクションを参照してください。