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

# OpenAI Responses API Conversations

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

此 API 是 [OpenAI Responses API](https://mastra.zisheng.pro/reference/client-js/responses) 的后续配套功能。存储的 Responses 调用会返回 `conversation_id`；在 Mastra 中，该值就是原始 memory `threadId`。需要直接操作该 thread 时，请使用 `client.conversations`。

此 API 目前处于实验阶段。

## 与 OpenAI Responses 的关系

使用 OpenAI Responses API 生成和续写内容：

```typescript
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：

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

## 使用示例

```typescript
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。

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

**返回：** `Promise<Conversation>`。

#### `retrieve(conversationId, requestContext?)`

通过 thread ID 检索对话。

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

console.log(conversation.thread)
```

**返回：** `Promise<Conversation>`。

#### `delete(conversationId, requestContext?)`

通过 thread ID 删除对话。

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

console.log(deleted.deleted)
```

**返回：** `Promise<ConversationDeleted>`。

### 条目

#### `items.list(conversationId, requestContext?)`

列出对话中存储的条目。

```typescript
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 服务器的请求上下文。