ai-sdk-core-v7

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: ai-sdk-core

Scope

适用范围

Applies to: Backend AI with Vercel AI SDK v7 (
```
ai
```
package)
Does NOT cover: React chat UIs (see ai-sdk-ui)

适用场景：使用Vercel AI SDK v7（
```
ai
```
包）开发后端AI
不包含内容：React聊天UI（详见ai-sdk-ui）

Assumptions

前提假设

Folder major tracks the installed
```
ai
```
package in
```
package.json
```
, not a skill-file revision
Node.js 22+, ESM; Zod 4 for
```
inputSchema
```
Never write AI SDK from memory. Grep
```
node_modules/ai/docs/
```
and
```
node_modules/ai/src/
```
for the installed version. Else https://ai-sdk.dev/docs (append
```
.md
```
) or https://ai-sdk.dev/api/search-docs?q=
v6 leftovers: https://ai-sdk.dev/docs/migration-guides/migration-guide-7-0

文件夹版本以
```
package.json
```
中安装的
```
ai
```
包版本为准，而非技能文件修订版本
Node.js 22+，ESM；使用Zod 4定义
```
inputSchema
```
切勿凭记忆编写AI SDK代码。请在
```
node_modules/ai/docs/
```
和
```
node_modules/ai/src/
```
中搜索已安装版本的相关内容。否则可访问https://ai-sdk.dev/docs（追加`.md`）或https://ai-sdk.dev/api/search-docs?q=
v6迁移遗留内容：https://ai-sdk.dev/docs/migration-guides/migration-guide-7-0

Principles

核心原则

```
generateText
```
/
```
streamText
```
for request handlers and one-shot API routes;
```
instructions
```
for system-style prompt

Request-handler tool loops:

stopWhen: isStepCount(n)

generateText

streamText

— not

maxSteps

, not

stepCountIs

```
ToolLoopAgent
```
+
```
generate()
```
/
```
stream()
```
for durable agents — not hand-rolled loops, not
```
new Agent()
```
UI streams:
```
createUIMessageStreamResponse
```
+
```
toUIMessageStream({ stream: result.stream })
```
from
```
'ai'
```
. Use these for new handlers and for dedicated stream/SDK updates
```
result.toUIMessageStreamResponse()
```
still works in v7 (deprecated). Leave it only when the task is unrelated to streaming or the SDK
Tool results must be JSON-serializable (no
```
Date
```
)
System prompt lives in
```
instructions
```
. Client
```
messages
```
must not include
```
{ role: 'system' }
```
unless the server fully trusts the payload

在请求处理器和一次性API路由中使用
```
generateText
```
/
```
streamText
```
；使用
```
instructions
```
定义系统风格提示词

请求处理器工具循环：在

generateText

streamText

上使用

stopWhen: isStepCount(n)

— 不要使用

maxSteps

或

stepCountIs

构建持久化Agent使用
```
ToolLoopAgent
```
+
```
generate()
```
/
```
stream()
```
— 不要手动编写循环，也不要使用
```
new Agent()
```
UI流处理：从
```
'ai'
```
包中使用
```
createUIMessageStreamResponse
```
+
```
toUIMessageStream({ stream: result.stream })
```
。新处理器和专用流/SDK更新均需使用这些方法
```
result.toUIMessageStreamResponse()
```
在v7中仍可使用（已废弃）。仅当任务与流处理或SDK无关时才保留该写法
工具返回结果必须可JSON序列化（不能包含
```
Date
```
类型）
系统提示词需放在
```
instructions
```
中。客户端
```
messages
```
中不得包含
```
{ role: 'system' }
```
，除非服务器完全信任该负载

Constraints

约束条件

MUST

必须遵守

Read bundled docs before writing calls
```
convertToModelMessages
```
when the client sends UI messages
Reject untrusted
```
{ role: 'system' }
```
in
```
messages
```
. Do not set
```
allowSystemInMessages: true
```
for client-supplied chat

编写调用代码前先阅读捆绑文档
当客户端发送UI消息时，使用
```
convertToModelMessages
```
进行转换
拒绝客户端消息中不可信的
```
{ role: 'system' }
```
。对于客户端提供的聊天内容，请勿设置
```
allowSystemInMessages: true
```

AVOID

需避免

toDataStreamResponse

pipeDataStreamToResponse

stepCountIs

maxSteps

result.fullStream

/ top-level

system:

(use

isStepCount

result.stream

instructions

)

Guessing model IDs

使用

toDataStreamResponse

pipeDataStreamToResponse

使用

stepCountIs

maxSteps

result.fullStream

/ 顶层

system:

（请使用

isStepCount

、

result.stream

、

instructions

）

猜测模型ID

Interactions

关联内容

Complements ai-sdk-ui, fastify, next
Upstream: vercel/ai use-ai-sdk

补充内容：ai-sdk-ui、fastify、next
上游文档：vercel/ai use-ai-sdk

Templates

模板

generate-text-basic.ts
stream-text-chat.ts
agent-with-tools.ts

generate-text-basic.ts
stream-text-chat.ts
agent-with-tools.ts

References

参考资料

Request handlers — tools +
```
isStepCount
```
, Fastify SSE, system-message reject

Request handlers — 工具 +
```
isStepCount
```
、Fastify SSE、系统消息拦截