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

# 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

```typescript
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.

```typescript
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 :

```typescript
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.

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

**Renvoie :** `Promise<ResponsesResponse>`.

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

Supprime une réponse enregistrée.

```typescript
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.

```typescript
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.

```typescript
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`](https://mastra.zisheng.pro/fr/reference/client-js/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.

```typescript
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.

```typescript
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.