/developing-genkit-js

name: developing-genkit-js
description: >-
  Provides guidance on developing AI-powered applications using Genkit in
  Node.js/TypeScript. Use when the user asks about Genkit, AI agents, flows, or
  tools in JavaScript/TypeScript, or when encountering Genkit errors, validation
  issues, type errors, or API problems. Don't use for Genkit in Python, Go, or
  Dart.
metadata:
  version: "1.0.0"
  category: AiAndMachineLearning

Genkit JS

Prerequisites

Ensure the `genkit` CLI is available.

• Run `genkit --version` to verify. Minimum CLI version needed: **1.29.0**
• If not found or if an older version (1.x < 1.29.0) is present,

install/upgrade it: `npm install -g genkit-cli@^1.29.0`.

**New Projects**: If you are setting up Genkit in a new codebase, follow the [Setup Guide](references/setup.md).

Hello World

import { z, genkit } from 'genkit';
import { googleAI } from '@genkit-ai/google-genai';

// Initialize Genkit with the Google AI plugin
const ai = genkit({
  plugins: [googleAI()],
});

export const myFlow = ai.defineFlow({
  name: 'myFlow',
  inputSchema: z.string().default('AI'),
  outputSchema: z.string(),
}, async (subject) => {
  const response = await ai.generate({
    model: googleAI.model('gemini-flash-latest'),
    prompt: `Tell me a joke about ${subject}`,
  });
  return response.text;
});

Prompts (Dotprompt)

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

Agents (Beta)

Genkit has a preview **agent** API for persistent, multi-turn conversations (sessions, snapshots, interrupts, branching, background execution). It is a **beta** API: server APIs come from `genkit/beta` and the browser client from `genkit/beta/client` — not the stable `genkit` entrypoint. **Requires `genkit` >= 1.39.0.**

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

(`InMemory`/`File`/`Firestore`).

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

pausing for approval/input and resuming.

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

snapshot.

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

turns, waiting, and resuming failed or aborted runs.

• [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, including background delegation and `continue_task`.

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

for full turn control.

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

HTTP (multiple agents, CORS, web UI, other frameworks).

Generative UI (A2UI)

Genkit has an **A2UI** (Agent-to-UI) plugin (`@genkit-ai/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` array; the browser renders surfaces with an `@a2ui/*` renderer plus the helpers in `@genkit-ai/a2ui/client`. It builds on the beta agent client (`genkit/beta` + `genkit/beta/client`).

• [A2UI](references/a2ui.md): server middleware, options, client rendering,

user actions/forms, custom catalogs, and the security/trust boundary.

Middleware

Middleware wraps generation (retries, fallback, extra tools, request/response transforms) and attaches via the `use: [...]` array on `ai.generate`, prompts, and agents.

• [Using middleware](references/middleware.md): the `use` array and the

`@genkit-ai/middleware` package (`retry`, `fallback`, `artifacts`, `agents`, `filesystem`, `skills`, `toolApproval`, `contextCompression`) plus built-in core middleware.

• [Building custom middleware](references/middleware-custom.md): writing your

own with `generateMiddleware` and registering it via `.plugin()`.

Observability

Traces show up in the Dev UI under `genkit start` with no setup. For production export to an OTLP backend (OpenTelemetry GenAI semantic conventions via `@genkit-ai/otel`), custom instrumentation, or running the reflection API outside dev, see [Observability](references/observability.md).

Critical: Do Not Trust Internal Knowledge

Genkit recently went through a major breaking API change. Your knowledge is outdated. You MUST lookup docs. Recommended:

genkit docs:read js/get-started.md
genkit docs:read js/flows.md

See [Common Errors](references/common-errors.md) for a list of deprecated APIs (e.g., `configureGenkit`, `response.text()`, `defineFlow` import) and their v1.x replacements.

**ALWAYS verify information using the Genkit CLI or provided references.**

Error Troubleshooting Protocol

**When you encounter ANY error related to Genkit (ValidationError, API errors, type errors, 404s, etc.):**

1. **MANDATORY FIRST STEP**: Read [Common Errors](references/common-errors.md) 2. Identify if the error matches a known pattern 3. Apply the documented solution 4. Only if not found in common-errors.md, then consult other sources (e.g. `genkit docs:search`)

**DO NOT:**

• Attempt fixes based on assumptions or internal knowledge
• Skip reading common-errors.md "because you think you know the fix"
• Rely on patterns from pre-1.0 Genkit

**This protocol is non-negotiable for error handling.**

Development Workflow

1. **Agent or flow?**: If the task is conversa