Genkit Python
Build AI features in Python — generation, structured output, streaming, tools,
flows, and multi-turn agents — with Genkit Python 0.13.
- New project? See Setup and
Examples.
- Upgrading from 0.12 or fixing broken 0.12 imports/signatures? Read
Migrating from 0.12 to 0.13 first.
Prerequisites
- Python 3.10+ and
uv
(install)
- Genkit CLI:
npm install -g genkit-cli if genkit --version is missing
Hello World
from genkit import Genkit
from genkit_google_genai import GoogleAI
ai = Genkit(
plugins=[GoogleAI()],
model=GoogleAI.gemini('gemini-flash-latest'),
)
async def main() -> None:
response = await ai.generate(prompt='Suggest one seasonal pasta dish.')
if response.error:
raise RuntimeError(response.error.message)
print(response.text)
# => Lemony tagliatelle with asparagus, sweet peas, and herb ricotta
if __name__ == '__main__':
ai.run_main(main())
ai.generate does not raise when the provider rejects or fails a call
(INVALID_ARGUMENT, UNAVAILABLE, rate limits). It returns response.error
(Failure with .status and .message), finish_reason == 'failed', and
empty text. Problems caught before the call raise: GoogleAI() raises
ValueError without GEMINI_API_KEY; an unknown model, invalid key, or unknown
config field raises GenkitError. See
Common Errors.
Agents (Experimental)
Multi-turn chats with history, typed state, human approval, branching, and
background work live under genkit.exp and genkit.exp.agent. Start here:
Agents.
from genkit.exp import Genkit
from genkit.exp.agent import InMemorySessionStore
from genkit_google_genai import GoogleAI
ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))
agent = ai.define_agent(
name='concierge',
system='You are a concise hotel concierge.',
store=InMemorySessionStore(),
)
chat = agent.chat()
res = await chat.send('Recommend a quiet dinner spot.') # AgentResponse
print(res.text)
# => Try Osteria Lume on 5th; it has booths and low music.
turn = chat.send_stream('Is it open past 10pm?') # AgentTurn
async for chunk in turn.stream:
if chunk.text:
print(chunk.text, end='')
final = await turn.response # AgentResponse
More: sessions ·
HITL ·
branching ·
background ·
state ·
artifacts ·
custom ·
HTTP
Imports
Every symbol lives in one public module (never import private _ submodules;
see Migrating from 0.12 to 0.13 if a 0.12
symbol moved):
- Core app:
from genkit import Genkit, FlowContext, ToolContext, Message, Part, Role, Media, Document, MultipartToolResponse, PublicError, GenkitError, Failure, ErrorReason
- Google GenAI & Vertex AI:
from genkit_google_genai import GoogleAI, VertexAI, GeminiConfig, GeminiImageConfig, GeminiTtsConfig
- Other providers:
from genkit_vertexai import ModelGarden ·
from genkit_anthropic import Anthropic, AnthropicConfig ·
from genkit_openai import OpenAI, OpenAIConfig ·
from genkit_ollama import Ollama, OllamaConfig ·
from genkit_amazon_bedrock import Bedrock, BedrockConfig
- Built-in middleware:
from genkit_middleware import Middleware, Retry, Fallback, ToolApproval, Skills, Filesystem (plus from genkit_middleware.exp import Artifacts for agent sessions)
- Writing custom middleware:
from genkit.middleware import Middleware, MiddlewareContext
- FastAPI & HTTP:
from genkit_fastapi import serve_flow, genkit_fastapi_handler, handle_genkit_request · from genkit_fastapi.exp import serve_agent ·
from genkit.web import RequestData, to_sse, error_body, error_status
- Agents (experimental):
from genkit.exp import Genkit, current_session · from genkit.exp.agent import Agent, Session, InMemorySessionStore, FileSessionStore, remote_agent
- Telemetry:
from genkit_google_cloud import enable_google_cloud_telemetry
· from genkit.telemetry import configure_instrumentation ·
from genkit_otel import GenAiInstrumentation
- MCP (Client & Host):
from genkit_mcp import define_mcp_client, define_mcp_host, McpClient, McpHost
- Testing & Mocks:
from genkit.testing import define_echo_model, define_scripted_model, EchoModel, ScriptedModel
- Evaluators (0.13 only; cut from 1.0, additive later):
from genkit_evaluators import register_genkit_evaluators ·
from genkit.evaluator import BaseDataPoint, EvaluatorResponse, Score, ScoreDetails, ScoreStatus
Workflow
- Agent or flow? Use
ai.define_agent (on genkit.exp.Genkit, see
Agents) for multi-turn chats, state, or
human-in-the-loop approval instead of hand-rolling a message loop inside a
flow. Use @ai.flow() on genkit.Genkit for stateless request/response or
streaming pipelines.
- Configure credentials & model refs. Set
GEMINI_API_KEY. Prefer
typed refs (GoogleAI.gemini('gemini-flash-latest')) and typed flat configs
(GeminiConfig(...)) so your type checker validates fields before runtime.
Prefixed strings ('googleai/gemini-flash-latest') also work.
- Enter via
ai.run_main(main()) for standalone scripts and CLI apps so
the process stays up for the Dev UI under genkit start. FastAPI apps skip
run_main; uvicorn keeps the process alive:
genkit start -- uv run uvicorn main:app --reload.
- Run with Dev Workflow (
genkit start + Dev
UI) and type-check with pyright, mypy, or ty.
- Verify with traces, not a blind
uv run. See
Genkit CLI.
- Stuck? Check Gotchas,
Common Errors, or
Migrating from 0.12 to 0.13.
Gotchas
- Agents need
genkit.exp: from genkit.exp import Genkit. Stable
genkit.Genkit has no define_agent.
- Tools are async:
@ai.tool() raises TypeError on a plain def; use
async def.
- Check
response.error: provider failures come back on the response, not
as exceptions (see Hello World).
- Gemini thinking levels:
GeminiConfig(thinking_level='MINIMAL') fails on
gemini-flash-latest; use 'LOW', 'MEDIUM', or 'HIGH'.
- Vertex AI model IDs: Vertex does not serve
-latest aliases. Pass a
pinned model ID to VertexAI.gemini(...).
- Logging:
genkit.get_logger is structlog-based.
enable_google_cloud_telemetry() injects trace context for GCP log-trace
correlation.
- Cloud telemetry auth: call
enable_google_cloud_telemetry() with
Application Default Credentials or explicit credentials= (service account
dict or Credentials instance).
Genkit CLI (recommended)
genkit start wraps any Python program that uses Genkit, capturing traces from
every action while forwarding stdio cleanly. Running uv run directly skips
trace capture.
Primary pattern (persistent server + Dev UI):
genkit start -- uv run src/main.py
genkit start --noui -- uv run src/main.py # persistent runtime without opening the Dev UI
genkit start runs until stopped with Ctrl+C (even with --noui). Do not
run genkit start as a blocking step in automated/non-interactive scripts; use
flow:run instead.
Non-interactive use (agents/CI): pass --non-interactive before -- so the
CLI never blocks on prompts:
genkit start --non-interactive -- uv run src/main.py
One-shot flow execution (flow:run): spins up the runtime, invokes one
@ai.flow() by name, prints a Trace ID, and exits:
genkit flow:run myFlow '{"data": "input"}' -- uv run src/main.py
Note: flow:run invokes flows (@ai.flow()), not agents (ai.define_agent).
Wrap a single agent turn in a helper flow to exercise it via flow:run (see
Agents).
Inspecting traces:
genkit trace:list # list recent trace IDs
genkit trace:get <traceId> # human-readable trace inspection
genkit trace:get <traceId> --format json # machine-readable JSON for jq / scripts
Always pass --format json when piping into jq or other parsers.
See Dev Workflow for the full pre-run checklist
and Dev UI walkthrough.
References
- Migrating from 0.12 to 0.13:
Deterministic 0.12 -> 0.13 renames, config flattening,
PublicError, and
exp moves.
- Examples: Structured output, streaming, media parts,
flows, tools, interrupts, cancellation, embeddings.
- Setup: Project bootstrap with
uv, version alignment,
and provider plugins.
- Common Errors: Fast fixes for 0.13 validation
errors, HTTP 500 redaction, streaming, and sessions.
- FastAPI:
serve_flow, serve_agent, PublicError,
SSE streaming, and parallel flows.
- Dotprompt:
.prompt files, schema validation,
variants, partials, and helpers.
- Evals: 0.13 evaluator syntax (deprecated; removed in
1.0).
- Dev Workflow:
genkit start, Dev UI, and trace
verification checklist.
- Agents (Experimental): Multi-turn stateful agents
(
genkit.exp).
1---2name: developing-genkit-python3description: >-4 Provides guidance on developing AI-powered applications using Genkit Python5 (0.13) and migrating Genkit Python 0.12 projects to 0.13. Use when building AI6 agents, flows, tools, structured outputs, or FastAPI routes in Python,7 upgrading from Genkit 0.12, or debugging Genkit imports, config errors, or8 traces. Don't use for Genkit in JavaScript/TypeScript, Go, or Dart.9metadata:10 source: https://skillmd.com/skills/google/developing-genkit-python11 version: "1.0.0"12 category: AiAndMachineLearning13---1415# Genkit Python1617Build AI features in Python — generation, structured output, streaming, tools,18flows, and multi-turn agents — with Genkit Python 0.13.1920- **New project?** See [Setup](references/setup.md) and21 [Examples](references/examples.md).22- **Upgrading from 0.12 or fixing broken 0.12 imports/signatures?** Read23 [Migrating from 0.12 to 0.13](references/migrating-from-0.12.md) first.2425## Prerequisites2627- Python **3.10+** and **`uv`**28 ([install](https://docs.astral.sh/uv/getting-started/installation/))29- Genkit CLI: `npm install -g genkit-cli` if `genkit --version` is missing3031## Hello World3233```python34from genkit import Genkit35from genkit_google_genai import GoogleAI3637ai = Genkit(38 plugins=[GoogleAI()],39 model=GoogleAI.gemini('gemini-flash-latest'),40)414243async def main() -> None:44 response = await ai.generate(prompt='Suggest one seasonal pasta dish.')45 if response.error:46 raise RuntimeError(response.error.message)47 print(response.text)48 # => Lemony tagliatelle with asparagus, sweet peas, and herb ricotta495051if __name__ == '__main__':52 ai.run_main(main())53```5455`ai.generate` does not raise when the provider rejects or fails a call56(`INVALID_ARGUMENT`, `UNAVAILABLE`, rate limits). It returns `response.error`57(`Failure` with `.status` and `.message`), `finish_reason == 'failed'`, and58empty text. Problems caught before the call raise: `GoogleAI()` raises59`ValueError` without `GEMINI_API_KEY`; an unknown model, invalid key, or unknown60config field raises `GenkitError`. See61[Common Errors](references/common-errors.md).6263## Agents (Experimental)6465Multi-turn chats with history, typed state, human approval, branching, and66background work live under `genkit.exp` and `genkit.exp.agent`. Start here:67[Agents](references/agents.md).6869```python70from genkit.exp import Genkit71from genkit.exp.agent import InMemorySessionStore72from genkit_google_genai import GoogleAI7374ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))75agent = ai.define_agent(76 name='concierge',77 system='You are a concise hotel concierge.',78 store=InMemorySessionStore(),79)8081chat = agent.chat()82res = await chat.send('Recommend a quiet dinner spot.') # AgentResponse83print(res.text)84# => Try Osteria Lume on 5th; it has booths and low music.8586turn = chat.send_stream('Is it open past 10pm?') # AgentTurn87async for chunk in turn.stream:88 if chunk.text:89 print(chunk.text, end='')90final = await turn.response # AgentResponse91```9293More: [sessions](references/agents-sessions.md) ·94[HITL](references/agents-human-in-the-loop.md) ·95[branching](references/agents-branching.md) ·96[background](references/agents-background.md) ·97[state](references/agents-state.md) ·98[artifacts](references/agents-artifacts.md) ·99[custom](references/agents-custom.md) ·100[HTTP](references/agents-http.md)101102## Imports103104Every symbol lives in one public module (never import private `_` submodules;105see [Migrating from 0.12 to 0.13](references/migrating-from-0.12.md) if a 0.12106symbol moved):107108- **Core app**: `from genkit import Genkit, FlowContext, ToolContext, Message, Part, Role, Media, Document, MultipartToolResponse, PublicError, GenkitError, Failure, ErrorReason`109- **Google GenAI & Vertex AI**: `from genkit_google_genai import GoogleAI, VertexAI, GeminiConfig, GeminiImageConfig, GeminiTtsConfig`110- **Other providers**: `from genkit_vertexai import ModelGarden` ·111 `from genkit_anthropic import Anthropic, AnthropicConfig` ·112 `from genkit_openai import OpenAI, OpenAIConfig` ·113 `from genkit_ollama import Ollama, OllamaConfig` ·114 `from genkit_amazon_bedrock import Bedrock, BedrockConfig`115- **Built-in middleware**: `from genkit_middleware import Middleware, Retry, Fallback, ToolApproval, Skills, Filesystem` (plus `from genkit_middleware.exp import Artifacts` for agent sessions)116- **Writing custom middleware**:117 `from genkit.middleware import Middleware, MiddlewareContext`118- **FastAPI & HTTP**:119 `from genkit_fastapi import serve_flow, genkit_fastapi_handler,120 handle_genkit_request` · `from genkit_fastapi.exp import serve_agent` ·121 `from genkit.web import RequestData, to_sse, error_body, error_status`122- **Agents (experimental)**: `from genkit.exp import Genkit, current_session` · `from genkit.exp.agent import Agent, Session, InMemorySessionStore, FileSessionStore, remote_agent`123- **Telemetry**: `from genkit_google_cloud import enable_google_cloud_telemetry`124 · `from genkit.telemetry import configure_instrumentation` ·125 `from genkit_otel import GenAiInstrumentation`126- **MCP (Client & Host)**: `from genkit_mcp import define_mcp_client, define_mcp_host, McpClient, McpHost`127- **Testing & Mocks**: `from genkit.testing import define_echo_model, define_scripted_model, EchoModel, ScriptedModel`128- **Evaluators (0.13 only; cut from 1.0, additive later)**:129 `from genkit_evaluators import register_genkit_evaluators` ·130 `from genkit.evaluator import BaseDataPoint, EvaluatorResponse, Score,131 ScoreDetails, ScoreStatus`132133## Workflow1341351. **Agent or flow?** Use `ai.define_agent` (on `genkit.exp.Genkit`, see136 [Agents](references/agents.md)) for multi-turn chats, state, or137 human-in-the-loop approval instead of hand-rolling a message loop inside a138 flow. Use `@ai.flow()` on `genkit.Genkit` for stateless request/response or139 streaming pipelines.1402. **Configure credentials & model refs.** Set **`GEMINI_API_KEY`**. Prefer141 typed refs (`GoogleAI.gemini('gemini-flash-latest')`) and typed flat configs142 (`GeminiConfig(...)`) so your type checker validates fields before runtime.143 Prefixed strings (`'googleai/gemini-flash-latest'`) also work.1443. **Enter via `ai.run_main(main())`** for standalone scripts and CLI apps so145 the process stays up for the Dev UI under `genkit start`. FastAPI apps skip146 `run_main`; uvicorn keeps the process alive:147 `genkit start -- uv run uvicorn main:app --reload`.1484. **Run with [Dev Workflow](references/dev-workflow.md)** (`genkit start` + Dev149 UI) and type-check with `pyright`, `mypy`, or `ty`.1505. **Verify with traces**, not a blind `uv run`. See151 [Genkit CLI](#genkit-cli-recommended).1526. **Stuck?** Check [Gotchas](#gotchas),153 [Common Errors](references/common-errors.md), or154 [Migrating from 0.12 to 0.13](references/migrating-from-0.12.md).155156## Gotchas157158- **Agents need `genkit.exp`**: `from genkit.exp import Genkit`. Stable159 `genkit.Genkit` has no `define_agent`.160- **Tools are async**: `@ai.tool()` raises `TypeError` on a plain `def`; use161 `async def`.162- **Check `response.error`**: provider failures come back on the response, not163 as exceptions (see [Hello World](#hello-world)).164- **Gemini thinking levels**: `GeminiConfig(thinking_level='MINIMAL')` fails on165 `gemini-flash-latest`; use `'LOW'`, `'MEDIUM'`, or `'HIGH'`.166- **Vertex AI model IDs**: Vertex does not serve `-latest` aliases. Pass a167 pinned model ID to `VertexAI.gemini(...)`.168- **Logging**: `genkit.get_logger` is structlog-based.169 `enable_google_cloud_telemetry()` injects trace context for GCP log-trace170 correlation.171- **Cloud telemetry auth**: call `enable_google_cloud_telemetry()` with172 Application Default Credentials or explicit `credentials=` (service account173 dict or `Credentials` instance).174175## Genkit CLI (recommended)176177`genkit start` wraps any Python program that uses Genkit, capturing traces from178every action while forwarding stdio cleanly. Running `uv run` directly skips179trace capture.180181**Primary pattern (persistent server + Dev UI):**182```bash183genkit start -- uv run src/main.py184genkit start --noui -- uv run src/main.py # persistent runtime without opening the Dev UI185```186`genkit start` runs until stopped with Ctrl+C (even with `--noui`). Do **not**187run `genkit start` as a blocking step in automated/non-interactive scripts; use188`flow:run` instead.189190**Non-interactive use (agents/CI):** pass `--non-interactive` before `--` so the191CLI never blocks on prompts:192```bash193genkit start --non-interactive -- uv run src/main.py194```195196**One-shot flow execution (`flow:run`):** spins up the runtime, invokes one197`@ai.flow()` by name, prints a `Trace ID`, and exits:198```bash199genkit flow:run myFlow '{"data": "input"}' -- uv run src/main.py200```201Note: `flow:run` invokes flows (`@ai.flow()`), not agents (`ai.define_agent`).202Wrap a single agent turn in a helper flow to exercise it via `flow:run` (see203[Agents](references/agents.md)).204205**Inspecting traces:**206```bash207genkit trace:list # list recent trace IDs208genkit trace:get <traceId> # human-readable trace inspection209genkit trace:get <traceId> --format json # machine-readable JSON for jq / scripts210```211Always pass `--format json` when piping into `jq` or other parsers.212213See [Dev Workflow](references/dev-workflow.md) for the full pre-run checklist214and Dev UI walkthrough.215216## References217218- [Migrating from 0.12 to 0.13](references/migrating-from-0.12.md):219 Deterministic 0.12 -> 0.13 renames, config flattening, `PublicError`, and220 `exp` moves.221- [Examples](references/examples.md): Structured output, streaming, media parts,222 flows, tools, interrupts, cancellation, embeddings.223- [Setup](references/setup.md): Project bootstrap with `uv`, version alignment,224 and provider plugins.225- [Common Errors](references/common-errors.md): Fast fixes for 0.13 validation226 errors, HTTP 500 redaction, streaming, and sessions.227- [FastAPI](references/fastapi.md): `serve_flow`, `serve_agent`, `PublicError`,228 SSE streaming, and parallel flows.229- [Dotprompt](references/dotprompt.md): `.prompt` files, schema validation,230 variants, partials, and helpers.231- [Evals](references/evals.md): 0.13 evaluator syntax (deprecated; removed in232 1.0).233- [Dev Workflow](references/dev-workflow.md): `genkit start`, Dev UI, and trace234 verification checklist.235- [Agents (Experimental)](references/agents.md): Multi-turn stateful agents236 (`genkit.exp`).