@genkit-ai/vercel-ai

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

A Genkit plugin providing a Vercel AI SDK ChatTransport for connecting useChat to Genkit Agents.

原始使用文档
文档目录14 节
  1. Installation
  2. Peer dependencies
  3. Quick start
  4. 1. Define a Genkit agent (server)
  5. 2. Connect from the client
  6. Works with AI Elements
  7. Entry points
  8. API
  9. GenkitChatTransport
  10. Interrupts (human-in-the-loop)
  11. Mapping utilities
  12. Features
  13. Requirements
  14. License

@genkit-ai/vercel-ai

A Genkit plugin that provides a Vercel AI SDK ChatTransport for connecting useChat to Genkit Agents.

Building with a coding agent? Install the Genkit JS skill first.

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

It teaches your agent the current Genkit JS APIs and common gotchas. Source, manual install and skills for other languages: genkit-ai/skills.

Use this plugin to build rich chat UIs in React (Next.js, Vite, etc.) that stream responses from Genkit agents — including multi-turn conversations, tool calls, and interrupt-based human-in-the-loop flows — with zero custom plumbing.

Installation

npm install @genkit-ai/vercel-ai

Peer dependencies

PackageRequiredNotes
genkit✅>=1.0.0 — the agent API used by this transport lives in the genkit/beta subpath.
ai✅^6.0.0 — provides ChatTransport, UIMessage, etc.
@ai-sdk/reactClient only^3.0.0 — only needed where you call the useChat hook (browser).

Note: @ai-sdk/react is not a declared peer dependency of this package because the server-side entry point does not require it. Install it yourself in any project that uses useChat.

Quick start

1. Define a Genkit agent (server)

// 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);

Or with Express:

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

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

2. Connect from the client

'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>
  );
}

That's it — text streaming, multi-turn history, tool calls, and interrupts all work out of the box.

Works with AI Elements

This transport is fully compatible with AI Elements — the component library and custom shadcn/ui registry for building AI-native applications. Since GenkitChatTransport implements the standard ChatTransport interface, all AI Elements components (Conversation, Message, Tool, PromptInput, etc.) work out of the box with Genkit agents.

'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>
  );
}

See the full working example in js/testapps/vercel-ai-elements which demonstrates multi-agent selection, tool call rendering, and interrupt-based human-in-the-loop approval flows — all powered by AI SDK Elements.

Entry points

Import pathEnvironmentContents
@genkit-ai/vercel-aiServer / sharedMapping utilities (mapUIMessageToGenkit, mapUIPartToGenkit, etc.) and re-exported UIMessage type
@genkit-ai/vercel-ai/clientBrowser / clientGenkitChatTransport class

The /client entry point is browser-safe and has no Node.js dependencies.

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
});

Configuration

OptionTypeDescription
urlstringRequired. URL of the Genkit agent endpoint.
headersRecord<string, string> | () => Record<string, string>Optional HTTP headers to include on every request. Accepts a static object or a function for dynamic values (e.g. auth tokens).

The useChat id must be a bare UUID. The transport sends the chat id to the agent as its Genkit sessionId, and the agent server requires session ids to be bare UUIDs. Generate one with crypto.randomUUID() and pass it to useChat({ id }). If you omit id, the AI SDK generates a non-UUID id and the transport will return an error.

import { useMemo } from 'react';

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

Server-managed session state

Conversation state is fully server-managed. The transport sends the chat id to the agent as a sessionId, and the agent persists per-session state in its configured SessionStore. Each turn automatically resumes the session's latest snapshot — there is no client-side snapshot bookkeeping to manage or persist, and nothing is lost on a page reload (the server holds the state).

To continue an existing conversation, simply reuse the same UUID id.

Restoring a conversation after a reload

Because state is server-managed, resuming the next turn requires nothing more than reusing the same UUID id. The only thing the client must rebuild is the rendered message list (useChat owns those, and they are not persisted by the transport).

