/developing-genkit-dart

name: developing-genkit-dart
description: >-
  Provides guidance on developing AI-powered applications using the Genkit Dart
  SDK. Use when the user asks to build AI agents in Dart, use Genkit flows, or
  integrate LLMs into Dart/Flutter applications. Don't use for Genkit in
  JavaScript/TypeScript, Go, or Python.
metadata:
  version: "1.0.0"
  category: AiAndMachineLearning

Genkit Dart

Genkit Dart is an AI SDK for Dart that provides a unified interface for code generation, structured outputs, tools, flows, and AI agents.

Core Features and Usage

If you need help with initializing Genkit (`Genkit()`), Generation (`ai.generate`), Tooling (`ai.defineTool`), Flows (`ai.defineFlow`), Embeddings (`ai.embed`), streaming, or calling remote flow endpoints, please load the core framework reference: [references/genkit.md](references/genkit.md)

1.0 vs pre-1.0 APIs

This skill targets Genkit Dart **1.0** (`genkit: ^1.0.0`). Older code and training data use pre-1.0 names that no longer compile; the common ones:

• HTTP: `startFlowServer` / per-route `shelfHandler` / `shelf_cors_headers` are

now `GenkitRouter` + `serve()` or `asShelfHandler()`, with `CorsOptions`; context providers take `RequestData` ([genkit_shelf.md](references/genkit_shelf.md)).

• `StatusCodes.UNAUTHENTICATED` is `StatusCode.unauthenticated` (lowerCamelCase,

same for `EvalStatus.pass`, `ToolChoice.required`).

• No `RetryPlugin`; `retry()` is built in and takes `Duration`s

(`initialDelay`, `maxDelay`, also `cacheTtl` elsewhere).

• Renames: `GenerateResponseHelper` -> `GenerateResult` (`modelResponse`,

`chunk.modelChunk`), `ExecutablePrompt` -> `Prompt<Input, Output>`, `embedMany` -> `embed`, `ToolFnArgs` -> `ToolFnArg`, `toolOutputSchema` -> `outputSchema`, `underlyingException` -> `cause`, `modelInfo:` -> `info:`, `RemoteAction.dispose()` -> `close()`, `prompt(input, PromptGenerateOptions(config: ...))` -> `prompt(input, config: ...)` (named options, like `generate`), `defineMiddleware` -> `ai.defineGenerateMiddleware` (app) / `generateMiddleware` (plugins).

• Provider config types are prefixed: `GeminiThinkingConfig`,

`GeminiSafetySettings`, `GeminiGoogleSearch`, `GeminiSpeechConfig`, `GoogleGenAiEmbedderOptions`, `AnthropicThinkingConfig`.

• Removed: `ToolInterruptException` / `ctx.interrupt()` (return

`.interrupt(...)`), `GoogleAiModels` / `OpenAIModels` constants (use `googleAI.gemini('...')`, `openAI.model('...')`). Simulated constrained output is opt-in via `simulateConstrainedGeneration()`.

• `.prompt` Picoschema is spec-compliant: `name: type, description`, never

`name(description): type` ([dotprompt.md](references/dotprompt.md)).

Prompts (Dotprompt)

`.prompt` files keep prompt content out of Dart code with YAML frontmatter plus a Handlebars template. See [references/dotprompt.md](references/dotprompt.md): `promptDir`, `ai.prompt()` (call/stream/render), variants, partials, named schemas via `defineSchema`, and the `tools`/`maxTurns`/`returnToolRequests`/`use` (middleware) frontmatter fields. A `.prompt` file can also back an agent directly via `definePromptAgent`.

Agents

Genkit Dart has an **agent** API for persistent, multi-turn conversations (sessions, snapshots, interrupts, branching, background execution, custom state, artifacts, and multi-agent delegation). The agent/session/snapshot APIs are **experimental** and live behind opt-in imports: server APIs come from `package:genkit/experimental.dart` (alongside `package:genkit/genkit.dart`), the browser/HTTP client from `package:genkit/experimental_client.dart` (alongside `package:genkit/client.dart`), and `dart:io` extras like `FileSessionStore` from `package:genkit/experimental_io.dart`. These entry points are `@experimental`, so importing them raises an `experimental_member_use` analyzer warning you can silence in `analysis_options.yaml`. The `remoteAgent` client works from any Dart app, including **Flutter**, and the backend is fully interchangeable — it can talk to a Genkit agent implemented in Dart, JS/TypeScript, or Go over the same HTTP protocol. A few Dart specifics: interrupts are `ai.defineInterrupt(...)` or tools that return `.interrupt(...)` (there is no `ctx.interrupt()`), sub-agent delegation uses the `agents()` middleware from `package:genkit_middleware`, and there is no `artifacts()` middleware yet (define artifact tools directly).

For more details see:

• [Agents](references/agents.md): defining/serving an agent and client-managed

state (start here).

• [Sessions & persistence](references/agents-sessions.md): session stores

(`InMemorySessionStore`/`FileSessionStore`/`FirestoreSessionStore`).

• [Human-in-the-loop / interrupts](references/agents-human-in-the-loop.md):

pausing for approval/input via `.interrupt(...)` and resuming.

• [Branching](references/agents-branching.md): forking a conversation from a

snapshot.

• [Background agents](references/agents-background.md): detaching long-running

turns and polling.

• [Working with state](references/agents-state.md): typed custom session

state, auto-synced to the client.

• [Artifacts](references/agents-artifacts.md): producing and reading named

deliverables.

• [Multi-agent orchestration](references/agents-multi-agent.md): delegating to

sub-agents with the `agents()` middleware.

• [Advanced custom agents](references/agents-custom.md): `defineCustomAgent`

for full turn control.

• [Deploying agents](references/agents-deployment.md): serving agents over

HTTP with `GenkitRouter.addAgent` (multiple agents, shelf, CORS).

Generative UI (A2UI)

Genkit Dart has an **A2UI** (Agent-to-UI) plugin (`genkit_a2ui`) that lets an agent stream interactive UI **surfaces** (cards, lists, forms, buttons), not just prose. The whole server-side integration is the `a2ui()` model middleware in an agent's (or `ai.generate`'s) `use` list; the Flutter client renders surfaces with the [`genui`](https://pub.de