OpenAI Responses API Conversations

OpenAI Responses API Conversations 以 Responses API 的形式提供 Mastra Agent 的對話管理功能。你可透過當中的方法，在 Mastra 建立、取得、刪除及查看以執行緒為基礎的對話。

此 API 延伸自 OpenAI Responses API。已儲存的 Responses 呼叫會傳回 conversation_id；在 Mastra 中，此值是原始記憶 threadId。如要直接操作該執行緒，請使用 client.conversations。

此 API 目前屬實驗性功能。

與 OpenAI Responses 的關係

使用 OpenAI Responses API 產生及延續內容：

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

console.log(response.conversation_id)

如要查看或管理已儲存的執行緒，請使用 Conversations API：

const conversation = await client.conversations.retrieve(response.conversation_id!)
const items = await client.conversations.items.list(response.conversation_id!)

使用範例

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

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

const conversation = await client.conversations.create({
  agent_id: 'support-agent',
})

console.log(conversation.id)

方法

生命週期

create(params)

為所選 Agent 建立新的對話執行緒。

const conversation = await client.conversations.create({
  agent_id: 'support-agent',
  title: 'Billing support',
})

傳回： Promise<Conversation>。

retrieve(conversationId, requestContext?)

按執行緒 ID 取得對話。

const conversation = await client.conversations.retrieve('thread_123')

console.log(conversation.thread)

傳回： Promise<Conversation>。

delete(conversationId, requestContext?)

按執行緒 ID 刪除對話。

const deleted = await client.conversations.delete('thread_123')

console.log(deleted.deleted)

傳回： Promise<ConversationDeleted>。

項目

items.list(conversationId, requestContext?)

列出對話中已儲存的項目。

const items = await client.conversations.items.list('thread_123')

console.log(items.data)

傳回： Promise<ConversationItemsPage>。

回應結構

create() 及 retrieve() 會傳回包含下列內容的對話物件：

• id：原始執行緒 ID
• object：值一律為 'conversation'
• thread：已儲存的執行緒記錄

delete() 會傳回：

• id：原始執行緒 ID
• object：值一律為 'conversation.deleted'
• deleted：值一律為 true

items.list() 會傳回：

• object：值一律為 'list'
• data：對話項目，例如 message、function_call 及 function_call_output
• first_id：頁面中第一個項目的 ID
• last_id：頁面中最後一個項目的 ID
• has_more：目前頁面之後是否還有更多項目

參數

agent_id:

string

必填。擁有對話記憶的已註冊 Mastra Agent。

conversation_id?:

string

可選。用作原始執行緒 ID 的對話 ID。

resource_id?:

string

可選。要與對話執行緒關聯的資源 ID。

title?:

string

可選。連同對話儲存的執行緒標題。

metadata?:

Record<string, unknown>

可選。連同對話儲存的執行緒中繼資料。

requestContext?:

RequestContext | Record<string, any>

可選。轉送至 Mastra 伺服器的請求上下文。