developing-genkit-js 用于在 Node.js/TypeScript 中构建 Genkit flow、AI agent、工具、Dotprompt、middleware 和生成式 UI。Genkit API 近期有破坏性变化，开始前先确认 CLI 至少为 1.29.0；如果涉及 beta agent，则需要 1.39.0，并从 `genkit/beta` 导入对应 API。
单次、无状态任务可以用 flow；对话、多轮、持久会话或助手场景应优先看 `defineAgent`。模型和 provider 要按项目需要选择，未指定时可从 Google AI 开始。提示词可放在 `.prompt` 文件，工具调用、重试、fallback、审批和 A2UI 则通过对应 middleware 或参考路径配置。
遇到任何 Genkit 错误，先读 `common-errors.md`，不要凭旧 API 经验修复。开发验证使用 `genkit flow:run` 或 `genkit start` 捕获 trace，不能只直接运行 Node 进程后凭感觉判断工具是否被调用。