OpenAI Responses API Conversations

OpenAI Responses API Conversations は、Mastra Agents の会話管理機能を Responses API として提供します。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 サーバーへ転送されるリクエストコンテキスト。