用 Google Genkit Agents API 搭全栈 AI Agent（状态持久化 + 产物 + 流式）

Genkit 是 Node 优先的框架，先确认你有 Node 20+，然后新建项目并装包：

# 新建目录并初始化
mkdir my-genkit-agent && cd my-genkit-agent
npm init -y

# 安装 Genkit 核心 + Google AI 插件（用 Gemini 当大脑）
npm install genkit @genkit-ai/ai @genkit-ai/googleai

# 可选：装 CLI 方便本地调试
npm install -D genkit-cli

下面是一个最小可跑的 Agent：它维护一段对话历史，能多轮回答。关键就是 agent.chat() 返回的会话对象可以一直复用。

import { genkit } from 'genkit';
import { googleAI } from '@genkit-ai/googleai';

const ai = genkit({ plugins: [googleAI()] });

// 定义一个最简单的 Agent
const agent = ai.defineAgent(
  { name: 'helper', model: googleAI.model('gemini-2.5-flash') },
  async (input) => {
    return `收到：${input.prompt}`;
  }
);

// 发起一轮对话
const session = agent.chat();
const r1 = await session.send('帮我规划一次三天两晚的上海出差');
console.log(r1.text);

光能聊没用，得让它能查实时数据。我们加一个「查天气」工具：

const getWeather = ai.defineTool(
  { name: 'getWeather', description: '查询某城市天气',
    inputSchema: z.object({ city: z.string() }) },
  async ({ city }) => {
    // 这里换成你真实的天气 API
    return { city, tempC: 28, condition: '晴' };
  }
);

const agent = ai.defineAgent(
  { name: 'tripPlanner', model: googleAI.model('gemini-2.5-flash'),
    tools: [getWeather] },
  async (input) => input.prompt
);

这是 Genkit 最实用的设计：工具可以在当前会话里更新「状态」或「产物」，客户端实时收到变更。

const saveItinerary = ai.defineTool(
  { name: 'saveItinerary',
    description: '把行程存成可下载的产物',
    inputSchema: z.object({ markdown: z.string() }) },
  async ({ markdown }, ctx) => {
    // 产物：用户能单独下载/版本管理
    ctx.artifacts.set('itinerary', { content: markdown });
    return { ok: true };
  }
);

// 同时在多轮中维护「已选城市」状态
// ctx.state.set('selectedCity', '上海')

Genkit 提供两种持久化方案，二选一：

// 方案 A：服务端管理（推荐生产多实例）
// 内置 Firestore（生产）/ 内存（开发）/ 文件（本地测试）
const ai = genkit({
  plugins: [googleAI()],
  sessionStore: { kind: 'file', path: './sessions' }
});
// 客户端用 sessionId 重新连接，自动还原历史+状态+产物

// 方案 B：客户端管理（适合有数据驻留要求的场景）
// 不配存储，服务端每次返回完整状态，客户端回传
// 代价：会话变长后网络负载会增加

用 sendStream 替代 send，前端就能像打字机一样收到增量内容，连状态/产物变更也实时推送：

const { stream, response } = session.sendStream('把行程细化成每天安排');

// 前端：边收边渲染
for await (const chunk of stream) {
  render(chunk.text);   // 增量文本
}
const final = await response;  // 最终完整结果

Genkit 的精髓：本地和线上是同一个 Agent 对象，不用为部署重写逻辑。

# 本地用开发者 UI 调试（带可视化 trace）
npx genkit start

# 部署到 Cloud Run / 任意 Node 服务
# 用 genkit/express 暴露 HTTP 端点
import { expressHandler } from 'genkit/express';
app.post('/agent/chat', expressHandler(agent));