API Responses d'OpenAI

Cette interface compatible avec OpenAI et reposant sur des agents vous permet d'utiliser les Agents Mastra comme une API Responses. Elle fournit des méthodes permettant de créer, de récupérer, de diffuser en streaming et de supprimer des réponses par l'intermédiaire des agents Mastra.

Ces routes sont des adaptateurs reposant sur les agents, la mémoire et le stockage de Mastra. Utilisez agent_id pour sélectionner l'agent Mastra qui doit traiter la requête. Vous pouvez transmettre model afin de remplacer le modèle configuré de l'agent pour une seule requête, ou l'omettre pour utiliser le modèle déjà configuré sur l'agent.

Les réponses enregistrées renvoient également conversation_id. Dans Mastra, il s'agit du threadId brut de la mémoire.

Cette API est actuellement expérimentale.

Exemple d'utilisation

import { MastraClient } from '@mastra/client-js'

const client = new MastraClient({
  baseUrl: 'http://localhost:4111',
})

const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Summarize this ticket',
  store: true,
})

console.log(response.output_text)

Méthodes

Cycle de vie

create(params)

Crée une réponse.

const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Summarize this ticket',
})

Renvoie : Promise<ResponsesResponse> lorsque stream est omis ou vaut false.

Lorsque stream: true, create() renvoie un itérable asynchrone de charges utiles d'événements au format SSE :

const stream = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Summarize this ticket',
  stream: true,
})

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta)
  }
}

Les réponses en streaming peuvent également comprendre des événements de tools. Les flux d'appels de tools utilisent les événements response.output_item.added, response.function_call_arguments.delta, response.function_call_arguments.done et response.output_item.done. Les résultats des tools apparaissent sous forme d'éléments function_call_output avec des identifiants <toolCallId>:output.

Renvoie : Promise<ResponsesStream>.

retrieve(responseId, requestContext?)

Récupère une réponse enregistrée.

const response = await client.responses.retrieve('msg_123')

Renvoie : Promise<ResponsesResponse>.

delete(responseId, requestContext?)

Supprime une réponse enregistrée.

const deleted = await client.responses.delete('msg_123')

Renvoie : Promise<{ id: string; object: "response"; deleted: true }>

stream(params)

Crée une réponse en streaming.

const stream = await client.responses.stream({
  agent_id: 'support-agent',
  input: 'Say hello',
})

for await (const event of stream) {
  console.log(event.type)
}

Renvoie : Promise<ResponsesStream>.

Réponses enregistrées et conversations

Les réponses enregistrées comprennent à la fois response.id et conversation_id.

• response.id est l'identifiant de la réponse. Pour les réponses enregistrées reposant sur un agent, il s'agit de l'identifiant persistant du message de l'assistant.
• conversation_id est l'identifiant brut du fil Mastra.

Utilisez previous_response_id lorsque vous souhaitez poursuivre à partir d'une réponse précédemment enregistrée. Utilisez conversation_id lorsque vous souhaitez cibler directement un fil connu.

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

const second = await client.responses.create({
  agent_id: 'support-agent',
  conversation_id: first.conversation_id!,
  input: 'Add a follow-up to the same thread',
  store: true,
})

Utilisez client.conversations lorsque vous souhaitez créer, récupérer, supprimer ou inspecter directement la conversation sous-jacente de l'API Responses d'OpenAI.

Appel de fonctions (tools)

response.tools contient les définitions de fonctions configurées et disponibles pour la requête.

Si le modèle appelle une fonction, cette activité est incluse dans response.output sous forme d'éléments function_call et function_call_output, aux côtés du message final de l'assistant.

Lorsque stream: true, les appels de fonctions sont également émis sous forme d'événements du flux Responses. Lisez les événements response.function_call_arguments.delta pour obtenir des chunks d'arguments partiels et privilégiez response.function_call_arguments.done pour la charge utile finale des arguments et le nom du tool. Lisez les événements response.output_item.done pour les éléments function_call et function_call_output terminés. Les éléments de sortie des tools utilisent des identifiants <toolCallId>:output.

Sortie structurée

Utilisez text.format lorsque vous souhaitez obtenir une sortie JSON.

• json_object active le mode JSON.
• json_schema active une sortie structurée contrainte par un schéma.

Les deux formats renvoient du JSON dans le contenu du message de l'assistant. Utilisez json_schema lorsque vous devez appliquer strictement un schéma. Utilisez json_object lorsque vous avez seulement besoin d'une sortie JSON valide.

const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Return a structured support ticket summary.',
  text: {
    format: {
      type: 'json_schema',
      name: 'ticket_summary',
      schema: {
        type: 'object',
        properties: {
          summary: { type: 'string' },
          priority: { type: 'string' },
        },
        required: ['summary', 'priority'],
        additionalProperties: false,
      },
    },
  },
})

Requêtes reposant sur un Provider

Utilisez providerOptions lorsque vous avez besoin d'options propres au Provider que Mastra ne normalise pas au niveau de Responses.

const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Continue this exchange',
  providerOptions: {
    openai: {
      previousResponseId: 'resp_123',
    },
  },
})

Structure de la réponse

L'objet de réponse renvoyé comprend :

• id : l'identifiant de la réponse
• output : les éléments de sortie tels que message, function_call et function_call_output de l'assistant
• output_text : getter pratique qui rassemble la sortie textuelle de l'assistant
• tools : les définitions de tools configurées pour la requête
• conversation_id : l'identifiant brut du fil pour les réponses enregistrées
• text : le format de sortie textuelle demandé, s'il est fourni

Paramètres

agent_id?:

string

Requis pour les requêtes initiales. Sélectionne l'agent Mastra qui exécute la requête. Les tours de suivi enregistrés peuvent l'omettre lorsqu'ils poursuivent avec previous_response_id.

model?:

string

Remplacement facultatif du modèle pour cette requête, par exemple openai/gpt-5. En cas d'omission, Mastra utilise le modèle configuré sur l'agent sélectionné.

input:

string | Array<{ role: 'system' | 'developer' | 'user' | 'assistant'; content: string | Array<{ type: 'input_text' | 'text' | 'output_text'; text: string }> }>

Requis. Texte d'entrée ou tableau de messages pour la réponse.

instructions?:

string

Remplacement facultatif des instructions pour cette requête.

text?:

{ format: { type: 'json_object' } | { type: 'json_schema'; name: string; schema: Record<string, unknown>; description?: string; strict?: boolean } }

Format facultatif de la sortie textuelle. Utilisez json_object pour le mode JSON ou json_schema pour une sortie structurée contrainte par un schéma.

providerOptions?:

Record<string, Record<string, unknown> | undefined>

Options facultatives propres au Provider transmises à l'appel du modèle sous-jacent.

stream?:

boolean

Lorsque la valeur est true, renvoie un itérable asynchrone d'événements de l'API Responses.

store?:

boolean

Lorsque la valeur est true, conserve la réponse dans la mémoire de l'agent sélectionné.

conversation_id?:

string

Identifiant facultatif de la conversation. Dans Mastra, il s'agit de l'identifiant brut du fil de mémoire.

previous_response_id?:

string

Poursuit une chaîne de réponses enregistrées à partir de la réponse précédente.

requestContext?:

RequestContext | Record<string, any>

Contexte facultatif de la requête transmis au serveur Mastra.