developing-genkit-js

작성자: genkit-ai

Node.js/TypeScript에서 Genkit을 사용하여 AI 기반 애플리케이션을 개발합니다. 사용자가 Genkit, AI 에이전트, 플로우 또는 JavaScript/TypeScript 도구에 대해 질문하거나 Genkit 오류, 검증 문제, 타입 오류 또는 API 문제가 발생할 때 사용하세요.

npx skills add https://github.com/genkit-ai/skills --skill 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:

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, contextCompression) plus built-in core middleware.
  • Building custom middleware: 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.

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

CLI Usage (recommended)

genkit start unintrusively wraps any Node.js program that uses the Genkit library, running it unchanged while capturing traces from every Genkit action so you can prove tools were actually called and inspect model I/O from the terminal, even for headless checks. It forwards stdio, so interactive CLI tools that rely on stdin/stdout work without issues. Running your app directly (node/tsx/npm start) skips trace capture, so you're debugging blind.

Primary pattern (default): prefix genkit start -- to your normal run command. This collects telemetry from any Genkit code your program runs, whether triggered from the dev UI, your own web server/web UI, or a plain script:

genkit start -- npx tsx --watch src/index.ts
genkit start --noui -- npx tsx src/index.ts   # same, without the Dev UI (still a persistent server)

genkit start runs until you stop it with Ctrl+C. That is expected and correct for the common cases: a server your web/mobile app calls, or an interactive CLI you exit yourself. --noui only drops the Dev UI; it is not a one-shot command and will not exit on its own. Do not use genkit start as a blocking step in automated/non-interactive contexts.

Non-interactive use (agents/CI): add the global --non-interactive flag before -- so the CLI uses defaults and never blocks on a prompt (e.g. the first-run analytics notice): genkit start --non-interactive -- npx tsx src/index.ts (works with flow:run too).

Run a flow (flow:run): invoke a specific flow by name from the CLI. Append your run command after -- to spin up the runtime just for this run (the command runs as-is to register your flows):

genkit flow:run myFlow '{"data": "input"}' -- npx tsx src/index.ts

This is self-terminating: it runs the flow once, prints a Trace ID, then exits (inspect it with genkit trace:get <id>). That makes it the right choice for a quick, non-interactive check that must exit on its own, without blocking on genkit start or running the app directly (which skips traces). Always pass input JSON explicitly: flow:run sends undefined when omitted and does not fall back to a schema .default(). Note: flow:run runs flows (ai.defineFlow), not agents; you can't flow:run an agent (ai.defineAgent) directly. To exercise an agent from the CLI, wrap one turn in a throwaway flow and run that (see Agents).

Debugging with traces: the fastest way to see prompts, model inputs/outputs, tool calls, latencies, and errors. Inspect from the terminal after any run under genkit start:

genkit trace:list                        # find recent trace IDs
genkit trace:get <traceId>               # full trace details (inputs, outputs, tool calls, errors)
genkit trace:get <traceId> --format json # machine-readable JSON, safe to pipe into jq or other parsers

For machine-readable output, pass --format json to get clean JSON you can pipe into jq or other parsers. The default output is human-oriented (banner/log lines, possible truncation on large traces), so don't pipe that form directly; use --format json, grep, or the Dev UI trace viewer.

See CLI Reference for more commands, and genkit --help for the full list.

References

관련 스킬

appinsights-instrumentation
microsoft
Azure Application Insights를 사용하여 웹앱을 계측하기 위한 가이드 및 참고 자료입니다. ASP.NET Core 및 Node.js 애플리케이션의 SDK 설정, 원격 분석 패턴, Azure 호스팅 환경에서의 구성을 다룹니다. 이 스킬(참고 및 가이드)과 azure-prepare(실제 구현)를 구분하며, 사용자가 프로젝트에 계측을 추가하려는 경우 azure-prepare를 호출합니다. Azure App Service에서 C# ASP.NET Core 앱에 대한 자동 계측 가이드와 수동...
devopsapidevelopment
azure-ai
microsoft
통합 MCP 도구를 통해 Azure AI Search, Speech, OpenAI 및 Document Intelligence 서비스에 액세스합니다. AI Search는 엔터티 추출 및 OCR을 위한 내장 AI 보강 기능을 갖춘 전체 텍스트, 벡터, 하이브리드 및 의미론적 검색을 지원합니다. Speech 서비스는 실시간 및 배치 음성-텍스트 변환, 신경 음성을 사용한 텍스트-음성 합성, 화자 분할을 처리합니다. MCP 도구는 인덱스 쿼리를 위한 azure__search와 전사 및 합성을 위한 azure__speech에 직접 액세스를 제공합니다. SDK...
researchapidevelopment
azure-prepare
microsoft
Azure 애플리케이션을 인프라스트럭처-애즈-코드, 구성, 컨테이너화를 통해 배포 준비합니다. 애플리케이션 유형과 배포 대상에 따라 Bicep 또는 Terraform 인프라 코드, azure.yaml 구성, Dockerfile을 생성합니다. 필수 계획 우선 워크플로우가 필요합니다: 작업 공간 분석, 요구 사항 수집, 레시피(AZD, AZCLI, Bicep 또는 Terraform) 선택, 아키텍처 설계, 사용자 승인 후에만 실행합니다. 새 앱 생성, 현대화, 업데이트를 다루며, 라우팅...
devopsapidevelopment
cf-cli
cloudflare
Cloudflare's official cf CLI (beta) for the public Cloudflare API and Workers projects. Use for finding and running Cloudflare commands from the terminal — sign-in and profiles, cf cli search, cf schema, cf deploy/dev/build, resource commands for DNS, zones, D1, KV, and R2 — and for choosing between cf and Wrangler in a project.
devopsapidevelopment
entra-agent-id
microsoft
Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals 및 인스턴스별 Agent Identities를 Microsoft Graph를 통해 프로비저닝하고, OAuth 2.0 토큰을 구성합니다…
apidevelopmentsecurity
entra-app-registration
microsoft
Microsoft Entra ID 앱 등록, OAuth 2.0 구성, MSAL 통합을 통한 안전한 애플리케이션 인증. 웹 앱, SPA, 모바일 앱, 데몬 서비스 전반의 앱 등록 설정, 인증 구성, API 권한, 클라이언트 자격 증명 관리를 다룹니다. 최초 등록, 콘솔 애플리케이션 인증, 서비스 간 자격 증명 흐름을 위한 단계별 워크플로를 포함합니다. Azure CLI 명령어, .NET용 MSAL 라이브러리 예제 등을 제공합니다.
apidevelopmentsecurity
expo-router
expo
프레임워크(오픈소스). Expo Router를 위한 내비게이션 및 라우팅. 파일 기반 라우트, 그룹 및 동적 라우트, 폴더 구성, 미리보기 및 컨텍스트 메뉴가 있는 Link, 네이티브 Stack, 페이지 제목, 모달 및 폼 시트, NativeTabs, 헤더 및 툴바, 헤더 검색 바를 다룹니다.
apidesigndevelopment
expo-upgrade
expo
프레임워크(OSS). Expo SDK 버전 업그레이드 및 의존성 문제 해결을 위한 가이드라인
apidevelopmenttesting