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 : utilisez @mastra/claude pour enregistrer un agent Claude SDK et l'appeler avec les méthodes Mastra generate() et stream().
• 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 : 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

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

pnpm

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

Yarn

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

Bun

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

Définissez les identifiants du SDK Claude :

export ANTHROPIC_API_KEY="..."

Créer un agent Claude SDK

Configurez Claude Agent SDK à l'aide de sdkOptions.

src/mastra/agents/claude-sdk-agent.ts

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.

src/mastra/agents/claude-sdk-agent.ts

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

npm install @mastra/cursor @cursor/sdk

pnpm

pnpm add @mastra/cursor @cursor/sdk

Yarn

yarn add @mastra/cursor @cursor/sdk

Bun

bun add @mastra/cursor @cursor/sdk

Définissez les identifiants du SDK Cursor :

export CURSOR_API_KEY="..."

Créer un agent Cursor SDK

Configurez Cursor Agent SDK à l'aide de sdkOptions.

src/mastra/agents/cursor-sdk-agent.ts

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 :

src/mastra/agents/cursor-sdk-agent.ts

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 :

src/mastra/agents/cursor-sdk-agent.ts

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

npm install @mastra/openai @openai/agents zod

pnpm

pnpm add @mastra/openai @openai/agents zod

Yarn

yarn add @mastra/openai @openai/agents zod

Bun

bun add @mastra/openai @openai/agents zod

Définissez les identifiants du SDK OpenAI :

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.

src/mastra/agents/openai-sdk-agent.ts

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 :

src/mastra/agents/openai-sdk-agent.ts

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.

src/mastra/agents/openai-sdk-agent.ts

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 :

src/mastra/index.ts

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() :

src/mastra/run-sdk-agent.ts

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 :

src/mastra/resume-claude.ts

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 :

src/mastra/resume-openai.ts

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.

src/mastra/run-openai-structured-output.ts

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é.

Ressources associées

• Vue d'ensemble des agents
• Outils
• Observabilité