尧图网站建设 
AI SDK 7 实战指南基于skills/use-ai-sdk的版本对齐、AI Gateway 接入与 Agent 构建全流程【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai本篇指南以仓库内skills/use-ai-sdk/SKILL.md为骨架系统讲解 AI SDKai包的正确打开方式如何不依赖记忆、以随包文档为准绳进行开发如何通过 Vercel AI Gateway 一条 API 接入多家模型如何用ToolLoopAgent等内建抽象构建 Agent 并实现端到端类型安全以及 DevTools 调试、版本管理与类型检查等工程化细节。读完你将掌握一套查证驱动的 AI SDK 实战方法论可直接应用于本仓库中 examples 目录下的各类示例应用。一、AI SDK 是什么AI SDKnpm 上的ai包是面向 TypeScript 生态的 AI 应用开发工具包。它屏蔽了不同模型提供商的差异为文本生成、结构化输出、工具调用tool calling、Agent、Embedding 以及框架级 UI 集成提供统一 API。从当前仓库的入口文件可以直观看到它的能力版图。packages/ai/src/index.ts 将整个 SDK 按目录导出涵盖agentAgent 抽象如ToolLoopAgentgenerate-text/stream-textgenerateText/streamText文本生成与流式输出generate-object结构化输出embed/rerank向量嵌入与重排序generate-image/generate-video/generate-speech/transcribe/translate多模态能力ui/ui-message-stream框架无关的 UI 消息流middleware/telemetry/registry中间件、遥测与模型注册表。此外ai包还从ai-sdk/gateway、ai-sdk/provider-utils透传了createGateway、gateway、tool、zodSchema、jsonSchema等核心构造器见 packages/ai/src/index.ts。在仓库中与ai包配套的还有ai-sdk/openai、ai-sdk/anthropic、ai-sdk/google等数十个提供商包见 packages 目录以及ai-sdk/react、ai-sdk/svelte、ai-sdk/vue等框架包。二、铁律永远不要凭记忆写 AI SDK 代码SKILL.md 中最核心的一条方法论是你所记忆的 AI SDK 知识几乎必然是过时的。这个 SDK 跨版本演进极快——API 被重命名、移除、新增。训练数据中很可能包含已废弃的 API、过时模式和不存在的模型 ID。其中useChat等 UI Hooks 是变动最频繁的 API 之一写客户端代码时尤其要小心。因此绝不凭记忆编写 AI SDK 代码。写任何 API、选项、模式之前都必须对照项目里实际安装版本的文档与源码进行核实。这条原则在本仓库同样成立仓库根目录的 CHANGELOG.md 与 packages/ai/CHANGELOG.md 记录了频繁的 API 演进packages/ai/package.json中当前版本为7.0.97任何外部记忆都可能与该版本不符。三、使用随包附带、与版本匹配的文档ai包在发布时会把完整文档和源码打进包里node_modules/ai/docs/与node_modules/ai/src/。这些内容始终与已安装版本精确匹配因此优先级高于任何记忆。使用流程如下确认ai已安装。如果node_modules/ai/不存在只用项目包管理器安装ai包本身如pnpm add ai。之后按任务需要再安装提供商包如ai-sdk/openai和框架包如ai-sdk/react——保持按需安装避免无关依赖干扰版本匹配。阅读并检索随包文档与源码文档在node_modules/ai/docs/源码在node_modules/ai/src/。提供商包与框架包同样自带文档node_modules/ai-sdk/name/docs/。若随包文档中没有答案再检索在线文档站任何文档页 URL 后追加.md即可获得 Markdown 版本也可用其搜索接口检索。如果文档和源码中都找不到答案明确说出来不要猜。在本仓库monorepo中上述随包文档的源就位于 content/docs含03-ai-sdk-core、04-ai-sdk-ui、07-reference、08-migration-guides等目录。ai包的构建脚本也印证了这一点packages/ai/package.json 中的prepack脚本执行cp -r ../../content/docs ./docs把仓库内文档复制进包里随 npm 发布。也就是说本仓库的 content/docs 就是你开发时版本匹配文档的上游来源。四、AI Gateway最快的起步方式Vercel AI Gateway 是开始使用 AI SDK 的最快路径。它通过单一 API提供 OpenAI、Anthropic、Google 等多家提供商的模型无需逐个安装提供商包也无需管理多把 API Key。4.1 接入步骤通过 OIDC 认证适用于 Vercel 部署环境或获取 AI Gateway API Key通过环境变量AI_GATEWAY_API_KEY提供给应用使用provider/model字符串引用模型例如anthropic/claude-...、openai/gpt-...。环境变量名在仓库源码中有明确依据packages/gateway/src/errors/gateway-authentication-error.ts 的错误提示写明通过apiKey选项或AI_GATEWAY_API_KEY环境变量提供 API Key 或 Vercel 访问令牌。Gateway 提供商的完整实现可参见 packages/gateway/src/gateway-provider.ts 与 packages/gateway/src/gateway-language-model.ts。ai包通过 packages/ai/src/index.ts 直接导出createGateway与gateway即开即用。4.2 选择模型永远先拉取最新模型列表模型发布与下架非常频繁绝不要用记忆中的模型 ID 写代码。写引用模型的代码前先获取当前模型列表。SKILL.md 给出的命令如下注意不要用head之类截断列表以免漏掉最新模型# 列出所有可用模型 curl -s https://ai-gateway.vercel.sh/v1/models | jq -r .data[].id # 按提供商过滤如 anthropic、openai、google curl -s https://ai-gateway.vercel.sh/v1/models | jq -r [.data[] | select(.id | startswith(anthropic/)) | .id] | reverse | .[]当同一模型存在多个版本时优先选择版本号最高的那个。五、构建与消费 Agent5.1 优先使用内建 Agent 抽象构建带工具循环的 Agent 时应优先使用 SDK 内建的 Agent 抽象如ToolLoopAgent而不是手写工具调用循环。ToolLoopAgent的实现在 packages/ai/src/agent/tool-loop-agent.ts其类注释精确描述了循环语义工具循环 Agent 在每个步骤中调用 LLM若返回工具调用则执行工具并在新步骤中把工具结果回传给 LLM。循环持续直到满足以下任一条件返回的推理结束原因不是 tool-calls被调用的工具没有execute函数工具调用需要通过toolApproval或工具级needsApproval审批达到停止条件默认停止条件是isStepCount(20)。其配置项定义在 packages/ai/src/agent/tool-loop-agent-settings.ts常用关键配置包括配置项说明默认值model使用的语言模型必填—instructionsAgent 指令可为字符串或带 provider options 的SystemModelMessage—allowSystemInMessages是否允许在prompt/messages中携带 system 消息关闭时系统消息只能走instructionsfalsetoolChoice工具选择策略autostopWhen最后一步含工具结果时的停止条件可传数组任一满足即停isStepCount(20)activeTools限制模型可调用的工具子集而不改变结果的工具类型—toolOrder控制工具定义发送给提供商的顺序有助于保持工具定义顺序稳定、改善提供商侧缓存—output结构化输出规格—runtimeContext运行时上下文应视为不可变变更请在prepareStep中完成—toolApproval工具审批配置优先级高于工具自身定义的审批设置—repairToolCall修复解析失败工具调用的函数—prepareStep为每一步提供不同设置的函数—onStart/onStepStart/onToolExecutionStart/onToolExecutionEnd/onStepEnd/onEnd各阶段生命周期回调—providerOptions透传给提供商的额外选项—include控制步骤结果中携带的数据如请求/响应体关闭可降低大 payload如图片场景的内存占用默认包含请求与响应体排除请求消息注意源码中以experimental_开头或已标记deprecated的别名如experimental_telemetry、experimental_onStart、experimental_repairToolCall、onStepFinish、onFinish在后续大版本中会被移除新代码应使用正式命名。5.2 消费 Agent端到端类型安全Agent 在客户端被消费时要做到端到端类型安全从 Agent 定义推断 UI 消息类型例如配合useChat使用。仓库中对应实现为 packages/ai/src/agent/infer-agent-ui-message.ts配套测试见 packages/ai/src/agent/infer-agent-ui-message.test-d.ts。React 侧useChat的泛型签名在 packages/react/src/use-chat.ts 中它接受UI_MESSAGE泛型并返回类型化的messages数组packages/react/src/use-chat.ts。消费 Agent 是框架相关的先查看项目的package.json判断技术栈再按对应框架的 quickstart 接入。本仓库 examples 目录提供了多框架参考实现例如examples/ai-e2e-nextNext.js Agent 全流程示例examples/harness-e2e-nextHarness 端到端示例examples/harness-e2e-tui终端 TUI Agent 示例examples/next 等基础文本生成示例。当前最新的 Agent、工具与类型安全 API 的权威说明以随包文档node_modules/ai/docs/尤其 agents 章节为准其上游即仓库的 content/docs/03-agents 与 content/docs/03-ai-sdk-harnesses。六、DevTools开发期调试利器AI SDK DevTools 会捕获你的 AI SDK 调用——请求、响应、工具调用、Token 用量以及多步运行过程——让你精确查看 Agent 每一步做了什么适合在开发阶段调试生成结果。使用要点它是独立的包本仓库对应 packages/devtools含 packages/devtools/src 的实现与 packages/devtools/examples 示例仅用于本地开发不应部署到生产环境安装与接入方式以其随包文档为准对应源码 packages/devtools/src 中可查阅具体 API 形态。七、保持 SDK 版本最新过时的安装是 AI SDK 报错的最常见来源。开发时应对比已安装版本与最新版本已安装版本查看node_modules/ai/package.json的version字段最新版本运行npm view ai version查询。如果已安装版本落后最新版本一个主版本或更多应明确告知用户当前处于旧版本并建议先升级再继续开发。迁移指南对应仓库中的 content/docs/08-migration-guides本仓库还提供了专门的迁移技能 skills/migrate-ai-sdk-v6-to-v7。仓库根目录 CHANGELOG.md 汇总了全部变更记录是核对版本差异的第一手资料。八、修改代码之后跑类型检查最小化配置完成代码修改后必须运行项目的类型检查器。实践中注意两点配置保持最小化——只设置与默认值不同的选项。判断默认值时先查文档或源码而不是凭记忆过度指定。例如ToolLoopAgent的stopWhen默认是isStepCount(20)packages/ai/src/agent/tool-loop-agent-settings.tsallowSystemInMessages默认false同文件 packages/ai/src/agent/tool-loop-agent-settings.ts——如果你要的就是默认行为就无需显式传入。绝大多数类型错误来自记忆中的、已变更的 API。遇到类型错误时回头重新核对当前文档与源码而不是试图用as之类的断言强行绕过。本仓库的ai包自带完整的类型检查与测试脚本见 packages/ai/package.jsontype-check执行tsc --buildtest同时跑 Node 与 Edge 环境的 vitest。在你的业务项目中运行相应框架的类型检查命令如tsc --noEmit即可。九、总结一份可复用的 AI SDK 工作流把 SKILL.md 的方法论落成日常开发工作流先装包按需安装ai再按任务补装ai-sdk/provider与ai-sdk/framework后查证优先检索node_modules/ai/docs/与node_modules/ai/src/上游即本仓库 content/docs 与 packages/ai/src其次才检索在线文档找不到就明确说不支持/未知接入模型优先走 AI GatewayAI_GATEWAY_API_KEYprovider/model模型 ID 一律先拉取/v1/models列表确认构建能力文本生成用generateText/streamText结构化输出用generateObjectAgent 用ToolLoopAgent客户端消费配合useChat推断 UI 消息类型以获得端到端类型安全调试与维护开发期用 DevTools 观察请求、工具调用与 Token 用量定期用npm view ai version对比已装版本落后主版本时提示升级并参考迁移指南收尾验证跑类型检查配置只设与默认不同的值遇到类型错误回到文档重新核对。这套工作流的核心不是记住某个 API 的写法而是建立一条以版本匹配文档为准绳、以源码为证据的查证链路——这正是 AI SDK 这类快速演进库的生存之道。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AI SDK 7 实战指南：基于 `skills/use-ai-sdk` 的版本对齐、AI Gateway 接入与 Agent 构建全流程
AI SDK 7 实战指南基于skills/use-ai-sdk的版本对齐、AI Gateway 接入与 Agent 构建全流程【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai本篇指南以仓库内skills/use-ai-sdk/SKILL.md为骨架系统讲解 AI SDKai包的正确打开方式如何不依赖记忆、以随包文档为准绳进行开发如何通过 Vercel AI Gateway 一条 API 接入多家模型如何用ToolLoopAgent等内建抽象构建 Agent 并实现端到端类型安全以及 DevTools 调试、版本管理与类型检查等工程化细节。读完你将掌握一套查证驱动的 AI SDK 实战方法论可直接应用于本仓库中 examples 目录下的各类示例应用。一、AI SDK 是什么AI SDKnpm 上的ai包是面向 TypeScript 生态的 AI 应用开发工具包。它屏蔽了不同模型提供商的差异为文本生成、结构化输出、工具调用tool calling、Agent、Embedding 以及框架级 UI 集成提供统一 API。从当前仓库的入口文件可以直观看到它的能力版图。packages/ai/src/index.ts 将整个 SDK 按目录导出涵盖agentAgent 抽象如ToolLoopAgentgenerate-text/stream-textgenerateText/streamText文本生成与流式输出generate-object结构化输出embed/rerank向量嵌入与重排序generate-image/generate-video/generate-speech/transcribe/translate多模态能力ui/ui-message-stream框架无关的 UI 消息流middleware/telemetry/registry中间件、遥测与模型注册表。此外ai包还从ai-sdk/gateway、ai-sdk/provider-utils透传了createGateway、gateway、tool、zodSchema、jsonSchema等核心构造器见 packages/ai/src/index.ts。在仓库中与ai包配套的还有ai-sdk/openai、ai-sdk/anthropic、ai-sdk/google等数十个提供商包见 packages 目录以及ai-sdk/react、ai-sdk/svelte、ai-sdk/vue等框架包。二、铁律永远不要凭记忆写 AI SDK 代码SKILL.md 中最核心的一条方法论是你所记忆的 AI SDK 知识几乎必然是过时的。这个 SDK 跨版本演进极快——API 被重命名、移除、新增。训练数据中很可能包含已废弃的 API、过时模式和不存在的模型 ID。其中useChat等 UI Hooks 是变动最频繁的 API 之一写客户端代码时尤其要小心。因此绝不凭记忆编写 AI SDK 代码。写任何 API、选项、模式之前都必须对照项目里实际安装版本的文档与源码进行核实。这条原则在本仓库同样成立仓库根目录的 CHANGELOG.md 与 packages/ai/CHANGELOG.md 记录了频繁的 API 演进packages/ai/package.json中当前版本为7.0.97任何外部记忆都可能与该版本不符。三、使用随包附带、与版本匹配的文档ai包在发布时会把完整文档和源码打进包里node_modules/ai/docs/与node_modules/ai/src/。这些内容始终与已安装版本精确匹配因此优先级高于任何记忆。使用流程如下确认ai已安装。如果node_modules/ai/不存在只用项目包管理器安装ai包本身如pnpm add ai。之后按任务需要再安装提供商包如ai-sdk/openai和框架包如ai-sdk/react——保持按需安装避免无关依赖干扰版本匹配。阅读并检索随包文档与源码文档在node_modules/ai/docs/源码在node_modules/ai/src/。提供商包与框架包同样自带文档node_modules/ai-sdk/name/docs/。若随包文档中没有答案再检索在线文档站任何文档页 URL 后追加.md即可获得 Markdown 版本也可用其搜索接口检索。如果文档和源码中都找不到答案明确说出来不要猜。在本仓库monorepo中上述随包文档的源就位于 content/docs含03-ai-sdk-core、04-ai-sdk-ui、07-reference、08-migration-guides等目录。ai包的构建脚本也印证了这一点packages/ai/package.json 中的prepack脚本执行cp -r ../../content/docs ./docs把仓库内文档复制进包里随 npm 发布。也就是说本仓库的 content/docs 就是你开发时版本匹配文档的上游来源。四、AI Gateway最快的起步方式Vercel AI Gateway 是开始使用 AI SDK 的最快路径。它通过单一 API提供 OpenAI、Anthropic、Google 等多家提供商的模型无需逐个安装提供商包也无需管理多把 API Key。4.1 接入步骤通过 OIDC 认证适用于 Vercel 部署环境或获取 AI Gateway API Key通过环境变量AI_GATEWAY_API_KEY提供给应用使用provider/model字符串引用模型例如anthropic/claude-...、openai/gpt-...。环境变量名在仓库源码中有明确依据packages/gateway/src/errors/gateway-authentication-error.ts 的错误提示写明通过apiKey选项或AI_GATEWAY_API_KEY环境变量提供 API Key 或 Vercel 访问令牌。Gateway 提供商的完整实现可参见 packages/gateway/src/gateway-provider.ts 与 packages/gateway/src/gateway-language-model.ts。ai包通过 packages/ai/src/index.ts 直接导出createGateway与gateway即开即用。4.2 选择模型永远先拉取最新模型列表模型发布与下架非常频繁绝不要用记忆中的模型 ID 写代码。写引用模型的代码前先获取当前模型列表。SKILL.md 给出的命令如下注意不要用head之类截断列表以免漏掉最新模型# 列出所有可用模型 curl -s https://ai-gateway.vercel.sh/v1/models | jq -r .data[].id # 按提供商过滤如 anthropic、openai、google curl -s https://ai-gateway.vercel.sh/v1/models | jq -r [.data[] | select(.id | startswith(anthropic/)) | .id] | reverse | .[]当同一模型存在多个版本时优先选择版本号最高的那个。五、构建与消费 Agent5.1 优先使用内建 Agent 抽象构建带工具循环的 Agent 时应优先使用 SDK 内建的 Agent 抽象如ToolLoopAgent而不是手写工具调用循环。ToolLoopAgent的实现在 packages/ai/src/agent/tool-loop-agent.ts其类注释精确描述了循环语义工具循环 Agent 在每个步骤中调用 LLM若返回工具调用则执行工具并在新步骤中把工具结果回传给 LLM。循环持续直到满足以下任一条件返回的推理结束原因不是 tool-calls被调用的工具没有execute函数工具调用需要通过toolApproval或工具级needsApproval审批达到停止条件默认停止条件是isStepCount(20)。其配置项定义在 packages/ai/src/agent/tool-loop-agent-settings.ts常用关键配置包括配置项说明默认值model使用的语言模型必填—instructionsAgent 指令可为字符串或带 provider options 的SystemModelMessage—allowSystemInMessages是否允许在prompt/messages中携带 system 消息关闭时系统消息只能走instructionsfalsetoolChoice工具选择策略autostopWhen最后一步含工具结果时的停止条件可传数组任一满足即停isStepCount(20)activeTools限制模型可调用的工具子集而不改变结果的工具类型—toolOrder控制工具定义发送给提供商的顺序有助于保持工具定义顺序稳定、改善提供商侧缓存—output结构化输出规格—runtimeContext运行时上下文应视为不可变变更请在prepareStep中完成—toolApproval工具审批配置优先级高于工具自身定义的审批设置—repairToolCall修复解析失败工具调用的函数—prepareStep为每一步提供不同设置的函数—onStart/onStepStart/onToolExecutionStart/onToolExecutionEnd/onStepEnd/onEnd各阶段生命周期回调—providerOptions透传给提供商的额外选项—include控制步骤结果中携带的数据如请求/响应体关闭可降低大 payload如图片场景的内存占用默认包含请求与响应体排除请求消息注意源码中以experimental_开头或已标记deprecated的别名如experimental_telemetry、experimental_onStart、experimental_repairToolCall、onStepFinish、onFinish在后续大版本中会被移除新代码应使用正式命名。5.2 消费 Agent端到端类型安全Agent 在客户端被消费时要做到端到端类型安全从 Agent 定义推断 UI 消息类型例如配合useChat使用。仓库中对应实现为 packages/ai/src/agent/infer-agent-ui-message.ts配套测试见 packages/ai/src/agent/infer-agent-ui-message.test-d.ts。React 侧useChat的泛型签名在 packages/react/src/use-chat.ts 中它接受UI_MESSAGE泛型并返回类型化的messages数组packages/react/src/use-chat.ts。消费 Agent 是框架相关的先查看项目的package.json判断技术栈再按对应框架的 quickstart 接入。本仓库 examples 目录提供了多框架参考实现例如examples/ai-e2e-nextNext.js Agent 全流程示例examples/harness-e2e-nextHarness 端到端示例examples/harness-e2e-tui终端 TUI Agent 示例examples/next 等基础文本生成示例。当前最新的 Agent、工具与类型安全 API 的权威说明以随包文档node_modules/ai/docs/尤其 agents 章节为准其上游即仓库的 content/docs/03-agents 与 content/docs/03-ai-sdk-harnesses。六、DevTools开发期调试利器AI SDK DevTools 会捕获你的 AI SDK 调用——请求、响应、工具调用、Token 用量以及多步运行过程——让你精确查看 Agent 每一步做了什么适合在开发阶段调试生成结果。使用要点它是独立的包本仓库对应 packages/devtools含 packages/devtools/src 的实现与 packages/devtools/examples 示例仅用于本地开发不应部署到生产环境安装与接入方式以其随包文档为准对应源码 packages/devtools/src 中可查阅具体 API 形态。七、保持 SDK 版本最新过时的安装是 AI SDK 报错的最常见来源。开发时应对比已安装版本与最新版本已安装版本查看node_modules/ai/package.json的version字段最新版本运行npm view ai version查询。如果已安装版本落后最新版本一个主版本或更多应明确告知用户当前处于旧版本并建议先升级再继续开发。迁移指南对应仓库中的 content/docs/08-migration-guides本仓库还提供了专门的迁移技能 skills/migrate-ai-sdk-v6-to-v7。仓库根目录 CHANGELOG.md 汇总了全部变更记录是核对版本差异的第一手资料。八、修改代码之后跑类型检查最小化配置完成代码修改后必须运行项目的类型检查器。实践中注意两点配置保持最小化——只设置与默认值不同的选项。判断默认值时先查文档或源码而不是凭记忆过度指定。例如ToolLoopAgent的stopWhen默认是isStepCount(20)packages/ai/src/agent/tool-loop-agent-settings.tsallowSystemInMessages默认false同文件 packages/ai/src/agent/tool-loop-agent-settings.ts——如果你要的就是默认行为就无需显式传入。绝大多数类型错误来自记忆中的、已变更的 API。遇到类型错误时回头重新核对当前文档与源码而不是试图用as之类的断言强行绕过。本仓库的ai包自带完整的类型检查与测试脚本见 packages/ai/package.jsontype-check执行tsc --buildtest同时跑 Node 与 Edge 环境的 vitest。在你的业务项目中运行相应框架的类型检查命令如tsc --noEmit即可。九、总结一份可复用的 AI SDK 工作流把 SKILL.md 的方法论落成日常开发工作流先装包按需安装ai再按任务补装ai-sdk/provider与ai-sdk/framework后查证优先检索node_modules/ai/docs/与node_modules/ai/src/上游即本仓库 content/docs 与 packages/ai/src其次才检索在线文档找不到就明确说不支持/未知接入模型优先走 AI GatewayAI_GATEWAY_API_KEYprovider/model模型 ID 一律先拉取/v1/models列表确认构建能力文本生成用generateText/streamText结构化输出用generateObjectAgent 用ToolLoopAgent客户端消费配合useChat推断 UI 消息类型以获得端到端类型安全调试与维护开发期用 DevTools 观察请求、工具调用与 Token 用量定期用npm view ai version对比已装版本落后主版本时提示升级并参考迁移指南收尾验证跑类型检查配置只设与默认不同的值遇到类型错误回到文档重新核对。这套工作流的核心不是记住某个 API 的写法而是建立一条以版本匹配文档为准绳、以源码为证据的查证链路——这正是 AI SDK 这类快速演进库的生存之道。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考