> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Agent.streamLegacy()（旧版）

> **注意:** **已弃用**：此方法已弃用，并且只适用于 V1 模型。V2 模型请改用新的 [`.stream()`](https://mastra.zisheng.pro/reference/streaming/agents/stream) 方法。升级详情请参阅[迁移指南](https://mastra.zisheng.pro/guides/migrations/vnext-to-standard-apis)。

`.streamLegacy()` 是旧版 Agent Stream API，用于即时Stream V1 模型 Agent 的回应。此方法接受讯息及选用的Stream选项。

## 使用范例

```typescript
await agent.streamLegacy('message for agent')
```

## 参数

**messages** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): 要传送给 Agent 的讯息。可以是单一字符串、字符串阵列或结构化讯息对象。

**options** (`AgentStreamOptions<OUTPUT, EXPERIMENTAL_OUTPUT>`): Stream处理进程的选用设定。

**options.abortSignal** (`AbortSignal`): 可让你中止 Agent 执行的讯号对象。讯号中止后，所有进行中的操作都会终止。

**options.context** (`CoreMessage[]`): 提供给 Agent 的额外内容脉络讯息。

**options.experimental\_output** (`Zod schema | JsonSchema7`): 启用结构化输出，并同时产生文本及进行 Tool 调用。模型产生的回应会符合所提供的 schema。

**options.instructions** (`string`): 自订指示，覆盖 Agent 针对这次产生作业使用的预设指示。适合用于动态修改 Agent 行为，而毋须创建新的 Agent 实例。

**options.output** (`Zod schema | JsonSchema7`): 定义预期的输出结构。可以是 JSON Schema 对象或 Zod schema。

**options.memory** (`object`): 记忆体设定。这是管理记忆体的建议方式。

**options.memory.thread** (`string | { id: string; metadata?: Record<string, any>, title?: string }`): 对话 thread，可以是字符串 ID，或包含 id 及选用 metadata 的对象。

**options.memory.resource** (`string`): 与 thread 关联的用户或资源标识符。

**options.memory.options** (`MemoryConfig`): 记忆体行为的设定，例如讯息记录及语意回忆。

**options.maxSteps** (`number`): 允许的最大执行步骤数。

**options.maxRetries** (`number`): 最大重试次数。设为 0 可停用重试。

**options.memoryOptions** (`MemoryConfig`): \*\*已弃用。\*\* 请改用 memory.options。记忆体管理的设定选项。

**options.memoryOptions.lastMessages** (`number | false`): 要加入内容脉络的近期讯息数量；设为 false 可停用。

**options.memoryOptions.semanticRecall** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): 启用语意回忆以寻找相关的过往讯息。可以是布尔值或详细设定。

**options.memoryOptions.workingMemory** (`WorkingMemory`): 工作记忆功能的设定。

**options.memoryOptions.threads** (`{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }`): Thread 专用设定，包括自动产生标题。

**options.onFinish** (`StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>`): Stream完成时调用的回呼函数，会接收最终结果。

**options.onStepFinish** (`StreamTextOnStepFinishCallback<any> | never`): 每个执行步骤完成后调用的回呼函数，会以 JSON 字符串接收步骤详情。不适用于结构化输出。

**options.resourceId** (`string`): \*\*已弃用。\*\* 请改用 memory.resource。与 Agent 互动的用户或资源标识符。如有提供 threadId，亦必须提供此值。

**options.telemetry** (`TelemetrySettings`): Stream期间收集遥测资料的设定。

**options.telemetry.isEnabled** (`boolean`): 启用或停用遥测。实验阶段预设为停用。

**options.telemetry.recordInputs** (`boolean`): 启用或停用输入记录。预设为启用；你可停用输入记录，以免记录敏感资料。

**options.telemetry.recordOutputs** (`boolean`): 启用或停用输出记录。预设为启用；你可停用输出记录，以免记录敏感资料。

**options.telemetry.functionId** (`string`): 此函数的标识符，用于按函数分组遥测资料。

**options.temperature** (`number`): 控制模型输出的随机程度。较高的值（例如 0.8）令输出更随机；较低的值（例如 0.2）令输出更聚焦且更具确定性。

**options.threadId** (`string`): \*\*已弃用。\*\* 请改用 memory.thread。对话 thread 的标识符，可在多次互动之间保留内容脉络。如有提供 resourceId，亦必须提供此值。

**options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): 控制 Agent 在Stream期间如何使用 Tool。

**options.toolChoice.'auto'** (`string`): 由模型决定是否使用 Tool（预设）。

**options.toolChoice.'none'** (`string`): 不使用任何 Tool。

**options.toolChoice.'required'** (`string`): 要求模型使用最少一个 Tool。

**options.toolChoice.{ type: 'tool'; toolName: string }** (`object`): 要求模型使用指定名称的 Tool。

**options.toolsets** (`ToolsetsInput`): Stream期间供 Agent 使用的额外 Toolset。

