@genkit-ai/vercel-ai

中文文档
0.7.0发布于 2026/11/04Apache-2.0TypeScriptESM + CJS零依赖近 30 天下载 2401

一个提供 Vercel AI SDK Chat Transport 的 Genkit 插件,用于连接使用 Chat 到 Genkit Agents .

中文使用文档
文档目录14 节
  1. 安装
  2. 同伴依赖关系
  3. 快开始
  4. 1. 界定基因组代理人(服务器)
  5. 2. 从客户端连接
  6. 与AI元素有关的工作
  7. 入境点
  8. API 密码
  9. GenkitChatTransport
  10. 间断( 人- 在- 在- 在- 有)
  11. 测绘公用事业
  12. 特征
  13. 所需资源
  14. 许可证

@genkit-ai/vercel-ai (英语)

A 类 精灵 提供插件 维塞尔 AI SDK ChatTransport 用于连接 useChat 给源基特特工.

用编码代理? 先安装基因组JS技能.

npx skills add genkit-ai/skills --skill developing-genkit-js

它教你的代理人 现任Genkit JS APIs 和普通的gitchas. 其他语言的来源、人工安装和技能: 技能/技能。 。 。 .

使用此插件在 React (Next.js, Vite等) 中构建丰富的聊天 UI 源基特代理商的流回,包括多回合对话, 工具调用,以及基于中断的 " 人行 " 流动——零 定制管道.

安装

npm install @genkit-ai/vercel-ai

同伴依赖关系

软件包需求页:1
genkit✅>=1.0.0 - 运输所使用的API剂生活在 genkit/beta 子路径.
ai✅^6.0.0 - 提供 ChatTransport, (中文(简体) ), UIMessage等 (中文(简体) ).
@ai-sdk/react仅限客户^3.0.0 - 只需要你打电话给我 useChat 钩 (眉生.

说明: @ai-sdk/react 此软件包不是宣布的对等依赖 因为服务器边入口并不需要它。 安装它 在任何项目中使用 useChat。 。 。 .

快开始

1. 界定基因组代理人(服务器)

// app/api/chat/weather/route.ts  (Next.js App Router example)
import { appRoute } from '@genkit-ai/next';
import { genkit } from 'genkit/beta';
import { googleAI } from '@genkit-ai/google-genai';

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

const weatherAgent = ai.defineAgent({
  name: 'weatherAgent',
  model: 'googleai/gemini-flash-latest',
  tools: [/* your tools here */],
});

export const POST = appRoute(weatherAgent);

或有快报:

import { expressHandler } from '@genkit-ai/express';
import express from 'express';

const app = express();
app.post('/api/chat/weather', expressHandler(weatherAgent));
app.listen(3000);

2. 从客户端连接

'use client';
import { useChat } from '@ai-sdk/react';
import { GenkitChatTransport } from '@genkit-ai/vercel-ai/client';
import { useMemo } from 'react';

export default function Chat() {
  const transport = useMemo(
    () => new GenkitChatTransport({ url: '/api/chat/weather' }),
    []
  );
  // The `useChat` `id` is sent to the agent as its `sessionId`; it must be a UUID.
  const chatId = useMemo(() => crypto.randomUUID(), []);

  const { messages, input, handleInputChange, handleSubmit, status } =
    useChat({ id: chatId, transport });


  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          <strong>{m.role}:</strong>{' '}
          {m.parts
            .filter((p) => p.type === 'text')
            .map((p) => p.text)
            .join('')}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
        <button type="submit" disabled={status !== 'ready'}>
          Send
        </button>
      </form>
    </div>
  );
}

就是这样,文本流,多回转的历史,工具呼叫,和中断 都从盒子里出来.

与AI元素有关的工作

这种运输完全兼容 AI 要素 - 组成部分图书馆和 自定义 阴影/ ui 建筑物登记簿 应用。 自兹 GenkitChatTransport 执行标准 ChatTransport 界面,所有 AI 元素组件 (Conversation, (中文(简体) ), Message, (中文(简体) ), Tool, (中文(简体) ), PromptInput) 和源基特一起在盒子里工作 探员.

'use client';
import { useChat } from '@ai-sdk/react';
import { GenkitChatTransport } from '@genkit-ai/vercel-ai/client';
import { useMemo } from 'react';

