OpenAI Responses API

这个与 OpenAI 兼容、由 Agent 支持的接口可让你将 Mastra Agent 用作 Responses API。它提供通过 Mastra Agent 创建、检索、流式传输和删除响应的方法。

这些路由是在 Mastra Agent、memory 和存储之上的 Agent 支持型适配器。使用 agent_id 选择应处理请求的 Mastra Agent。你可以传入 model，为单次请求覆盖 Agent 配置的模型；也可以省略它，使用 Agent 上已配置的模型。

存储的响应还会返回 conversation_id。在 Mastra 中，它就是原始 memory threadId。

此 API 目前处于实验阶段。

使用示例

import { MastraClient } from '@mastra/client-js'

const client = new MastraClient({
  baseUrl: 'http://localhost:4111',
})

const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Summarize this ticket',
  store: true,
})

console.log(response.output_text)

方法

生命周期

create(params)

创建响应。

const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Summarize this ticket',
})

当省略 stream 或其值为 false 时，返回： Promise<ResponsesResponse>。

当 stream: true 时，create() 返回 SSE 风格事件 payload 的异步可迭代对象：

const stream = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Summarize this ticket',
  stream: true,
})

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta)
  }
}

流式响应也可以包含 Tool 事件。Tool 调用流使用 response.output_item.added、response.function_call_arguments.delta、response.function_call_arguments.done 和 response.output_item.done 事件。Tool 结果以 function_call_output 条目出现，ID 为 <toolCallId>:output。

返回： Promise<ResponsesStream>。

retrieve(responseId, requestContext?)

检索存储的响应。

const response = await client.responses.retrieve('msg_123')

返回： Promise<ResponsesResponse>。

delete(responseId, requestContext?)

删除存储的响应。

const deleted = await client.responses.delete('msg_123')

返回： Promise<{ id: string; object: "response"; deleted: true }>

stream(params)

创建流式响应。

const stream = await client.responses.stream({
  agent_id: 'support-agent',
  input: 'Say hello',
})

for await (const event of stream) {
  console.log(event.type)
}

返回： Promise<ResponsesStream>。

存储的响应和对话

存储的响应同时包含 response.id 和 conversation_id。

• response.id 是响应 ID。对于存储的 Agent 支持型响应，它是持久化的 assistant 消息 ID。
• conversation_id 是原始 Mastra thread ID。

需要从之前存储的响应继续时，请使用 previous_response_id。需要直接指定已知 thread 时，请使用 conversation_id。

const first = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Start a support thread',
  store: true,
})

const second = await client.responses.create({
  agent_id: 'support-agent',
  conversation_id: first.conversation_id!,
  input: 'Add a follow-up to the same thread',
  store: true,
})

需要直接创建、检索、删除或查看底层 OpenAI Responses API 对话时，请使用 client.conversations。

函数调用（Tool）

response.tools 包含可用于该请求的已配置函数定义。

如果模型调用函数，该活动会与最终的 assistant message 一起，以 function_call 和 function_call_output 条目的形式包含在 response.output 中。

当 stream: true 时，函数调用也会作为 Responses 流事件发出。读取 response.function_call_arguments.delta 事件以获取部分参数分块；对于最终确定的参数 payload 和 Tool 名称，应优先使用 response.function_call_arguments.done。读取 response.output_item.done 事件以获取已完成的 function_call 和 function_call_output 条目。Tool 输出条目使用 <toolCallId>:output ID。

结构化输出

需要 JSON 输出时，请使用 text.format。

• json_object 启用 JSON 模式。
• json_schema 启用受 schema 约束的结构化输出。

两种格式都会在 assistant 消息内容中返回 JSON。需要严格执行 schema 时，请使用 json_schema；只需要有效的 JSON 输出时，请使用 json_object。

const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Return a structured support ticket summary.',
  text: {
    format: {
      type: 'json_schema',
      name: 'ticket_summary',
      schema: {
        type: 'object',
        properties: {
          summary: { type: 'string' },
          priority: { type: 'string' },
        },
        required: ['summary', 'priority'],
        additionalProperties: false,
      },
    },
  },
})

Provider 支持型请求

需要使用 Mastra 未在 Responses 层标准化的 Provider 特定选项时，请使用 providerOptions。

const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Continue this exchange',
  providerOptions: {
    openai: {
      previousResponseId: 'resp_123',
    },
  },
})

响应结构

返回的响应对象包含：

• id：响应 ID
• output：输出条目，例如 assistant message、function_call 和 function_call_output
• output_text：拼接 assistant 文本输出的便捷 getter
• tools：为请求配置的 Tool 定义
• conversation_id：存储响应的原始 thread ID
• text：请求的文本输出格式（如果提供）

参数

agent_id?:

string

初始请求必填。选择执行请求的 Mastra Agent。使用 previous_response_id 继续存储的后续轮次时，可以省略此项。

model?:

string

可选。覆盖此请求所用的模型，例如 openai/gpt-5。如果省略，Mastra 将使用所选 Agent 上配置的模型。

input:

string | Array<{ role: 'system' | 'developer' | 'user' | 'assistant'; content: string | Array<{ type: 'input_text' | 'text' | 'output_text'; text: string }> }>

必填。响应的输入文本或消息数组。

instructions?:

string

可选。覆盖此请求的指令。

text?:

{ format: { type: 'json_object' } | { type: 'json_schema'; name: string; schema: Record<string, unknown>; description?: string; strict?: boolean } }

可选。文本输出格式。使用 json_object 启用 JSON 模式，或使用 json_schema 启用受 schema 约束的结构化输出。

providerOptions?:

Record<string, Record<string, unknown> | undefined>

可选。传递给底层模型调用的 Provider 特定选项。

stream?:

boolean

为 true 时，返回 Responses API 事件的异步可迭代对象。

store?:

boolean

为 true 时，通过所选 Agent 的 memory 持久化响应。

conversation_id?:

string

可选。对话标识符。在 Mastra 中，它是原始 memory thread ID。

previous_response_id?:

string

从之前存储的响应继续已存储的响应链。

requestContext?:

RequestContext | Record<string, any>

可选。转发到 Mastra 服务器的请求上下文。