genkit_shelf

Releases

1. ▸▾1.0.07 Oct 2026

   Release genkit_shelf-v1.0.0

   Release genkit_shelf-v1.0.0

   Open source →

   Additional notes

   Genkit Dart is now 1.0. The core genkit package, schemantic, and the main plugins are stable and covered by semantic versioning. Some packages stay on 0.x because their underlying platforms or APIs are still changing:

   Package	Version
   genkit, schemantic, schemantic_builder	1.0.0
   genkit_google_genai, genkit_vertexai, genkit_anthropic, genkit_openai	1.0.0
   genkit_middleware, genkit_mcp, genkit_shelf	1.0.0
   genkit_firebase_ai, genkit_google_cloud	0.3.0
   genkit_chrome, genkit_otel, genkit_vertex_auth	0.2.0
   genkit_a2ui	0.4.0

   This release has a lot of breaking changes. Most of them are small renames and tightened types that came out of a full review of the public API before freezing it. The ones you are most likely to hit are GenkitRouter (if you used genkit_shelf), prompts, and GenerateResult.

   Highlights

   Stable vs. experimental imports

   The stable API is now clearly separated from experimental features. Stable libraries are covered by semver:

   import 'package:genkit/genkit.dart';
   import 'package:genkit/client.dart';
   import 'package:genkit/lite.dart';
   import 'package:genkit/plugin.dart';
   import 'package:genkit/telemetry.dart';
   import 'package:genkit/io.dart';       // new: HTTP serving (dart:io)

   Experimental features have their own imports. They can change or be removed in any minor release:

   import 'package:genkit/experimental.dart';        // agents, sessions, snapshots, live/bidi models
   import 'package:genkit/experimental_client.dart'; // browser-safe agent client
   import 'package:genkit/experimental_io.dart';     // FileSessionStore, GenkitRouter.addAgent
   import 'package:genkit_middleware/agents.dart';   // agents() sub-agent delegation middleware

   These libraries are annotated @experimental, so the analyzer warns (experimental_member_use) as soon as you import one. If you've accepted the instability, you can silence the warning:

   # analysis_options.yaml
   analyzer:
     errors:
       experimental_member_use: ignore

   What moved:

   • Agent and session data types (AgentOutput, AgentInput, SessionSnapshot, TurnEnd, Artifact, JsonPatchOperation, and about 15 more) are no longer exported from the stable libraries. Import experimental.dart or experimental_client.dart. (#480)
   • genkit_middleware no longer re-exports agents(), AgentsPlugin, AgentsOptions and related types. Import package:genkit_middleware/agents.dart directly. (#482)
   • Bidi streaming: calling Action.streamBidi() now triggers the experimental warning. BidiActionStream and BidiActionFn are exported from experimental.dart. (#483)
   • Dev UI reflection protocol types are no longer exported. (#481)

   Serving over HTTP: GenkitRouter

   HTTP serving now lives in core (package:genkit/io.dart) and runs on plain dart:io. genkit_shelf is now a thin adapter on top of it. startFlowServer and FlowWithContextProvider are gone. (#533)

   import 'package:genkit/io.dart';
   
   final genkit = GenkitRouter()
     ..addAction(helloFlow)                                 // POST /hello
     ..addAction(secureFlow, contextProvider: bearerAuth)   // per-action auth
     ..addAction(googleAI().model('gemini-flash-latest'));  // models and tools can be served too
   
   await genkit.serve(port: 8080, cors: const CorsOptions());

   Context providers get a framework-neutral RequestData instead of a shelf Request. Header names are lowercased:

   Future<Map<String, dynamic>> bearerAuth(RequestData request) async {
     final user = await verifyToken(request.headers['authorization']);
     if (user == null) {
       throw GenkitException('Unauthorized', status: StatusCode.unauthenticated); // 401
     }
     return {'userId': user.id}; // becomes ctx.context
   }

   You can also mount it inside your own server, or serve a single action:

   // your own dart:io server
   await for (final request in server) {
     if (await genkit.handleHttpRequest(request, basePath: '/api')) continue;
     // ...your routes
   }
   
   // single action
   final handleHello = ioHandler(helloFlow, contextProvider: bearerAuth);
   
   // shelf
   final app = Router()
     ..post('/hello', shelfHandler(helloFlow))
     ..mount('/api/', genkit.asShelfHandler());

   Agents (experimental) mount with one call. You no longer need hand-written /getSnapshot and /abort routes:

   import 'package:genkit/experimental_io.dart';
   
   final api = GenkitRouter()
     ..addAgent(weatherAgent)                               // turn + /getSnapshot + /abort
     ..addAgent(bankingAgent, contextProvider: bearerAuth);

   Migrating from startFlowServer:

   // before
   await startFlowServer(
     flows: [helloFlow, FlowWithContextProvider(flow: secureFlow, context: bearerAuth)],
     cors: {'origin': '*'},
   );
   
   // after
   final genkit = GenkitRouter()
     ..addAction(helloFlow)
     ..addAction(secureFlow, contextProvider: bearerAuth);
   await genkit.serve(cors: const CorsOptions());

   Wire format change: streamed responses now use Content-Type: text/event-stream, and a failed stream ends with a data: {"error": ...} frame instead of error: {...}. This matches the Go and Python servers. Clients from genkit 0.17 and earlier only understand the old frame. If you have shipped apps (for example Flutter apps) that use an old client, turn on the legacy frame:

   final genkit = GenkitRouter(sendLegacyErrorFrame: true);

   See #533 for the full design and migration guide.

   Constrained generation middleware

   Some models don't support constrained (schema-enforced) output natively. For those, you can opt into simulateConstrainedGeneration(). It moves the output schema into the prompt as instructions, so structured output still works. It's built in, so you don't need to register a plugin. (#453, #519)

   final response = await ai.generate(
     model: someModel,
     prompt: 'Describe a cat',
     outputSchema: Cat.$schema,
     use: [simulateConstrainedGeneration()],
   );
   
   // Lite API
   await lite.generate(
     model: model,
     outputSchema: Cat.$schema,
     use: [SimulateConstrainedGenerationMiddleware()],
   );

   Nothing is rewritten unless you add the middleware. If a model doesn't support constrained output (for example Chrome's built-in model), add the middleware or use the provider's own config option, such as Chrome's responseConstraint.

   Typed prompts

   Prompts now have an Output type parameter, so they return typed structured output just like generate. ExecutablePrompt is renamed to Prompt. Call options are now named parameters, the same ones generate takes. (#527, #622)

   final joke = ai.definePrompt(
     name: 'joke',
     inputSchema: JokeInput.$schema,
     outputSchema: Joke.$schema,
     prompt: 'Tell a joke about {{topic}}',
   ); // Prompt<JokeInput, Joke>
   
   final Joke? j = (await joke(JokeInput(topic: 'cats'), config: {'temperature': 0.2})).output;
   
   // typed lookup
   final p = await ai.prompt<JokeInput, Joke>('joke');
   
   // .prompt file with a schema but no Dart type
   final s = await ai.prompt('summarize', outputParserSchema: Summary.$schema);

   The Lite API's generate / generateStream also infer a typed output from outputSchema now. (#499)

   Middleware

   • ai.defineGenerateMiddleware registers middleware from app code, with no plugin needed. The top-level defineMiddleware used by plugin authors is renamed to generateMiddleware. (#571)

     final logging = ai.defineGenerateMiddleware<LoggingOptions>(
       name: 'logging',
       configSchema: LoggingOptions.$schema,
       create: (config, ctx) => LoggingMiddleware(config),
     );
     
     await ai.generate(prompt: 'hi', use: [logging(LoggingOptions(level: 'debug'))]);

   • retry() works out of the box. RetryPlugin is removed; delete it from plugins:. Delays are now Durations, and retryModel is now noRetryModel. (#531, #549)

     use: [retry(maxRetries: 3, initialDelay: const Duration(milliseconds: 500))]

   • The middleware tool hook returns ToolResult. GenerateMiddleware.tool now returns Future<ToolResult>, and ToolInterruptException is removed. Return .interrupt(data) instead of throwing. (#503)

   Breaking changes

   Core (genkit)

   Generate results

   • GenerateResponseHelper is renamed to GenerateResult. rawResponse is now modelResponse, rawChunk is now modelChunk, and jsonOutput is removed (use output). (#534)
   • GenerateResult and GenerateResponseChunk are now read-only views. They no longer extend the wire types and have no setters or toJson(). To forward chunks to a flow, use onChunk: (c) => ctx.sendChunk(c.modelChunk). (#547)
   • Usage counts and indexes (inputTokens, outputTokens, Candidate.index, ...) are now int instead of double. (#546)

   Prompts

   • ExecutablePrompt<Input> is now Prompt<Input, Output>. Type parameter order is now payload types first, config last, everywhere: generate<Output, CustomOptions>, definePrompt<Input, Output, CustomOptions>, defineAgent<Input, State, CustomOptions>. (#527)
   • Prompt.call / stream / render take named parameters. PromptGenerateOptions is removed. (#622)
   • ExecutablePrompt.ref is now a PromptRef class instead of a record. PromptConfig is no longer exported. (#528, #529)

   Renames

   Before	After	PR
   StatusCodes.NOT_FOUND	StatusCode.notFound (use .wireName for 'NOT_FOUND')	#542
   EvalStatusEnum.PASS	EvalStatus.pass	#545
   GenkitException(underlyingException:)	GenkitException(cause:). statusCode is removed (use status.value or status.httpStatus)	#548
   ToolFnArgs	ToolFnArg	#537
   remoteModel(modelInfo:), modelMetadata(modelInfo:)	info:	#537
   RemoteAction.dispose()	close()	#537
   Tool(toolOutputSchema:)	Tool(outputSchema:)	#530
   ai.embedMany(documents:)	ai.embed(documents:)	#535
   cacheTtlMillis: 60000	cacheTtl: const Duration(minutes: 1) (also in genkit_mcp)	#539
   defineMiddleware(...)	generateMiddleware(...)	#571

   Types and class shapes

   • toolChoice is now a ToolChoice open enum instead of String, for example toolChoice: .required. (#493)
   • Open-enum values (Role, FinishReason, ToolChoice, ...) are now const, so you can use them as switch cases. (#544)
   • ActionFnArg, GenerateTurnState and GenerateMiddlewareContext are now final classes instead of record typedefs. Code that built them with record literals needs to use the constructors. (#484, #485, #486)
   • Core classes now have class modifiers. Actions (Model, Flow, Tool, ...) are base. Handle types are final. Registry is final, and its plumbing methods are now @internal. (#487, #529)
   • The Model, Embedder, Evaluator and Flow constructors now take non-null input, so plugin authors no longer need req!. Evaluator drops its unused type parameter. (#536, #528)
   • ActionStream.setResult / setError and the ActionMetadata.key setter are now @internal. BidiModel.customOptions and Embedder.customOptions are now final. (#488, #489, #528)
   • GenerateMiddlewareDef is now a final, callable class. Build one with generateMiddleware or ai.defineGenerateMiddleware. (#571)

   Removed

   • ToolFnArgs.interrupt(). Return .interrupt(data) from the tool instead. (#497)
   • ToolInterruptException. (#503)
   • RetryPlugin. (#531)
   • Formatter, FormatterHandlerResult, MessageParser and ChunkParser exports. (#491)
   • createResourceMatcher from genkit.dart. It's now exported from plugin.dart. (#529)
   • The old, empty package:genkit/io.dart. The name is reused for the new HTTP serving library. (#498, #533)

   Added exports

   Types that appeared in public signatures but couldn't be named are now exported: ActionStream, Evaluator, ActionFn, StreamingCallback, Registry, and others. (#490)

   Dotprompt 2.0

   .prompt files now use spec-compliant Picoschema:

   • tags(array): string is now an array of strings. It used to be a string with the description "array".
   • (*): string now maps to additionalProperties.
   • The old description form email(the email): string logs a warning at load time and fails at render time. Use email: string, the email instead.

   (#573)

   genkit_shelf

   • startFlowServer and FlowWithContextProvider are removed. Use GenkitRouter with shelfHandler / asShelfHandler(). Context providers take RequestData. See Serving over HTTP. (#533)

   genkit_middleware

   • The agents middleware is no longer exported from the main library. Import package:genkit_middleware/agents.dart. (#482)

   genkit_google_genai / genkit_vertexai

   • GoogleAiModels is removed. Name models by string: googleAI.gemini('gemini-flash-latest'), googleAI.geminiTts('gemini-3.8-flash-tts'). Catalog enums are no longer exported. (#524)
   • Exported option types now have a provider prefix, which avoids import clashes with other plugins. ThinkingConfig is now GeminiThinkingConfig. The same applies to GeminiSafetySettings, GeminiFunctionCallingConfig, GeminiGoogleSearch, GeminiFileSearch, and the speech/voice config types. TextEmbedderOptions is now GoogleGenAiEmbedderOptions. (#572)

   genkit_anthropic

   • ThinkingConfig is now AnthropicThinkingConfig. (#572)
   • toolChoice: required now maps to Anthropic's any. (#492)

   genkit_openai

   • OpenAIModels, OpenAIEmbedders, XaiModels and DeepSeekModels are removed. Use openAI.model('gpt-5.5'), xAI.model(...), deepSeek.model(...) and openAI.embedder(...). modelInfoFor and related functions are still exported. OpenAIModelKind is now a class. (#525)
   • Implementation helpers (GenkitConverter, getModelType, the capability-set constants) are no longer exported. (#502)

   schemantic

   • Generated code now emits plain JSON Schema maps instead of json_schema_builder calls. $Schema and the SchemaValidation re-export are removed. Regenerate your .g.dart files with schemantic_builder 1.0.0. (#522)

   New features

   Core (genkit)

   • Interrupt tool class for human-in-the-loop patterns. Tool and the related types are now exported from the Lite API. (#399)

   genkit_openai

   • Text-to-speech with tts-1, tts-1-hd and gpt-4o-mini-tts through openAI.speechModel(). (#405)
   • Speech-to-text with whisper-1, gpt-4o-transcribe and gpt-4o-mini-transcribe through openAI.transcriptionModel(), including Whisper translation. (#406)
   • reasoningEffort and verbosity options, plus reasoning output. (#430)

   genkit_anthropic

   • Stable/beta API selection (apiVersion, betas) and native structured output through output_config.format. Structured output now works together with extended thinking and with your own tools. (#402)
   • Every Claude model, including ones not yet in the curated catalog, now claims native structured output. (#518)
   • You can pass a custom http.Client. (#226)

   genkit_google_genai / genkit_vertexai

   • gemini-embedding-* embedders are discovered automatically and can embed media. (#394)
   • The curated model catalog is expanded to match the JS/Go plugins, and TTS models get the correct capability profile. (#513, #523, #524)

   Bug fixes

   Core (genkit)

   • A partial streamed chunk that doesn't match the output schema yet no longer fails the generation. (#500)
   • Reflection health checks for a different runtime id are now rejected. (#477)
   • The v1 reflection server reports the real package version. (#506)
   • defineSchema names in .prompt files are resolved at render time. (#570)
   • Detached agent turns keep running after a remote detach. (#567)
   • The remote client keeps the server's error status and message instead of a generic HTTP-derived error. (#568)
   • Logging now goes through package:logging instead of print(). (#508)

   genkit_middleware

   • Fixed a filesystem sandbox escape through symlinks. (#566)
   • ToolApprovalPlugin(approvedTools:) is honored when toolApproval() is called without a list. (#538)

   Plugins

   • google_genai, openai, firebase_ai: now honor the portable toolChoice option. (#494, #495, #496)
   • google_genai: Gemini finish reasons now map to Genkit's vocabulary. (#425)
   • google_genai, vertexai: injected HTTP clients are no longer closed by the plugin, and late cancellation is honored. (#454)
   • google_genai, vertexai: list() falls back to the curated catalog when model discovery fails. (#512)
   • openai: fixed xAI recursive tool schemas, and xAI model discovery no longer lists models that can't be served. (#476)
   • firebase_ai: stopped pre-registering the retired gemini-2.5-pro. (#509)

   Docs

   • READMEs now explain how to install the Genkit Dart agent skill. (#521)
   • example/ programs added for genkit_chrome, genkit_firebase_ai and genkit_google_cloud. (#505)
   • Fixed stale package descriptions. The Preview label is removed from the root README. (#504, #632)

   Full Changelog: genkit-v0.17.0...genkit-v1.0.0

• genkitpub.devGenkit Dart package, a Generative AI library for pure Dart client/server and Flutter apps.
• schemanticpub.devA lightweight library for type-safe data classes and runtime JSON Schemas, with built-in serialization and validation.
• genkit_google_genaipub.devGoogle AI plugin for Genkit Dart.
• genkit_vertexaipub.devVertex AI plugin for Genkit Dart.
• genkit_vertex_authpub.devShared Vertex AI auth utilities for Genkit Dart provider plugins.