import {
  Conversation, ConversationContent, ConversationScrollButton,
} from '@/components/ai-elements/conversation';
import { Message, MessageContent, MessageResponse } from '@/components/ai-elements/message';
import {
  PromptInput, PromptInputTextarea, PromptInputFooter, PromptInputSubmit,
} from '@/components/ai-elements/prompt-input';
import { Tool, ToolHeader, ToolContent, ToolInput, ToolOutput } from '@/components/ai-elements/tool';

export default function Chat() {
  const transport = useMemo(
    () => new GenkitChatTransport({ url: '/api/chat/weather' }),
    []
  );
  // The `useChat` `id` is sent to the agent as its `sessionId`; it must be a UUID.
  const chatId = useMemo(() => crypto.randomUUID(), []);
  const { messages, status, sendMessage } = useChat({ id: chatId, transport });


  return (
    <Conversation>
      <ConversationContent>
        {messages.map((message) => (
          <Message key={message.id} from={message.role}>
            <MessageContent>
              {message.parts.map((part, i) => {
                if (part.type === 'text' && part.text) {
                  return <MessageResponse key={i}>{part.text}</MessageResponse>;
                }
                if (part.type.startsWith('tool-')) {
                  const toolPart = part as any;
                  return (
                    <Tool key={i}>
                      <ToolHeader type={toolPart.type} state={toolPart.state} />
                      <ToolContent>
                        <ToolInput input={toolPart.input} />
                        <ToolOutput output={toolPart.output} />
                      </ToolContent>
                    </Tool>
                  );
                }
                return null;
              })}
            </MessageContent>
          </Message>
        ))}
      </ConversationContent>
      <ConversationScrollButton />
      <PromptInput onSubmit={(msg) => sendMessage({ text: msg.text })}>
        <PromptInputTextarea placeholder="Message..." />
        <PromptInputFooter>
          <div />
          <PromptInputSubmit status={status} />
        </PromptInputFooter>
      </PromptInput>
    </Conversation>
  );
}

参看以下文件的完整实例: js/testapps/vercel-ai-elements 哪个 演示多代理选择、工具调用渲染和中断 人-入-入-入-入-入-入-入-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出-出:出-出-出-出-出-出-出-出-出:出:出:出:出-出:出:出:出:出:出:出:出-出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出:出.

入境点

导入路径环境目录
@genkit-ai/vercel-ai服务器/ 共享测绘公用事业(mapUIMessageToGenkit, (中文(简体) ), mapUIPartToGenkit)和再出口 UIMessage 类型
@genkit-ai/vercel-ai/client浏览器/ 客户端GenkitChatTransport 类

这个 /client 入站点为浏览器安全并具有Node.js的依赖性.

API 密码

GenkitChatTransport

import { GenkitChatTransport } from '@genkit-ai/vercel-ai/client';

const transport = new GenkitChatTransport({
  url: '/api/chat/weather',
  headers: { Authorization: 'Bearer token' },         // static headers
  // headers: () => ({ Authorization: `Bearer ${getToken()}` }),  // or dynamic
});

配置

选项类型说明
urlstring要求. 源基特代理端点的 URL.
headersRecord<string, string> | () => Record<string, string>在每个请求中包含可选的 HTTP 信头 。 接受一个静态对象或动态值的函数(如认证符).

这个 useChat id 必须是裸体UUID. 传送器发送聊天 id 以特务身份 sessionId,并且代理服务器需要 会话 ID 要裸露 UUID 。 生成一个 crypto.randomUUID() 财务报告和审定财务报表 传过来 useChat({ id })。如果省略 id,AI SDK生成一个 非UUID ID, 传输会返回一个错误.

import { useMemo } from 'react';

const chatId = useMemo(() => crypto.randomUUID(), []);
const { messages, sendMessage } = useChat({ id: chatId, transport });

服务器管理的会话状态

对话状态是 完全服务器管理。传输发送聊天 id 作为代理人 sessionId,并且该代理人在 它的配置 SessionStore自动恢复会话 最近的情况——有 没有客户端快照簿记 管理或 持续,在页面重新装入(服务器持有状态)时不会丢失任何内容 .

要继续现有的对话,只需重新使用同样的UUID id。 。 。 .

重新装入后恢复对话

因为状态是服务器管理的,恢复 下一个 转身不需要更多了 而不是重用同一个UUID id客户端必须重建的唯一东西就是 已执行 信件列表( e)useChat 拥有这些,他们不是坚持的 运输.

