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

# Agents SDK

Les agents SDK vous permettent d'utiliser d'autres frameworks de SDK agentiques dans Mastra. Ils servent à enregistrer dans un projet Mastra des agents reposant sur un SDK, tandis que le SDK du fournisseur conserve son propre environnement d'exécution, ses outils, ses autorisations et sa boucle agentique.

## Quand utiliser des agents SDK

- Un SDK fournisseur gère déjà la boucle agentique, les outils, les autorisations ou l'environnement d'exécution local.
- Vous souhaitez enregistrer cet agent reposant sur un SDK dans un projet Mastra.
- Vous avez besoin de sorties `generate()` et `stream()` compatibles avec Mastra.
- Vous souhaitez que l'utilisation, les coûts et l'activité des outils liés à l'exécution du SDK apparaissent dans l'observabilité Mastra.

## Agents SDK pris en charge

- [Claude Agent SDK](#claude-agent-sdk) : utilisez `@mastra/claude` pour enregistrer un agent Claude SDK et l'appeler avec les méthodes Mastra `generate()` et `stream()`.
- [Cursor Agent SDK](#cursor-agent-sdk) : utilisez `@mastra/cursor` pour enregistrer un agent Cursor SDK et l'appeler avec les méthodes Mastra `generate()` et `stream()`.
- [OpenAI Agents SDK](#openai-agents-sdk) : utilisez `@mastra/openai` pour enregistrer un agent OpenAI SDK et l'appeler avec les méthodes Mastra `generate()` et `stream()`.

## Claude Agent SDK

Utilisez `@mastra/claude` pour configurer l'environnement d'exécution de Claude Code, les autorisations, les outils et le comportement de la boucle agentique.

### Installer les packages Claude

Installez le package Mastra et la dépendance homologue Claude Agent SDK :

**npm**:

```bash
npm install @mastra/claude @anthropic-ai/claude-agent-sdk
```

**pnpm**:

```bash
pnpm add @mastra/claude @anthropic-ai/claude-agent-sdk
```

**Yarn**:

```bash
yarn add @mastra/claude @anthropic-ai/claude-agent-sdk
```

**Bun**:

```bash
bun add @mastra/claude @anthropic-ai/claude-agent-sdk
```

Définissez les identifiants du SDK Claude :

```bash
export ANTHROPIC_API_KEY="..."
```

### Créer un agent Claude SDK

Configurez Claude Agent SDK à l'aide de `sdkOptions`.

```typescript
import { ClaudeSDKAgent } from '@mastra/claude'

export const claudeSDKAgent = new ClaudeSDKAgent({
  id: 'claude-sdk-agent',
  name: 'Claude SDK Agent',
  description: 'Use Claude Agent SDK through Mastra.',
  sdkOptions: {
    model: 'claude-sonnet-4-6',
    cwd: process.cwd(),
  },
})
```

### Ajouter des outils Claude SDK

Les outils de Claude Agent SDK sont fournis par l'intermédiaire de serveurs Model Context Protocol (MCP) du SDK Claude. Créez le serveur avec le SDK Claude, puis transmettez-le via `sdkOptions.mcpServers`.

```typescript
import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk'
import { ClaudeSDKAgent } from '@mastra/claude'
import { getTemperature } from '../tools/get-temperature'

const weatherServer = createSdkMcpServer({
  name: 'weather',
  version: '1.0.0',
  tools: [getTemperature],
})

export const claudeSDKAgent = new ClaudeSDKAgent({
  id: 'claude-sdk-agent',
  name: 'Claude SDK Agent',
  description: 'Use Claude Agent SDK through Mastra.',
  sdkOptions: {
    model: 'claude-sonnet-4-6',
    cwd: process.cwd(),
    mcpServers: {
      weather: weatherServer,
    },
    allowedTools: ['mcp__weather__get_temperature'],
  },
})
```

La valeur `allowedTools` suit la convention de nommage des outils MCP de Claude Agent SDK : `mcp__<server name>__<tool name>`.

## Cursor Agent SDK

Utilisez `@mastra/cursor` pour enregistrer un agent Cursor SDK dans Mastra tout en conservant la configuration propre à Cursor dans les options du SDK Cursor.

### Installer les packages Cursor

Installez le package Mastra et la dépendance homologue du SDK Cursor :

**npm**:

```bash
npm install @mastra/cursor @cursor/sdk
```

**pnpm**:

```bash
pnpm add @mastra/cursor @cursor/sdk
```

**Yarn**:

```bash
yarn add @mastra/cursor @cursor/sdk
```

**Bun**:

```bash
bun add @mastra/cursor @cursor/sdk
```

Définissez les identifiants du SDK Cursor :

```bash
export CURSOR_API_KEY="..."
```

### Créer un agent Cursor SDK

Configurez Cursor Agent SDK à l'aide de `sdkOptions`.

```typescript
import { CursorSDKAgent } from '@mastra/cursor'

export const cursorSDKAgent = new CursorSDKAgent({
  id: 'cursor-sdk-agent',
  name: 'Cursor SDK Agent',
  description: 'Use Cursor Agent SDK through Mastra.',
  sdkOptions: {
    apiKey: process.env.CURSOR_API_KEY,
    model: {
      id: 'gpt-5',
    },
    local: {
      cwd: process.cwd(),
    },
  },
})
```

Les agents Cursor locaux nécessitent un modèle explicite. Définissez-le dans `sdkOptions.model`.

### Utiliser un agent Cursor SDK existant

Si votre application crée déjà un agent Cursor SDK, transmettez plutôt cet agent à `CursorSDKAgent` :

```typescript
import { Agent as CursorAgent } from '@cursor/sdk'
import { CursorSDKAgent } from '@mastra/cursor'

const cursorAgent = CursorAgent.create({
  apiKey: process.env.CURSOR_API_KEY,
  model: {
    id: 'gpt-5',
  },
  local: {
    cwd: process.cwd(),
  },
})

export const cursorSDKAgent = new CursorSDKAgent({
  id: 'cursor-sdk-agent',
  name: 'Cursor SDK Agent',
  description: 'Use Cursor Agent SDK through Mastra.',
  agent: cursorAgent,
})
```

### Ajouter des outils Cursor SDK

Les outils de Cursor Agent SDK se configurent à l'aide des options du SDK Cursor. Transmettez les serveurs Model Context Protocol (MCP) via `sdkOptions.mcpServers` :

```typescript
import { CursorSDKAgent } from '@mastra/cursor'
import { mcpServers } from '../mcp/cursor'

export const cursorSDKAgent = new CursorSDKAgent({
  id: 'cursor-sdk-agent',
  name: 'Cursor SDK Agent',
  description: 'Use Cursor Agent SDK through Mastra.',
  sdkOptions: {
    apiKey: process.env.CURSOR_API_KEY,
    model: {
      id: 'gpt-5',
    },
    local: {
      cwd: process.cwd(),
    },
    mcpServers,
  },
})
```

## OpenAI Agents SDK

Utilisez `@mastra/openai` pour enregistrer un agent OpenAI Agents SDK dans Mastra tout en conservant les réglages propres à OpenAI dans les options du SDK OpenAI.

### Installer les packages OpenAI

Installez le package Mastra et la dépendance homologue OpenAI Agents SDK :

**npm**:

```bash
npm install @mastra/openai @openai/agents zod
```

**pnpm**:

```bash
pnpm add @mastra/openai @openai/agents zod
```

**Yarn**:

```bash
yarn add @mastra/openai @openai/agents zod
```

**Bun**:

```bash
bun add @mastra/openai @openai/agents zod
```

Définissez les identifiants du SDK OpenAI :

```bash
export OPENAI_API_KEY="..."
```

### Créer un agent OpenAI SDK

Configurez OpenAI Agents SDK à l'aide de `sdkOptions`. `OpenAISDKAgent` crée l'agent du SDK OpenAI lors de sa première utilisation.

```typescript
import { OpenAISDKAgent } from '@mastra/openai'

export const openaiSDKAgent = new OpenAISDKAgent({
  id: 'openai-sdk-agent',
  name: 'OpenAI SDK Agent',
  description: 'Use OpenAI Agents SDK through Mastra.',
  sdkOptions: {
    name: 'Repository assistant',
    instructions: 'Answer clearly and cite the relevant files.',
    model: 'gpt-5',
  },
})
```

### Utiliser un agent OpenAI SDK existant

Si votre application crée déjà un agent OpenAI SDK, transmettez plutôt cet agent à `OpenAISDKAgent` :

```typescript
import { Agent as OpenAIAgent } from '@openai/agents'
import { OpenAISDKAgent } from '@mastra/openai'

const sdkAgent = new OpenAIAgent({
  name: 'Repository assistant',
  instructions: 'Answer clearly and cite the relevant files.',
  model: 'gpt-5',
})

export const openaiSDKAgent = new OpenAISDKAgent({
  id: 'openai-sdk-agent',
  name: 'OpenAI SDK Agent',
  description: 'Use OpenAI Agents SDK through Mastra.',
  agent: sdkAgent,
})
```

### Ajouter des outils OpenAI SDK

Les outils d'OpenAI Agents SDK se configurent à l'aide des options du SDK OpenAI. Créez les outils avec le SDK OpenAI, puis transmettez-les via `sdkOptions.tools`.

```typescript
import { tool } from '@openai/agents'
import { OpenAISDKAgent } from '@mastra/openai'
import { z } from 'zod'

const getTemperature = tool({
  name: 'get_temperature',
  description: 'Get the current temperature for a city.',
  parameters: z.object({
    city: z.string(),
  }),
  execute: async ({ city }) => {
    return `${city}: 27 C`
  },
})

export const openaiSDKAgent = new OpenAISDKAgent({
  id: 'openai-sdk-agent',
  name: 'OpenAI SDK Agent',
  description: 'Use OpenAI Agents SDK through Mastra.',
  sdkOptions: {
    name: 'Weather assistant',
    model: 'gpt-5',
    tools: [getTemperature],
  },
})
```

## Enregistrer des agents SDK

Enregistrez les agents SDK dans l'instance Mastra comme les autres agents :

```typescript
import { Mastra } from '@mastra/core'
import { claudeSDKAgent } from './agents/claude-sdk-agent'
import { cursorSDKAgent } from './agents/cursor-sdk-agent'
import { openaiSDKAgent } from './agents/openai-sdk-agent'

export const mastra = new Mastra({
  agents: {
    claudeSDKAgent,
    cursorSDKAgent,
    openaiSDKAgent,
  },
})
```

Après leur enregistrement, appelez-les avec `mastra.getAgentById()` :

```typescript
import { mastra } from './index'

const agent = mastra.getAgentById('cursor-sdk-agent')
const stream = await agent.stream('Inspect this project and describe the test setup.')

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}
```

## Reprendre les exécutions du SDK

Les agents SDK prennent en charge les méthodes Mastra `resumeGenerate()` et `resumeStream()` avec les données de reprise natives du fournisseur. Transmettez le message à poursuivre ainsi que l'identifiant de reprise utilisé par le SDK sous-jacent.

Les agents Claude SDK peuvent reprendre une session connue avec `sessionId` :

```typescript
const result = await claudeSDKAgent.resumeGenerate({
  message: 'Continue the previous task.',
  sessionId: 'claude-session-id',
})

console.log(result.text)
```

Les agents OpenAI SDK peuvent reprendre à partir d'une réponse, d'une conversation ou d'une session antérieure :

```typescript
const stream = await openaiSDKAgent.resumeStream({
  message: 'Continue the previous task.',
  previousResponseId: 'resp_123',
})

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}
```

Les agents Cursor SDK peuvent poursuivre avec l'agent SDK encapsulé. Si vous devez reprendre un agent Cursor SDK stocké à partir de son ID, transmettez `agentId` dans `resumeData`.

## Sortie structurée

Les agents Claude et OpenAI SDK prennent en charge la propriété Mastra `structuredOutput` grâce aux API de sortie structurée natives de leur fournisseur. La valeur validée est disponible dans `result.object`.

```typescript
import { z } from 'zod'

const result = await openaiSDKAgent.generate<{ summary: string }>('Summarize this project.', {
  structuredOutput: {
    schema: z.object({
      summary: z.string(),
    }),
  },
})

console.log(result.object.summary)
```

Les agents Cursor SDK lèvent une erreur explicite lorsque `structuredOutput` est demandé, car le SDK TypeScript de Cursor n'expose pas d'API de sortie contrainte par un schéma.

## Observabilité

Les agents SDK créent des spans Mastra d'agent et de modèle pour les appels à `generate()` et `stream()`. Mastra enregistre l'utilisation fournie par le SDK, l'activité des outils et les métadonnées du fournisseur lorsque le SDK de ce dernier expose ces événements.

Les exécutions du SDK Claude peuvent inclure le coût estimé par le SDK à partir du message de résultat Claude. Celles du SDK Cursor incluent l'utilisation des tokens provenant des mises à jour d'interaction de Cursor. Celles du SDK OpenAI incluent l'utilisation des tokens provenant de l'état d'exécution OpenAI.

Pour configurer le stockage et le tableau de bord, consultez la page [Observabilité](https://mastra.zisheng.pro/fr/docs/observability/overview).

## Ressources associées

- [Vue d'ensemble des agents](https://mastra.zisheng.pro/fr/docs/agents/overview)
- [Outils](https://mastra.zisheng.pro/fr/docs/agents/using-tools)
- [Observabilité](https://mastra.zisheng.pro/fr/docs/observability/overview)