/developing-genkit-js

name: developing-genkit-js
description: Develop 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.
metadata:
  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 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.
• [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`) plus built-in core middleware.
• [Building custom middleware](references/middleware-custom.md): writing your own with `generateMiddleware` and registering it via `.plugin()`.

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 conversational, multi-turn, or described as "an agent", "assistant", or "chatbot", build it with `ai.defineAgent` (see [Agents](references/agents.md)) rather than hand-rolling a `generate` + tools loop inside a flow. Reach for a plain flow only for single-shot, stateless generation. 2. **Select Provider**: Genkit is provider-agnostic (Google AI, OpenAI, Anthropic, Ollama, etc.).

• If the user does not specify a provider, default to **Google AI**.
• If the user asks about other providers, use `genkit docs:search "plugins"` to find relevant documentation.

3. **Detect Framework