使用 messagesFromSnapshot 以重建来自 Genkit 的可见信件 SessionSnapshot (通过一个 /state 由相同键入的流 sessionId:

import { useChat } from '@ai-sdk/react';
import { GenkitChatTransport } from '@genkit-ai/vercel-ai/client';
import { messagesFromSnapshot } from '@genkit-ai/vercel-ai';
import { runFlow } from 'genkit/beta/client';
import { useEffect, useMemo, useState } from 'react';

export default function RestoredChat({ sessionId }: { sessionId: string }) {
  const transport = useMemo(() => new GenkitChatTransport({ url: '/api/chat/weather' }), []);
  const [initialMessages, setInitialMessages] = useState([]);

  useEffect(() => {
    (async () => {
      // Load the latest snapshot for this session (returns a SessionSnapshot).
      const snapshot = await runFlow({ url: '/api/chat/weather/state', input: sessionId });
      // Rebuild the visible message list from the snapshot.
      setInitialMessages(messagesFromSnapshot(snapshot.state.messages));
    })();
  }, [sessionId]);

  // Reuse the same UUID `id` so the next turn resumes the server-side session.
  const { messages, sendMessage } = useChat({ id: sessionId, transport, messages: initialMessages });
  // ...render messages, send new turns — continuity is preserved.
}

messagesFromSnapshot 合并 Genkit 的单独工具请求/ 工具响应 消息输入单个的 AI SDK 工具部件( 所以每个工具调用都变成一个) 元素),地图 reasoning 财务报告和审定财务报表 media 部分,保留部分 metadata,以及 发出任何未解决的工具请求(例如待决中断) input-available 说好UI还能解决.

提示 : 页:1 sessionId 装入快照时必须是相同的UUID 通过为 useChat id,所以已发送的消息和服务器侧 会话保持同步 .

重新生成响应

当UI触发再生时(AI SDK发送) trigger: 'regenerate-message'),运输重运行最后一个用户消息 作为 新转弯 相对于当前服务器侧会话状态。 这个 生成对同一提示的新答案。 因为状态是由服务器管理的 sessionId,没有客户端快照指针可以倒转到 与任何其他回合一样,重新生成的回合附在届会后.

如何运作

  1. 发送信件 通过源基特 streamFlow 客户端 — 一个浏览器安全 HTTP pOST 到代理端点并读取 NDJSON 流线的客户端 反应.
  2. 变换 元吉的书 AgentStreamChunk 事件进入 Vercel AI SDK UIMessageChunk 活动(text-delta, (中文(简体) ), tool-input-available, (中文(简体) ), tool-output-available(见a/c.5/49/70,附件).
  3. 发送会话 ID - 运输通行证 init: { sessionId: chatId } 并恢复 每个回合的会话最新快照。 没有客户端快照跟踪 需要帮助.
  4. 处理中断 ——当代理人暂停人输入时(通过 defineInterrupt),运输会浮出等待的工具呼叫UI. 接下来 sendMessages 调用已解析的工具结果 直接从消息历史中发送,传输自动发送 resume 有效载荷而非新消息 .

间断( 人- 在- 在- 在- 有)

精灵特工可以 暂停 中途通过 defineInterrupt (或呼叫的工具) interrupt()) (中文(简体) ). 当这种情况发生时, 显示已暂停的工具调用 useChat 作为工具在 页:1 input-available 状态。 解决这个问题有两种方法:

  1. 响应 ——直接提供工具的输出(人类的决定) 实值 (结果)。 这才是 defineInterrupt 工具预期.
  2. 重新开始 - 要求经纪人 重新运行 工具服务器侧,可选 附加元数据。 用于工具 interrupt() 直到确认和 然后在恢复时计算一个实际结果 resumed 参数已设置).

两者都由AI SDK的原生HITL原始人所驱动—— addToolResult 加号 sendAutomaticallyWhen - 所以没有手动 setMessages编号 :flushSync 需要:

import { useChat } from '@ai-sdk/react';
import {
  GenkitChatTransport,
  restartInterrupt,
} from '@genkit-ai/vercel-ai/client';
import { lastAssistantMessageIsCompleteWithToolCalls } from 'ai';

const { messages, addToolResult } = useChat({
  transport: new GenkitChatTransport({ url: '/api/chat/banking' }),
  // Auto-resume once every paused tool call has a result.
  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
});

// 1. Respond: provide the tool output (resume.respond).
addToolResult({
  tool: 'userApproval',
  toolCallId,
  output: { approved: true, feedback: 'Looks good' },
});

// 2. Restart: re-run the tool (resume.restart). The metadata becomes the
//    tool's `resumed` argument server-side.
addToolResult({
  tool: 'getExchangeRate',
  toolCallId,
  output: restartInterrupt({ confirmedAt: Date.now() }),
});

