Repository navigation
0.13 rewrote Genkit Python's veneer layer and public API surface to clean up ergonomics and typing ahead of 1.0. 0.14 keeps that API surface intact and focuses on hardening it before 1.0: we ran bug bashes across all surfaces—with an emphasis on Dev UI compatibility and provider plugins—and shipped those fixes alongside multi-tenant embedder configuration and a simpler response.media accessor.
1.0 is coming very soon—we're holding the 1.0 tag until we finish moving the Google GenAI plugin onto the Interactions API and cleaning up the Vertex AI plugin naming to match organizational changes, avoiding post-1.0 deprecations. We expect both to ship very soon, and in the meantime we will continue to ship small improvements and bug fixes we find from our thorough bug bashing.
uv add --upgrade genkit
# or: pip install --upgrade genkitGenkit Python has its own repo
Genkit Python now lives in genkit-ai/genkit-python, not in the py/ folder of genkit-ai/genkit.
- Releases come from
mainhere: Going forward, the latest release matchesmainon genkit-python. py/is going away: Thepy/folder will be deleted from genkit-ai/genkit. Open issues and PRs on genkit-python.- Installs don't change: Package names on PyPI are the same, so
pip install genkitand existing pins keep working.
Configure embedders for multi-tenant use cases
GoogleAI() previously raised at startup if no environment API key was set, and ai.embed() had no way to pass a per-request key or tenant context down to an embedder (#49, #114).
GoogleAI() now starts keyless (logging one warning), and ai.embed() / ai.embed_many() accept context={'secrets': {'api_key': ...}}. Rejected keys report ErrorReason.INVALID_CREDENTIALS with status UNAUTHENTICATED.
from genkit import ErrorReason, Genkit
from genkit.embedder import EmbedContext, EmbedRequest, EmbedResponse
from genkit_google_genai import GoogleAI
# 1. Start without a server-wide API key
ai = Genkit(plugins=[GoogleAI()])
# 2. Bill each embed call to the caller's key
vectors = await ai.embed(
embedder=GoogleAI.embedder('gemini-embedding-001'),
content='Mushroom Risotto',
context={'secrets': {'api_key': tenant_key}},
)
# => [Embedding(embedding=[...])]
# 3. Embedder handlers read the same context via EmbedContext
class MenuEmbedConfig(BaseModel):
dimensions: int = 768
async def embed_menu(req: EmbedRequest[MenuEmbedConfig], ctx: EmbedContext) -> EmbedResponse:
api_key = ctx.context['secrets']['api_key']
...
ai.define_embedder('custom/menu', embed_menu, config_schema=MenuEmbedConfig)
# 4. Detect rejected tenant keys on generate() calls
response = await ai.generate(
model=GoogleAI.gemini('gemini-flash-latest'),
prompt='Suggest a dish without peanuts.',
context={'secrets': {'api_key': tenant_key}},
)
if response.error and response.error.reason is ErrorReason.INVALID_CREDENTIALS:
await notify_tenant('Your Gemini key was rejected.')response.media returns the first media item
Reading a generated image or audio part previously required indexing response.media[0]. response.media (along with Message.media and ModelResponseChunk.media) now returns Media | None directly, while the full list moves to media_parts (#47).
response = await ai.generate(
model=GoogleAI.gemini_image('gemini-2.5-flash-image'),
prompt='A watercolor of a cozy bakery.',
)
# 1. Single-image convenience accessor
if response.media:
print(response.media.url)
# => data:image/png;base64,iVBORw0KGgoAAAANSU...
# 2. Iterate all media parts when a model returns more than one
for part in response.media_parts:
save_image(part.url)Bug fixes
Dev UI & tracing
- Failure traces: Show the error message, failure source, and a stack starting at your code instead of an empty
Errorbox (#63, #113, #115). - Per-turn spans: Each tool-loop turn and prompt call gets its own span (#64, #66), and "Open in model runner" pre-fills your config (#116).
- CLI & catalog:
genkit startworks from subdirectories (#53), and Dev UI catalog models run instead of returning 404 (#87).
Provider plugins
- Google GenAI: Lazy model discovery avoids startup 429s (#69), and Gemini
tools+output_schemastops looping (#107). - Anthropic: Preserves multiple
Role.SYSTEMmessages (#146), validatestemperature/top_plocally, and maps prompt-cache token counts (#70). - OpenAI: Skips blank transcription prompts so
gpt-4o-transcribe-diarizeworks from the Dev UI (#136). - Google Cloud: Exports metrics again, forwards
credentials=to all exporters, and adds trace IDs tostructlog(#62). - MCP: Names the failing server/host with its cause and wraps malformed replies in
GenkitError(#72, #74).
Runtime, typing & prompts
- Stream cancellation: Dropping a stream stops the model/tool loop;
genkit-fastapistops on client disconnect and returns 499 (#51). - Middleware: Inline
use=[...]instances keep constructor state, andRetry/Fallbacknever retry after streaming starts (#86). - Usage & reasoning:
response.total_usagesums every model call in a run,.reasoningreturns thinking text, andPart.from_tool_responsesupports multipart content (#48). - Type checking: Catches typed flows/tools called without
inputand mismatched model configs likeVeoConfigon a Gemini ref (#46). - Prompts & JSON: One broken
.promptfile no longer skips its folder,output.constrainedworks, andNaN/Infinityserialize asnullinstead of 500s (#85). - Flows & tools:
ai.run()accepts positional args and async callables (#84), interrupt restarts record approved input (#83), andFilesystem/Skillsstay confined to their roots (#52).
Before you upgrade
FirestoreSessionStore requires an extra (#54)
genkit-google-cloud no longer installs google-cloud-firestore by default. Add the firestore extra if your app imports FirestoreSessionStore:
uv add 'genkit-google-cloud[firestore]'
# or: pip install 'genkit-google-cloud[firestore]'response.media returns a single Media | None (#47)
# Before (0.13)
url = response.media[0].url
for item in response.media: ...
# After (0.14)
url = response.media.url
for item in response.media_parts: ...Run your type checker to catch for item in response.media: loops—iterating a Pydantic model yields (field, value) tuples instead of raising at runtime.
Other notes
- Evaluators are deprecated (#131): Still work in
0.14(with aFutureWarning) and will be removed next release (genkit-evaluatorsis capped at<0.15). Skillsuses folder names (#52):use_skill()matches the skill's directory name rather than YAMLname:.- Plugin authors (#114, #133): Embedder handlers receive
EmbedContextand background/custom actions receiveActionContextinstead ofFlowContext; handlers now accept(req),(req, ctx), or(ctx, req).