OpenAI Responses API Conversations

L'interface OpenAI Responses API Conversations expose les fonctionnalités de gestion des conversations des Agents Mastra sous la forme d'une Responses API. Elle fournit des méthodes permettant de créer, récupérer, supprimer et inspecter des conversations de Mastra adossées à des threads.

Cette API complète l'OpenAI Responses API. Les appels Responses stockés renvoient conversation_id ; dans Mastra, cette valeur correspond au threadId brut de la mémoire. Utilisez client.conversations lorsque vous souhaitez manipuler directement ce thread.

Cette API est actuellement expérimentale.

Relation avec OpenAI Responses

Utilisez l'OpenAI Responses API pour la génération et la poursuite d'une conversation :

const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Start a support thread',
  store: true,
})

console.log(response.conversation_id)

Utilisez la Conversations API pour inspecter ou gérer ce thread stocké :

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

Exemple d'utilisation

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)

Méthodes

Cycle de vie

create(params)

Crée un nouveau thread de conversation pour l'Agent sélectionné.

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

Renvoie : Promise<Conversation>.

retrieve(conversationId, requestContext?)

Récupère une conversation à partir de l'identifiant de son thread.

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

console.log(conversation.thread)

Renvoie : Promise<Conversation>.

delete(conversationId, requestContext?)

Supprime une conversation à partir de l'identifiant de son thread.

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

console.log(deleted.deleted)

Renvoie : Promise<ConversationDeleted>.

Éléments

items.list(conversationId, requestContext?)

Répertorie les éléments stockés pour une conversation.

const items = await client.conversations.items.list('thread_123')

console.log(items.data)

Renvoie : Promise<ConversationItemsPage>.

Structure de la réponse

create() et retrieve() renvoient un objet de conversation contenant :

• id : l'identifiant brut du thread
• object : toujours 'conversation'
• thread : l'enregistrement du thread stocké

delete() renvoie :

• id : l'identifiant brut du thread
• object : toujours 'conversation.deleted'
• deleted : toujours true

items.list() renvoie :

• object : toujours 'list'
• data : éléments de la conversation tels que message, function_call et function_call_output
• first_id : identifiant du premier élément de la page
• last_id : identifiant du dernier élément de la page
• has_more : indique s'il existe d'autres éléments après la page actuelle

Paramètres

agent_id:

string

Obligatoire. Agent Mastra enregistré auquel appartient la mémoire de la conversation.

conversation_id?:

string

Identifiant facultatif de la conversation à utiliser comme identifiant brut du thread.

resource_id?:

string

Identifiant facultatif de la ressource à associer au thread de conversation.

title?:

string

Titre facultatif du thread stocké avec la conversation.

metadata?:

Record<string, unknown>

Métadonnées facultatives du thread stockées avec la conversation.

requestContext?:

RequestContext | Record<string, any>

Contexte de requête facultatif transmis au serveur Mastra.