Use messagesFromSnapshot to rebuild the visible messages from a Genkit SessionSnapshot (loaded via a /state flow keyed by the same 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 merges Genkit's separate tool request / tool response messages into single AI SDK tool parts (so each tool call renders as one element), maps reasoning and media parts, preserves part metadata, and emits any unresolved tool request (e.g. a pending interrupt) in the input-available state so the UI can still resolve it.

Tip: the sessionId you load the snapshot with must be the same UUID you pass as the useChat id, so the rendered messages and the server-side session stay in sync.

Regenerating a response

When the UI triggers a regeneration (the AI SDK sends trigger: 'regenerate-message'), the transport re-runs the last user message as a fresh turn against the current server-side session state. This produces a new answer to the same prompt. Because state is server-managed by sessionId, there is no client-side snapshot pointer to rewind to — the regenerated turn is appended to the session like any other turn.

How it works

  1. Sends messages via Genkit's streamFlow client — a browser-safe HTTP client that POSTs to the agent endpoint and reads the NDJSON streaming response.
  2. Transforms Genkit's AgentStreamChunk events into Vercel AI SDK UIMessageChunk events (text-delta, tool-input-available, tool-output-available, etc.).
  3. Sends the session id — the transport passes init: { sessionId: chatId } to the agent, which persists per-session state server-side and resumes the session's latest snapshot on each turn. No client-side snapshot tracking is needed.
  4. Handles interrupts — when an agent pauses for human input (via defineInterrupt), the transport surfaces the pending tool call to the UI. On the next sendMessages call the resolved tool results are detected directly from the message history, and the transport automatically sends a resume payload instead of a new message.

Interrupts (human-in-the-loop)

Genkit agents can pause mid-run to ask a human for input via defineInterrupt (or a tool that calls interrupt()). When this happens, the transport surfaces the paused tool call to useChat as a tool part in the input-available state. There are two ways to resolve it:

  1. Respond — supply the tool's output directly (the human's decision is the result). This is what a defineInterrupt tool expects.
  2. Restart — ask the agent to re-run the tool server-side, optionally attaching metadata. Useful for tools that interrupt() until confirmed and then compute a real result on resume (their resumed argument is set).

Both are driven by the AI SDK's native HITL primitives — addToolResult plus sendAutomaticallyWhen — so no manual setMessages/flushSync is needed:

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() }),
});

Note: Genkit interrupts map to the AI SDK's addToolResult flow, not the tool-approval flow (needsApproval / addToolApprovalResponse). A Genkit interrupt never executes server-side on its own — the value you pass to addToolResult is the resolution. Use restartInterrupt() when you want the agent to re-run the tool instead of accepting a supplied output.

See the full working example in js/testapps/vercel-ai-elements, which demonstrates both the approval (userApproval) and restart (getExchangeRate) flows.

Mapping utilities

The root entry point (@genkit-ai/vercel-ai) exports mapping functions between Vercel AI SDK UIMessage types and Genkit MessageData, plus helper functions used by the transport:

FunctionDirectionDescription
mapUIMessageToGenkit(msg)UI → GenkitConvert a Vercel UIMessage to a Genkit MessageData
mapUIPartToGenkit(part)UI → GenkitConvert a single UIMessagePart to Genkit Part[]
messagesFromSnapshot(msgs)Genkit → UIConvert a SessionSnapshot's state.messages into UIMessage[] for rehydrating useChat (pairs tool requests/responses, preserves metadata)
mapGenkitMessageToUI(msg)Genkit → UIConvert a single Genkit MessageData into a UIMessage
extractResolvedToolResults(msgs)—Extract resolved tool invocation results from the message array
findLastUserMessage(msgs)—Find the last user message in a UIMessage[]

Tool/part metadata is preserved in both directions: mapUIPartToGenkit carries a UI part's metadata onto the Genkit part, and messagesFromSnapshot carries a Genkit part's metadata back onto the UI part.

The UIMessage type is also re-exported from the ai package for convenience.

Features

  • Text streaming — streams token-by-token text deltas to the UI

  • Multi-turn conversations — automatic server-managed session continuity keyed by the useChat id (sessionId)

  • Tool calls — surfaces tool inputs and outputs as they happen

  • Interrupts (human-in-the-loop) — first-class support for defineInterrupt tools; pause and resume flows with user input

  • Custom headers — static or dynamic headers for authentication

  • Browser-safe — the /client entry point has no Node.js dependencies

  • Zero config — no ChatSessionStore needed on the client side

Requirements

  • Genkit >=1.0.0 — the agent API (defineAgent, streamFlow) used by this transport is exposed via the genkit/beta subpath of the main 1.x package.
  • Vercel AI SDK >=6.0.0 (for useChat with ChatTransport)
  • @ai-sdk/react >=3.0.0 (client-side, for the useChat hook)
  • Node.js >=20 (server-side)

License

Apache-2.0 — see LICENSE.

版本与发布记录

@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 是什么?

A Genkit plugin providing a Vercel AI SDK ChatTransport for connecting useChat to 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 和提交记录判断。