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 事件以取得部分參數 chunk；對於最終確定的參數 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 伺服器的請求情境。