OpenAI Responses API Conversations

OpenAI Responses API Conversations 提供 Mastra Agent 作为 Responses API 时的对话管理功能。它提供用于在 Mastra 中创建、检索、删除和查看基于 thread 的对话的方法。

此 API 是 OpenAI Responses API 的后续配套功能。存储的 Responses 调用会返回 conversation_id；在 Mastra 中，该值就是原始 memory threadId。需要直接操作该 thread 时，请使用 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)

需要查看或管理已存储的 thread 时，请使用 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 创建新的对话 thread。

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

返回： Promise<Conversation>。

retrieve(conversationId, requestContext?)

通过 thread ID 检索对话。

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

console.log(conversation.thread)

返回： Promise<Conversation>。

delete(conversationId, requestContext?)

通过 thread 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：原始 thread ID
• object：始终为 'conversation'
• thread：存储的 thread 记录

delete() 返回：

• id：原始 thread 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

必填。拥有对话 memory 的已注册 Mastra Agent。

conversation_id?:

string

可选。用作原始 thread ID 的对话 ID。

resource_id?:

string

可选。与对话 thread 关联的资源 ID。

title?:

string

可选。与对话一起存储的 thread 标题。

metadata?:

Record<string, unknown>

可选。与对话一起存储的 thread 元数据。

requestContext?:

RequestContext | Record<string, any>

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