**options.clientTools** (`ToolsInput`): 在请求的 'client' 端执行的 Tool。这些 Tool 的定义不包含 execute 函数。

**options.hooks** (`ToolHooks`): 每次执行专用的 hook，会在 Tool 调用前后运行，并在这次执行中覆盖相符的 Agent 层级 hook。beforeToolCall 可传回 { proceed: false, output } 以略过 Tool 调用。

**options.savePerStep** (`boolean`): 每个Stream步骤完成后逐步储存讯息（预设：false）。

**options.providerOptions** (`Record<string, Record<string, JSONValue>>`): 传递至底层 LLM Provider 的额外 Provider 专用选项。结构为 { providerName: { optionKey: value } }。例如：{ openai: { reasoningEffort: 'high' }, anthropic: { maxTokens: 1000 } }。

**options.providerOptions.openai** (`Record<string, JSONValue>`): OpenAI 专用选项。例如：{ reasoningEffort: 'high' }

**options.providerOptions.anthropic** (`Record<string, JSONValue>`): Anthropic 专用选项。例如：{ maxTokens: 1000 }

**options.providerOptions.google** (`Record<string, JSONValue>`): Google 专用选项。例如：{ safetySettings: \[...] }

**options.providerOptions.\[providerName]** (`Record<string, JSONValue>`): 其他 Provider 专用选项。键是 Provider 名称，值是 Provider 专用选项的记录。

**options.runId** (`string`): 这次产生作业的唯一 ID，适合用于追踪及除错。

**options.requestContext** (`RequestContext`): 用于依赖注入及内容脉络资料的 Request Context。

**options.maxTokens** (`number`): 要产生的最大 token 数量。

**options.topP** (`number`): 内核取样。值介乎 0 至 1；建议设定 temperature 或 topP 其中一项，而非同时设定两者。

**options.topK** (`number`): 每个后续 token 只从排名最高的 K 个选项取样，用于排除属于「长尾」的低概率回应。

**options.presencePenalty** (`number`): 存在惩罚设定，影响模型重复提示中既有资料的可能性。值介乎 -1（增加重复）至 1（最大惩罚，减少重复）。

**options.frequencyPenalty** (`number`): 频率惩罚设定，影响模型重复使用相同字词或片语的可能性。值介乎 -1（增加重复）至 1（最大惩罚，减少重复）。

**options.stopSequences** (`string[]`): 停止串行。如有设定，模型产生其中一个停止串行时便会停止产生文本。

**options.seed** (`number`): 用于随机取样的种子（整数）。如有设定且模型支持，调用会产生确定性结果。

**options.headers** (`Record<string, string | undefined>`): 随请求传送的额外 HTTP header。只适用于以 HTTP 为基础的 Provider。

## 传回值

**textStream** (`AsyncGenerator<string>`): 异步产生器，在文本区块可用时逐一产生。

**fullStream** (`Promise<ReadableStream>`): 解析为完整回应 ReadableStream 的 Promise。

**text** (`Promise<string>`): 解析为完整文本回应的 Promise。

**usage** (`Promise<{ totalTokens: number; promptTokens: number; completionTokens: number }>`): 解析为 token 使用量资料的 Promise。

**finishReason** (`Promise<string>`): 解析为Stream结束原因的 Promise。

**toolCalls** (`Promise<Array<ToolCall>>`): 解析为Stream期间所作 Tool 调用的 Promise。

**toolCalls.toolName** (`string`): 所调用 Tool 的名称。

**toolCalls.args** (`any`): 传递给 Tool 的引数。

## 进阶使用范例

```typescript
await agent.streamLegacy('message for agent', {
  temperature: 0.7,
  maxSteps: 3,
  memory: {
    thread: 'user-123',
    resource: 'test-app',
  },
  toolChoice: 'auto',
})
```

## 迁移至新 API

> **信息:** 新的 `.stream()` 方法提供更强的功能，包括 AI SDK v5+ 兼容性、更完善的结构化输出处理，以及改良的回呼系统。详细迁移指示请参阅[迁移指南](https://mastra.zisheng.pro/guides/migrations/vnext-to-standard-apis)。

### 快速迁移范例

#### 迁移前（旧版）

```typescript
const result = await agent.streamLegacy('message', {
  temperature: 0.7,
  maxSteps: 3,
  onFinish: result => console.log(result),
})
```

#### 迁移后（新 API）

```typescript
const result = await agent.stream('message', {
  modelSettings: {
    temperature: 0.7,
  },
  maxSteps: 3,
  onFinish: result => console.log(result),
})
```

## 相关内容

- [迁移指南](https://mastra.zisheng.pro/guides/migrations/vnext-to-standard-apis)
- [新的 .stream() 方法](https://mastra.zisheng.pro/reference/streaming/agents/stream)
- [产生回应](https://mastra.zisheng.pro/docs/agents/overview)
- [Stream回应](https://mastra.zisheng.pro/docs/agents/overview)