developing-genkit-js

Files (21)

• SKILL.md
• a2ui.md · references/
• agents-artifacts.md · references/
• agents-background.md · references/
• agents-branching.md · references/
• agents-custom.md · references/
• agents-deployment.md · references/
• agents-human-in-the-loop.md · references/
• agents-multi-agent.md · references/
• agents-sessions.md · references/
• agents-state.md · references/
• agents.md · references/
• best-practices.md · references/
• common-errors.md · references/
• docs-and-cli.md · references/
• dotprompt.md · references/
• examples.md · references/
• middleware-custom.md · references/
• middleware.md · references/
• observability.md · references/
• setup.md · references/

SKILL.md (first lines)

# 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

```ts
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:

```sh
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.**

From google/skills, Apache-2.0.

More from google/skills