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

# OpenAI Responses API Conversations

OpenAI Responses API Conversations 提供 Mastra Agent 作為 Responses API 時的對話管理功能。它提供用於在 Mastra 中建立、取得、刪除和查看基於 thread 的對話的方法。

此 API 是 [OpenAI Responses API](https://mastra.zisheng.pro/zh-TW/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 伺服器的請求情境。