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

# OpenAI Responses API Conversations

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

此 API 延伸自 [OpenAI Responses API](https://mastra.zisheng.pro/zh-HK/reference/client-js/responses)。已儲存的 Responses 呼叫會傳回 `conversation_id`；在 Mastra 中，此值是原始記憶 `threadId`。如要直接操作該執行緒，請使用 `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)
```

如要查看或管理已儲存的執行緒，請使用 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 建立新的對話執行緒。

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

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

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

按執行緒 ID 取得對話。

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

console.log(conversation.thread)
```

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

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

按執行緒 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`：原始執行緒 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 伺服器的請求上下文。