ai-sdk-7

AI SDK 7 实现与迁移

将此技能用于 ai@7；使用 ai-sdk 解析未知版本，使用 ai-sdk-6 维护 v6。让 provider 和 UI 包版本与项目匹配。AI SDK 7 要求 Node.js 22+，且 AI SDK 包仅支持 ESM。

首先阅读已解析的 ai/docs/、provider 文档以及已安装的源码和类型； 此技能中的每个 ai-sdk.dev/docs/... 链接在 ai/docs/ 下都有离线副本 （路径映射见 ai-sdk）。Harness、WorkflowAgent 和迁移指南分别位于 ai/docs/03-ai-sdk-harnesses/、03-agents/07-workflow-agent.mdx 和 08-migration-guides/23-migration-guide-7-0.mdx；配套包仅提供类型定义。 本地文档不可用时，请使用官方文档或对应的仓库标签。 添加长期使用的封装之前，务必重新检查实验性包 API。

需求	入口
内存中的 Agent 循环	来自 ai 的 ToolLoopAgent
持久化 Agent	来自 @ai-sdk/workflow 的 WorkflowAgent + workflow 5
Claude Code/Codex/Pi 运行时	来自 @ai-sdk/harness/agent 的 HarnessAgent + 适配器 + 沙箱包
OpenTelemetry	registerTelemetry(new OpenTelemetry())、@ai-sdk/otel
调用停滞	timeout：毫秒数或 { totalMs, stepMs, firstChunkMs, chunkMs, toolMs }

重要边界

• 文本函数和 ToolLoopAgent 使用 instructions；循环限制使用 isStepCount。核心、Agent 和服务端 UI 流辅助函数使用 onEnd/onStepEnd （onFinish 仍是已弃用的别名）；客户端 useChat/Chat 保留 onFinish。
• prepareStep 的指令/消息覆盖会延续到后续步骤。usage 和工具数组等结果会汇总所有步骤； finalStep 保留访问最终步骤的能力，对于流式响应需要等待其完成。
• 服务端循环状态使用 runtimeContext，每个工具的状态使用经 schema 验证的 toolsContext。仅仅作为 context 并不会让其中任何一种状态对模型可见。
• ToolLoopAgent、WorkflowAgent、HarnessAgent 和 provider 执行的工具在审批、 持久化和生命周期方面各不相同。请根据实际的持久化/权限要求选择运行时。
• 从已配置的 provider 获取模型 ID 和能力。避免重叠设置推理参数：provider options 可以覆盖顶层的 reasoning。

核心形式

已使用 [email protected]、@ai-sdk/[email protected]、[email protected]、React 19 和 TypeScript 5.9 进行检查：运行 tsc --noEmit，并使用 mock 模型执行一次工具步骤 及后续回答。字符串形式的模型会通过 AI Gateway 解析。

// app/api/chat/route.ts
import { convertToModelMessages, createUIMessageStreamResponse, isStepCount, streamText, tool,
  toUIMessageStream, validateUIMessages, type InferUITools, type UIDataTypes, type UIMessage } from 'ai';
import { z } from 'zod';

const tools = {
  weather: tool({
    inputSchema: z.object({ city: z.string() }),
    execute: async ({ city }) => ({ city, celsius: 21 }),
  }),
};
export type ChatMessage = UIMessage<never, UIDataTypes, InferUITools<typeof tools>>;

export async function POST(req: Request) {
  const { messages } = await req.json();
  const uiMessages = await validateUIMessages<ChatMessage>({ messages, tools });
  const result = streamText({
    model: 'provider/model-id', // configured gateway ID, or a provider instance
    instructions: 'Answer briefly.',
    messages: await convertToModelMessages(uiMessages),
    tools,
    stopWhen: isStepCount(5),
  });
  return createUIMessageStreamResponse({ stream: toUIMessageStream({ stream: result.stream }) });
}

// app/page.tsx
'use client';
import { useChat } from '@ai-sdk/react';
import { DefaultChatTransport } from 'ai';
import type { ChatMessage } from './api/chat/route';

const transport = new DefaultChatTransport<ChatMessage>({ api: '/api/chat' });

export default function Chat() {
  const { messages, sendMessage, status } = useChat<ChatMessage>({ transport });
  return (
    <form action={(form) => void sendMessage({ text: String(form.get('text')) })}>
      {messages.map((m) => <div key={m.id}>{m.parts.map((part, i) =>
        part.type === 'text' ? <p key={i}>{part.text}</p>
        : part.type === 'tool-weather' && part.state === 'output-available'
          ? <p key={i}>{part.output.city}: {part.output.celsius} °C</p> : null)}</div>)}
      <input name="text" disabled={status === 'submitted' || status === 'streaming'} />
    </form>
  );
}

v6 的写法（system、stepCountIs、result.toUIMessageStreamResponse()） 在 7.0.124 中仍可编译；system 和该响应方法已弃用。

根据功能阅读

• Agents：内存/持久化执行与上下文。
• Harnesses：由运行时管理的会话与权限。
• 核心函数：输出、流和结果约定。
• 工具：审批边界、MCP Apps 和沙箱句柄。
• UI hooks：UI 流、审批和恢复。
• 迁移：语义变更和 codemod。
• 遥测：注册和数据控制。
• 媒体/文件：provider 引用和能力门控。
• 示例：当前的官方实现。

对变更过的多轮、工具、流或恢复路径进行类型检查和测试。 成功编译并不能证明审批策略或持久化行为正确。