说明: Genkit打断了 AI SDK的地图 addToolResult 流动, 没有 那个工具..核准 流动(needsApproval 编号 : addToolApprovalResponseA级 Genkit 中断从不执行服务器侧面 —— 您通过的价值 改为 addToolResult 实值 决议 使用 restartInterrupt() 当你 想要代理重新运行工具, 而不是接受所提供的输出 .

参看以下文件的完整实例: js/testapps/vercel-ai-elements,哪个 证明两项批准(userApproval)并重新启动(getExchangeRate(中文(简体) ) 流动.

测绘公用事业

根入点( E)@genkit-ai/vercel-ai) 出口绘图功能 在 Vercel AI SDK 之间 UIMessage 类型和基因组 MessageData附加时 运输所使用的辅助函数 :

函数方向说明
mapUIMessageToGenkit(msg)UI – 源基特语Name转换 Vercel UIMessage 给基因组 MessageData
mapUIPartToGenkit(part)UI – 源基特语Name转换单个 UIMessagePart 给源基特 Part[]
messagesFromSnapshot(msgs)Genkit – UI (英语)转换 a SessionSnapshot是因为 state.messages 输入 UIMessage[] 用于再水 useChat (传真工具请求/答复,保存元数据)
mapGenkitMessageToUI(msg)Genkit – UI (英语)转换单个源基特 MessageData 改为 a UIMessage
extractResolvedToolResults(msgs)—— 说从信件数组提取已解析的工具引用结果
findLastUserMessage(msgs)—— 说在 a 中查找最后一个用户消息 UIMessage[]

工具/部分元数据双向保存: mapUIPartToGenkit 带UI部分 metadata 进入基因组部分,以及 messagesFromSnapshot 带了玄基的 metadata 回到UI部分.

这个 UIMessage 类型也从 ai 为方便而包装.

特征

  • 文本流 – 串流符号逐个输入的文本三角洲到 UI

  • 多回合对话 自动服务器管理的会话连续性按键 useChat id (单位:千美元)sessionId(中文(简体) )

  • 工具调用 ——当工具投入和产出出现时表面

  • 间断( 人- 在- 在- 在- 有) ——头等舱支援 defineInterrupt 工具; 通过用户输入暂停并恢复流量

  • 自定义信头 ——用于认证的静态或动态信头

  • 浏览器安全 - 那个 /client 切入点没有节点.js依赖性

  • 零配置 没有 ChatSessionStore 客户端需要

所需资源

  • 精灵 >=1.0.0 - 代理人API(defineAgent, (中文(简体) ), streamFlow用于此 运输通过 genkit/beta 主子路径 1.x 软件包.
  • 维塞尔 AI SDK >=6.0.0 (计: useChat 与 ChatTransport(中文(简体) )
  • @ai-sdk/react >=3.0.0 (客户方,用于 useChat 钩子)
  • 节点.js >=20 (服务器侧)

许可证

阿帕奇-2.0 — 见 自由主义。 。 。 .

版本与发布记录

@genkit-ai/vercel-ai 共发布 15 个版本,首次发布于 2026/06/25;过去 12 个月发布了 15 个版本。

版本发布日期距今
0.7.0latest2026/11/0412 天前
0.6.02026/10/2225 天前
0.6.0-rc.3next2026/10/2225 天前
0.6.0-rc.22026/10/2126 天前
0.6.0-rc.12026/10/091 个月前
0.6.0-rc.02026/10/091 个月前

关于 @genkit-ai/vercel-ai 的常见问题

@genkit-ai/vercel-ai 是什么?

一个提供 Vercel AI SDK Chat Transport 的 Genkit 插件,用于连接使用 Chat 到 Genkit Agents .

如何安装 @genkit-ai/vercel-ai?

在项目目录运行 npm install @genkit-ai/vercel-ai,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:ai(^6.0.0)、genkit(^1.44.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@genkit-ai/vercel-ai 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@genkit-ai/vercel-ai 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@genkit-ai/vercel-ai 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@genkit-ai/vercel-ai 可以商用吗?

@genkit-ai/vercel-ai 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@genkit-ai/vercel-ai 的下载量有多少?

根据 npm 官方下载统计,@genkit-ai/vercel-ai 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,401 次,日均约 80 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@genkit-ai/vercel-ai 还在维护吗?

最新版本 0.7.0 发布于 2026/11/04(12 天前);至今共发布 15 个版本,其中过去 12 个月发布了 15 个;首次发布于 2026/06/25。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。