/developing-genkit-python

name: developing-genkit-python
description: >-
  Provides guidance on developing AI-powered applications using Genkit Python
  (0.13) and migrating Genkit Python 0.12 projects to 0.13. Use when building AI
  agents, flows, tools, structured outputs, or FastAPI routes in Python,
  upgrading from Genkit 0.12, or debugging Genkit imports, config errors, or
  traces. Don't use for Genkit in JavaScript/TypeScript, Go, or Dart.
metadata:
  version: "1.0.0"
  category: AiAndMachineLearning

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](references/setup.md) and

[Examples](references/examples.md).

• **Upgrading from 0.12 or fixing broken 0.12 imports/signatures?** Read

[Migrating from 0.12 to 0.13](references/migrating-from-0.12.md) first.

Prerequisites

• Python **3.10+** and **`uv`**

([install](https://docs.astral.sh/uv/getting-started/installation/))

• 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](references/common-errors.md).

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](references/agents.md).

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](references/agents-sessions.md) · [HITL](references/agents-human-in-the-loop.md) · [branching](references/agents-branching.md) · [background](references/agents-background.md) · [state](references/agents-state.md) · [artifacts](references/agents-artifacts.md) · [custom](references/agents-custom.md) · [HTTP](references/agents-http.md)

Imports

Every symbol lives in one public module (never import private `_` submodules; see [Migrating from 0.12 to 0.13](references/migrating-from-0.12.md) 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

1. **Agent or flow?** Use `ai.define_agent` (on `genkit.exp.Genkit`, see [Agents](references/agents.md)) 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. 2. **Configure credentials & model refs.** Set **`GEMINI_API_KEY`**. Prefer typed refs (`GoogleAI.gemini('gemini-flash-latest')`) and typed flat configs (`GeminiConfig(...