developing-genkit-python

Genkit Python

1 つの SDK で、AI 機能を Python で構築できます。生成、ストリーミング、ツール、フロー、複数ターンのエージェントに対応しています。

前提条件

• Python 3.10+ と uv（インストール）
• Genkit CLI：genkit --version が見つからない場合は、npm install -g genkit-cli

新しいアプリを作成しますか？セットアップ。パターンを確認しますか？例。

Hello World

from genkit import Genkit
from genkit_google_genai import GoogleAI

ai = Genkit(
    plugins=[GoogleAI()],
    model='googleai/gemini-flash-latest',
)

async def main():
    response = await ai.generate(prompt='Tell me a joke about Python.')
    print(response.text)

if __name__ == '__main__':
    ai.run_main(main())

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

履歴、型付き状態、人間による承認、分岐、バックグラウンド処理に対応した複数ターンのチャットです。こちらから始めてください：エージェント。

chat = agent.chat()
res = await chat.send('Hello')           # AgentResponse
turn = chat.send_stream('Hello')         # AgentTurn — .stream / .response

詳細：セッション · 人間参加型（HITL） · 分岐 · バックグラウンド処理 · 状態 · アーティファクト · カスタム · HTTP

インポート

• Google AI：from genkit_google_genai import GoogleAI
• エージェント：from genkit.agent import InMemorySessionStore, ...
• ミドルウェア：from genkit_middleware import Middleware, ToolApproval, ...
• FastAPI：from genkit_fastapi import serve_agent, serve_flow
• 評価：from genkit_evaluators import register_genkit_evaluators

ワークフロー

1. エージェントとフローのどちらを使いますか？ タスクが会話型、複数ターン、または「エージェント」「アシスタント」「チャットボット」と説明されている場合は、フロー内で generate とツールのループを自作するのではなく、ai.define_agent で構築します（エージェントを参照）。単発でステートレスな生成の場合にのみ、通常のフローを使用します。
2. GEMINI_API_KEY を設定します。プレフィックス付きのモデル ID（googleai/gemini-flash-latest）を使用します。
3. Genkit アプリでは ai.run_main(main()) から実行します（特に genkit start の場合）。よくあるエラーを参照してください。
4. 開発ワークフロー（genkit start + Dev UI）で実行します。
5. トレースで確認し、何も確認せずに実行するのは避けてください。アプリを直接実行（uv run）しても、開発トレースは記録されません。アプリの実行方法とトレースの記録方法については、Genkit CLIを参照してください。
6. 困った場合は、まずよくあるエラーを確認してください。

Genkit CLI（推奨）

genkit start は、Genkit ライブラリを使用するあらゆる Python プログラムを透過的にラップし、プログラムを変更せずに実行しながら、すべての Genkit アクションのトレースを収集します。これにより、ツールが実際に呼び出されたことを確認し、ヘッドレスなチェックでもターミナルからモデルの入出力を調べられます。stdio を転送するため、stdin/stdout に依存する対話型 CLI ツールも問題なく動作します。アプリを直接実行（uv run）するとトレースは収集されず、手探りでデバッグすることになります。

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

genkit start -- uv run src/main.py
genkit start --noui -- uv run src/main.py   # same, without the Dev UI (still a persistent server)

genkit start は Ctrl+C で停止するまで実行されます。これは一般的な用途、つまりウェブアプリやモバイルアプリから呼び出されるサーバーや、自分で終了する対話型 CLI では想定どおりの動作です。--noui は Dev UI を無効にするだけであり、一度だけ実行するコマンドではありません。自動化された環境や非対話型の環境で、ブロッキング処理として genkit start を使用しないでください。その場合は flow:run（以下を参照）を使用します。

非対話型での使用（エージェント／CI）： -- の前にグローバルフラグ --non-interactive を追加すると、CLI はデフォルトを使用し、プロンプト（初回起動時のアナリティクスに関する通知など）で処理を止めなくなります。例：genkit start --non-interactive -- uv run src/main.py（flow:run でも使用できます）。

フローの実行（flow:run）： CLI から名前を指定して特定のフローを呼び出します。-- の後に実行コマンドを追加すると、この実行のためだけにランタイムが起動します（フローを登録するため、コマンドはそのまま実行されます）。

genkit flow:run myFlow '{"data": "input"}' -- uv run src/main.py

これは実行後に自動終了します。フローを一度実行し、Trace ID を出力してから終了するため、手早く非対話型で確認する場合に適しています（genkit start とは異なります）。注：flow:run が実行するのはフロー（@ai.flow()）であり、エージェントではありません。エージェント（ai.define_agent）を直接 flow:run することはできません。CLI からエージェントを試すには、使い捨てのフローで1ターンをラップし、そのフローを実行します（Agents を参照）。

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

チェックリストと Dev UI の使い方について詳しくは、Dev Workflow を参照してください。

リファレンス

• Examples：構造化出力、ストリーミング、フロー、ツール、エンベディング。
• Setup：新規プロジェクトの初期設定とプラグイン。
• Common Errors：問題が発生したときは、まずこちらを確認してください。
• FastAPI：HTTP、genkit_fastapi_handler、並列フロー。
• Dotprompt：.prompt ファイルとヘルパー。
• Evals：評価器とデータセット。
• Dev Workflow：genkit start、Dev UI、チェックリスト。
• Agents (Beta)：マルチターン API。