Developing Genkit JS

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.

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: 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: defining/serving an agent and client-managed state (start here).
• Sessions & persistence: session stores (InMemory/File/Firestore).
• Human-in-the-loop / interrupts: pausing for approval/input and resuming.
• Branching: forking a conversation from a snapshot.
• Background agents: detaching long-running turns and polling.
• Working with state: typed custom session state, auto-synced to the client.
• Artifacts: producing and reading named deliverables.
• Multi-agent orchestration: delegating to sub-agents.
• Advanced custom agents: defineCustomAgent for full turn control.
• Deploying agents: 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: 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: the use array and the @genkit-ai/middleware package (retry, fallback, artifacts, agents, filesystem, skills, toolApproval) plus built-in core middleware.
• Building custom middleware: 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 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
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) 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: Check package.json to identify the runtime (Next.js, Firebase, Express).
   • Look for @genkit-ai/next, @genkit-ai/firebase, or @genkit-ai/google-cloud.
   • Adapt implementation to the specific framework's patterns.
4. Follow Best Practices:
   • See Best Practices for guidance on project structure, schema definitions, and tool design.
   • Be Minimal: Only specify options that differ from defaults. When unsure, check docs/source.
5. Ensure Correctness:
   • Run type checks (e.g., npx tsc --noEmit) after making changes.
   • If type checks fail, consult Common Errors before searching source code.
   • Verify with traces, not a blind run. Running the app directly (node/tsx/npm start) does not capture dev traces. See CLI Usage for how to run your app and capture traces.
6. Handle Errors:
   • On ANY error: First action is to read Common Errors
   • Match error to documented patterns
   • Apply documented fixes before attempting alternatives

Finding Documentation

Use the Genkit CLI to find authoritative documentation:

1. Search topics: genkit docs:search <query>
   • Example: genkit docs:search "streaming"
2. List all docs: genkit docs:list
3. Read a guide: genkit docs:read <path>
   • Example: genkit docs:read js/flows.md