API Agents

L’API Agents fournit des méthodes permettant d’interagir avec les Agents IA Mastra, notamment pour générer des réponses et diffuser des interactions en continu. Elle fournit également des méthodes pour gérer les Tools des Agents.

Récupération de tous les Agents

Récupérez la liste de tous les Agents disponibles :

const agents = await mastraClient.listAgents()

Renvoie un objet qui associe les ID des Agents à leurs configurations sérialisées.

Utilisation d’un Agent précis

Récupérez une instance d’un Agent précis à partir de son ID :

src/mastra/agents/my-agent.ts

export const myAgent = new Agent({
  id: 'my-agent',
})

const agent = mastraClient.getAgent('my-agent')

Méthodes des Agents

details()

Récupère des informations détaillées sur un Agent :

const details = await agent.details()

generate()

Génère une réponse de l’Agent :

const response = await agent.generate(
  [
    {
      role: 'user',
      content: 'Hello, how are you?',
    },
  ],
  {
    memory: {
      thread: 'thread-abc', // Optional: Thread ID for conversation context
      resource: 'user-123', // Optional: Resource ID
    },
    structuredOutput: {}, // Optional: Structured Output configuration
  },
)

Vous pouvez également utiliser le format simplifié sous forme de chaîne avec les options de mémoire :

const response = await agent.generate('Hello, how are you?', {
  memory: {
    thread: 'thread-1',
    resource: 'resource-1',
  },
})

stream()

Diffuse les réponses de l’Agent en continu pour les interactions en temps réel :

const response = await agent.stream('Tell me a story')

// Process data stream with the processDataStream util
response.processDataStream({
  onChunk: async chunk => {
    console.log(chunk)
  },
})

Vous pouvez également utiliser le format simplifié sous forme de chaîne avec les options de mémoire :

const response = await agent.stream('Tell me a story', {
  memory: {
    thread: 'thread-1',
    resource: 'resource-1',
  },
  clientTools: { colorChangeTool },
})

response.processDataStream({
  onChunk: async chunk => {
    if (chunk.type === 'text-delta') {
      console.log(chunk.payload.text)
    }
  },
})

Vous pouvez également lire directement le corps de la réponse :

const reader = response.body.getReader()
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  console.log(new TextDecoder().decode(value))
}

Format compatible avec l’AI SDK

Pour diffuser côté client des parties au format AI SDK depuis une réponse agent.stream(...), encapsulez response.processDataStream dans un ReadableStream<ChunkType> et utilisez toAISdkStream :

client-ai-sdk-transform.ts

import { createUIMessageStream } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'
import type { ChunkType, MastraModelOutput } from '@mastra/core/stream'

const response = await agent.stream('Tell me a story')

const chunkStream: ReadableStream<ChunkType> = new ReadableStream<ChunkType>({
  start(controller) {
    response
      .processDataStream({
        onChunk: async chunk => controller.enqueue(chunk as ChunkType),
      })
      .finally(() => controller.close())
  },
})

const uiMessageStream = createUIMessageStream({
  execute: async ({ writer }) => {
    for await (const part of toAISdkStream(chunkStream as unknown as MastraModelOutput, {
      from: 'agent',
    })) {
      writer.write(part)
    }
  },
})

for await (const part of uiMessageStream) {
  console.log(part)
}

sendMessage()

Envoie une entrée rédigée par l’utilisateur à une exécution active de l’Agent ou à un thread de mémoire inactif. Utilisez cette méthode avec subscribeToThread() afin que le client puisse effectuer le rendu du flux réveillé par le message ou recevant celui-ci.

const agent = mastraClient.getAgent('support-agent')

const result = await agent.sendMessage({
  message: {
    contents: 'Also consider the customer note I just added.',
    attributes: { sentFrom: 'web' },
  },
  resourceId: 'user-123',
  threadId: 'thread-abc',
})

console.log(result.runId)

message accepte une chaîne, un tableau de parties texte/fichier ou un objet contenant contents, attributes, metadata et providerOptions.

queueMessage()

Place une entrée rédigée par l’utilisateur dans la file d’attente du prochain tour du thread. Si le thread est actif, Mastra démarre une nouvelle exécution après la fin de l’exécution actuelle. Si le thread est inactif, Mastra démarre immédiatement une exécution.

await agent.queueMessage({
  message: 'Also check whether the tests need updates.',
  resourceId: 'user-123',
  threadId: 'thread-abc',
})

sendSignal()

Envoie un signal de bas niveau à une exécution active de l’Agent ou à un thread de mémoire. Utilisez cette méthode pour le contexte généré par le système, comme les rappels réactifs ou le contexte en forme de notification qui ne nécessite pas de stockage dans une boîte de réception. Pour des enregistrements de notification durables, utilisez l’API côté serveur Agent.sendNotificationSignal(). Pour les entrées rédigées par l’utilisateur, privilégiez sendMessage() ou queueMessage().

const agent = mastraClient.getAgent('support-agent')

const result = await agent.sendSignal({
  signal: {
    type: 'reactive',
    tagName: 'system-reminder',
    contents: 'Also consider the latest customer note.',
  },
  resourceId: 'user-123',
  threadId: 'thread-abc',
})

console.log(result.runId)

Utilisez ifActive.behavior et ifIdle.behavior pour déterminer si Mastra distribue, persiste ou ignore un signal, ou réveille un thread à partir de celui-ci :

await agent.sendSignal({
  signal: { type: 'reactive', tagName: 'system-reminder', contents: 'Store this for later.' },
  resourceId: 'user-123',
  threadId: 'thread-abc',
  ifIdle: {
    behavior: 'persist',
  },
})

Transmettez ifIdle.streamOptions lorsque le flux de réveil d’un thread inactif nécessite des options telles que les paramètres du modèle, les Tools ou le contexte d’exécution :

await agent.sendSignal({
  signal: { type: 'reactive', tagName: 'system-reminder', contents: 'Start from this signal.' },
  resourceId: 'user-123',
  threadId: 'thread-abc',
  ifIdle: {
    behavior: 'wake',
    streamOptions: {
      maxSteps: 3,
    },
  },
})

Renvoie { accepted: true, runId: string }.

signal:

{ type: 'user' | 'reactive' | 'notification' | string; tagName?: string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }

Charge utile du signal de bas niveau. Utilisez type pour la catégorie sémantique du signal et tagName pour le tag XML présenté au modèle. providerOptions est associé au tour de prompt obtenu et persisté dans le message de signal stocké.

runId?:

string

ID d’exécution à cibler directement.

resourceId?:

string

ID de ressource du thread de mémoire. À utiliser avec threadId pour les signaux ciblant un thread.

threadId?:

string

ID du thread à cibler. À utiliser avec resourceId pour les signaux ciblant un thread.

ifActive.behavior?:

'deliver' | 'persist' | 'discard'

Contrôle le comportement lorsque le thread cible est actif. Utilise par défaut deliver.

ifActive.attributes?:

Record<string, string | number | boolean>

Attributs fusionnés dans le signal lorsque Mastra l’accepte pendant que le thread cible est actif.

ifIdle.behavior?:

'wake' | 'persist' | 'discard'

Contrôle le comportement lorsque le thread cible est inactif. Utilise par défaut wake.

ifIdle.streamOptions?:

Omit<AgentExecutionOptions, 'messages'>

Options du flux qui démarre lorsque ifIdle.behavior vaut wake.

ifIdle.attributes?:

Record<string, string | number | boolean>

Attributs fusionnés dans le signal lorsque Mastra l’accepte pendant que le thread cible est inactif.

subscribeToThread()

S’abonne aux chunks bruts du flux d’un thread de mémoire. Utilisez cette méthode pour effectuer le rendu de la sortie d’un thread susceptible d’être démarré ou poursuivi par sendMessage(), queueMessage(), sendSignal() ou par la distribution d’une notification côté serveur.

const agent = mastraClient.getAgent('support-agent')

const subscription = await agent.subscribeToThread({
  resourceId: 'user-123',
  threadId: 'thread-abc',
})

await subscription.processDataStream({
  onChunk: chunk => {
    console.log(chunk)
  },
  reconnect: true,
})

subscribeToThread() renvoie la Response sous-jacente ainsi qu’un utilitaire processDataStream(). Cet utilitaire lit le flux d’abonnement jusqu’à la fermeture de la connexion ou l’abandon de la requête. Transmettez reconnect: true pour vous réabonner lorsque le transport se ferme ou qu’une demande de reconnexion échoue, par exemple après l’expiration du délai d’inactivité d’un proxy.

resourceId?:

string

ID de ressource du thread de mémoire.

threadId:

string

ID du thread auquel s’abonner.

processDataStream().reconnect?:

boolean | { maxRetries?: number; delayMs?: number }

Reconnecte le flux d’abonnement après sa fermeture ou l’échec d’une demande de reconnexion. true réessaie indéfiniment avec un délai d’une seconde.

streamUntilIdle()

Diffuse une réponse en continu et maintient le flux ouvert jusqu’à la fin de chaque tâche en arrière-plan lancée pendant l’exécution. Le serveur revient dans la boucle agentique à la fin de chaque tâche afin que le LLM puisse réagir aux résultats au cours du même appel. Nécessite que les tâches en arrière-plan soient activées sur l’instance Mastra ainsi qu’un thread de mémoire ; sinon, l’appel utilise un simple stream().

const response = await agent.streamUntilIdle('Research solana for me', {
  memory: {
    thread: 'thread-1',
    resource: 'resource-1',
  },
  maxIdleMs: 5 * 60_000, //optional
})

response.processDataStream({
  onChunk: async chunk => {
    if (chunk.type === 'background-task-completed') {
      console.log('task complete:', chunk.payload.taskId)
    }
  },
})

resumeStreamUntilIdle()

Reprend un flux d’Agent suspendu avec des données personnalisées et maintient le flux ouvert jusqu’à la fin de chaque tâche en arrière-plan lancée pendant l’exécution. Utilisez cette méthode pour poursuivre l’exécution après un point de suspension, par exemple la suspension d’un Workflow au sein d’un Agent. Nécessite que les tâches en arrière-plan soient activées sur l’instance Mastra ainsi qu’un thread de mémoire ; sinon, l’appel utilise un simple resumeStream() :

const response = await agent.resumeStreamUntilIdle(
  { approved: true, selectedOption: 'plan-b' },
  {
    memory: {
      thread: 'thread-1',
      resource: 'resource-1',
    },
    runId: 'run-123',
    toolCallId: 'tool-call-456', // optional
    maxIdleMs: 5 * 60_000, //optional
  },
)

await response.processDataStream({
  onChunk: chunk => {
    console.log(chunk)
  },
})

Le flux émet les mêmes types de chunks que stream(), auxquels s’ajoutent des chunks background-task-* pour les événements du cycle de vie des tâches. Consultez Agent.streamUntilIdle() pour l’API côté serveur complète et les chunks des tâches en arrière-plan pour connaître la structure des charges utiles.

getTool()

Récupère des informations sur un Tool précis disponible pour l’Agent :

const tool = await agent.getTool('tool-id')

executeTool()

Exécute un Tool précis pour l’Agent :

const result = await agent.executeTool('tool-id', {
  data: { input: 'value' },
})

network()

Diffuse les réponses d’un réseau d’Agents pour les interactions multi-Agents :

const response = await agent.network('Research this topic and write a summary')

response.processDataStream({
  onChunk: async chunk => {
    console.log(chunk)
  },
})

listSuspendedRuns()

Répertorie depuis le stockage les exécutions suspendues de l’Agent : celles qui attendent l’approbation d’un appel de Tool ou la reprise d’un Tool suspendu. La découverte s’appuie sur le stockage ; elle fonctionne donc après le redémarrage du serveur et sur plusieurs instances de serveur. Transmettez le runId renvoyé à approveToolCall(), declineToolCall() ou resumeStream().

const { runs, total } = await agent.listSuspendedRuns({
  threadId: 'thread-456',
  resourceId: 'user-123',
})

if (runs[0]) {
  console.log(runs[0].toolCalls) // [{ toolCallId, toolName, args, requiresApproval }]
  await agent.approveToolCall({
    runId: runs[0].runId,
    toolCallId: runs[0].toolCalls[0].toolCallId,
  })
}

Accepte des filtres facultatifs (threadId, resourceId, fromDate, toDate) et des paramètres de pagination (perPage, page). Renvoie { runs, total }, où total correspond au nombre d’exécutions correspondantes avant pagination. Consultez Agent.listSuspendedRuns() pour en savoir plus sur la structure des exécutions renvoyées.

approveToolCall()

Approuve un appel de Tool en attente et renvoie un flux de continuation. Utilisez cette méthode lorsque vous effectuez le rendu des chunks repris depuis la réponse d’approbation.

const response = await agent.approveToolCall({
  runId: 'run-123',
  toolCallId: 'tool-call-456',
})

response.processDataStream({
  onChunk: async chunk => {
    console.log(chunk)
  },
})

sendToolApproval()

Approuve ou refuse un appel de Tool en attente pour un thread auquel le client est abonné. Utilisez cette méthode avec subscribeToThread() lorsque les chunks repris doivent parvenir par l’abonnement existant au thread plutôt que par un flux de continuation distinct.

const result = await agent.sendToolApproval({
  resourceId: 'user-123',
  threadId: 'thread-456',
  toolCallId: 'tool-call-456',
  approved: true,
})

console.log(result.accepted)

Renvoie { accepted: true, runId: string, toolCallId?: string }.

declineToolCall()

Refuse un appel de Tool en attente et renvoie un flux de continuation. Utilisez cette méthode lorsque vous effectuez le rendu des chunks repris depuis la réponse de refus.

const response = await agent.declineToolCall({
  runId: 'run-123',
  toolCallId: 'tool-call-456',
})

response.processDataStream({
  onChunk: async chunk => {
    console.log(chunk)
  },
})

resumeStream()

Reprend un flux d’Agent suspendu avec des données personnalisées. Utilisez cette méthode pour poursuivre l’exécution après un point de suspension, par exemple la suspension d’un Workflow au sein d’un Agent :

const response = await agent.resumeStream(
  { approved: true, selectedOption: 'plan-b' },
  {
    runId: 'run-123',
    toolCallId: 'tool-call-456', // optional
  },
)

await response.processDataStream({
  onChunk: chunk => {
    console.log(chunk)
  },
})

approveToolCallGenerate()

Approuve un appel de Tool en attente lors de l’utilisation de generate() (sans streaming). Renvoie la réponse complète :

const output = await agent.generate('Find user John', {
  requireToolApproval: true,
})

if (output.finishReason === 'suspended') {
  const result = await agent.approveToolCallGenerate({
    runId: output.runId,
    toolCallId: output.suspendPayload.toolCallId,
  })

  console.log(result.text)
}

declineToolCallGenerate()

Refuse un appel de Tool en attente lors de l’utilisation de generate() (sans streaming). Renvoie la réponse complète :

const output = await agent.generate('Find user John', {
  requireToolApproval: true,
})

if (output.finishReason === 'suspended') {
  const result = await agent.declineToolCallGenerate({
    runId: output.runId,
    toolCallId: output.suspendPayload.toolCallId,
  })

  console.log(result.text)
}

Planifications des Agents

Utilisez les méthodes de planification du SDK client pour gérer les planifications persistées des Agents au moyen des routes /api/schedules. Pour découvrir les concepts et des exemples côté serveur, consultez Schedules et la référence de mastra.schedules.

createSchedule()

Crée une planification d’Agent en transmettant agentId.

const schedule = await mastraClient.createSchedule({
  agentId: 'pinger',
  cron: '0 * * * *',
  prompt: 'Give me a status update.',
})

listSchedules()

Répertorie les planifications des Agents. Filtrez-les au moyen de champs tels que agentId, threadId, resourceId, name ou status.

const schedules = await mastraClient.listSchedules({
  agentId: 'pinger',
  status: 'active',
})

getSchedule()

Récupère une planification d’Agent précise à partir de son ID.

const schedule = await mastraClient.getSchedule('agent_pinger')

updateSchedule()

Met à jour une planification d’Agent. Les planifications des Agents peuvent modifier des champs tels que cron, timezone, prompt, name, les options de distribution des signaux, les métadonnées et status.

const updated = await mastraClient.updateSchedule('agent_pinger', {
  cron: '*/30 * * * *',
  prompt: 'Give me a status update every 30 minutes.',
})

deleteSchedule()

Supprime une planification d’Agent.

await mastraClient.deleteSchedule('agent_pinger')

runSchedule()

Déclenche immédiatement et une seule fois une planification d’Agent sans modifier sa cadence cron.

const run = await mastraClient.runSchedule('agent_pinger')

pauseSchedule()

Suspend une planification d’Agent afin que le planificateur cesse de la déclencher. Renvoie la planification mise à jour.

await mastraClient.pauseSchedule('agent_pinger')

resumeSchedule()

Reprend une planification d’Agent suspendue. La prochaine heure de déclenchement est recalculée à partir de l’heure actuelle ; une planification suspendue pendant une longue période ne déclenche donc pas les occurrences en retard. Renvoie la planification mise à jour.

await mastraClient.resumeSchedule('agent_pinger')

listScheduleTriggers()

Répertorie l’historique des déclenchements d’une planification d’Agent, y compris le résumé joint de l’exécution pour chaque déclenchement.

const { triggers } = await mastraClient.listScheduleTriggers('agent_pinger', {
  limit: 50,
})

Tools clients

Les Tools côté client vous permettent d’exécuter des fonctions personnalisées sur le client lorsque l’Agent les demande.

import { createTool } from '@mastra/client-js'
import { z } from 'zod'

const colorChangeTool = createTool({
  id: 'changeColor',
  description: 'Changes the background color',
  inputSchema: z.object({
    color: z.string(),
  }),
  execute: async inputData => {
    document.body.style.backgroundColor = inputData.color
    return { success: true }
  },
})

// Use with generate
const response = await agent.generate('Change the background to blue', {
  clientTools: { colorChangeTool },
})

// Use with stream
const response = await agent.stream('Tell me a story', {
  memory: {
    thread: 'thread-1',
    resource: 'resource-1',
  },
  clientTools: { colorChangeTool },
})

response.processDataStream({
  onChunk: async chunk => {
    if (chunk.type === 'text-delta') {
      console.log(chunk.payload.text)
    } else if (chunk.type === 'tool-call') {
      console.log(
        `calling tool ${chunk.payload.toolName} with args ${JSON.stringify(
          chunk.payload.args,
          null,
          2,
        )}`,
      )
    }
  },
})

Mise en forme de la sortie d’un Tool client pour le modèle

Les Tools clients prennent en charge toModelOutput afin de contrôler ce que reçoit le modèle, notamment le contenu multimodal tel que les images. Comme les Tools clients s’exécutent localement, le mappage s’exécute également sur le client après la fin d’execute. La sortie transformée est renvoyée au serveur avec le résultat brut ; celui-ci reste ainsi disponible pour le stockage et la logique applicative.

const screenshotTool = createTool({
  id: 'takeScreenshot',
  description: 'Takes a screenshot of the current page',
  inputSchema: z.object({}),
  execute: async () => {
    const base64 = await captureScreenshot()
    return { ok: true, data: base64 }
  },
  toModelOutput: output => ({
    type: 'content',
    value: [{ type: 'media', data: output.data, mediaType: 'image/jpeg' }],
  }),
})

Tracing des Tools clients

Lorsque @mastra/observability est installé et configuré sur le serveur, un Tool côté client enregistre un Span CLIENT_TOOL_CALL comme enfant du Span AGENT_RUN actuel. Le serveur crée ce Span lorsque le modèle émet l’appel du Tool client et injecte un transporteur de Trace W3C dans le chunk d’appel de Tool sortant. Il termine le Span dès que les arguments du Tool sont disponibles. Sans observabilité configurée côté serveur, le Tracing des Tools clients n’effectue aucune opération.

Le SDK client mesure également la durée réelle de la fonction execute de chaque Tool client et la renvoie au serveur, où elle est émise comme métrique mastra_tool_duration_ms avec toolType: "client".

Pour enrichir la télémétrie depuis la fonction execute de votre Tool, utilisez l’utilitaire observe du contexte d’exécution afin d’ajouter des Spans enfants et des logs structurés :

import { createTool } from '@mastra/client-js'
import { z } from 'zod'

const fetchUserTool = createTool({
  id: 'fetchUser',
  description: 'Fetches the current user profile',
  inputSchema: z.object({ userId: z.string() }),
  execute: async ({ userId }, { observe }) => {
    observe.log('info', 'fetching user', { userId })
    const user = await observe.span('http GET /users', async () => {
      const res = await fetch(`/api/users/${userId}`)
      return res.json()
    })
    return user
  },
})

observe est toujours disponible : lorsqu’aucun contexte de Tracing n’est actif, par exemple lors d’une exécution en dehors d’un Agent tracé, span exécute directement la fonction et log n’effectue aucune opération. Aucun contrôle de valeur null n’est nécessaire.

Le SDK sérialise au format OTLP/JSON tout ce que le collecteur a mis en mémoire tampon et le renvoie dans le corps de la requête suivante. Le package @mastra/observability du serveur vérifie que les Spans appartiennent à la bonne Trace afin d’empêcher toute injection entre Traces, puis transmet chaque Span et log au même bus d’observabilité que celui utilisé par la télémétrie côté serveur. Vos exportateurs existants les récupèrent automatiquement une fois l’observabilité configurée.

Agents stockés

Les Agents stockés sont des configurations d’Agent conservées dans une base de données, qui peuvent être créées, mises à jour et supprimées à l’exécution. Ils référencent des primitives (Tools, Workflows, autres Agents, Scorers) par clé ; celles-ci sont résolues depuis le registre Mastra lors de l’instanciation de l’Agent. La mémoire est configurée en ligne sous la forme d’un objet SerializedMemoryConfig avec des options telles que lastMessages et semanticRecall.

listStoredAgents()

Récupère une liste paginée de tous les Agents stockés :

const result = await mastraClient.listStoredAgents()
console.log(result.agents) // Array of stored agents
console.log(result.total) // Total count

Avec pagination et tri :

const result = await mastraClient.listStoredAgents({
  page: 0,
  perPage: 20,
  orderBy: {
    field: 'createdAt',
    direction: 'DESC',
  },
})

createStoredAgent()

Crée un nouvel Agent stocké :

const agent = await mastraClient.createStoredAgent({
  id: 'my-agent',
  name: 'My Assistant',
  instructions: 'You are a helpful assistant.',
  model: {
    provider: 'openai',
    name: 'gpt-5.4',
  },
})

Par défaut, createStoredAgent() publie immédiatement la version initiale. Définissez autoPublish sur false pour créer un brouillon non publié que vous pourrez examiner avant d’appeler activateVersion() :

const draft = await mastraClient.createStoredAgent({
  id: 'draft-agent',
  name: 'Draft Assistant',
  instructions: 'You are a helpful assistant.',
  model: {
    provider: 'openai',
    name: 'gpt-5',
  },
  autoPublish: false,
})

Les Editors configurés avec la source code publient toujours la version initiale, car l’enregistrement écrit la configuration de l’Agent dans le système de fichiers.

Avec toutes les options :

const agent = await mastraClient.createStoredAgent({
  id: 'full-agent',
  name: 'Full Agent',
  description: 'A fully configured agent',
  instructions: 'You are a helpful assistant.',
  model: {
    provider: 'openai',
    name: 'gpt-5.4',
  },
  tools: { calculator: {}, weather: {} },
  workflows: { 'data-processing': {} },
  agents: { 'subagent-1': {} },
  memory: {
    options: {
      lastMessages: 20,
      semanticRecall: false,
    },
  },
  scorers: {
    'quality-scorer': {
      sampling: { type: 'ratio', rate: 0.1 },
    },
  },
  defaultOptions: {
    maxSteps: 10,
  },
  metadata: {
    version: '1.0',
    team: 'engineering',
  },
})

getStoredAgent()

Récupère une instance d’un Agent stocké précis :

const storedAgent = mastraClient.getStoredAgent('my-agent')

Méthodes des Agents stockés

details()

Récupère la configuration de l’Agent stocké :

const details = await storedAgent.details()
console.log(details.name)
console.log(details.instructions)
console.log(details.model)

update()

Met à jour certains champs d’un Agent stocké. Tous les champs sont facultatifs :

const updated = await storedAgent.update({
  name: 'Updated Agent Name',
  instructions: 'New instructions for the agent.',
})

// Update just the tools
await storedAgent.update({
  tools: { 'new-tool-1': {}, 'new-tool-2': {} },
})

// Update metadata
await storedAgent.update({
  metadata: {
    version: '2.0',
    lastModifiedBy: 'admin',
  },
})

delete()

Supprime un Agent stocké :

const result = await storedAgent.delete()
console.log(result.success) // true

Gestion des versions

Les instances Agent (définies dans le code) et StoredAgent disposent toutes deux de méthodes de gestion des versions de configuration. Consultez la section Gestion des versions dans Editor pour découvrir le cycle de vie et le comportement de sélection.

Récupération d’un Agent dans une version précise

Transmettez un identifiant de version lors de la récupération d’un Agent :

// Load the published version (default)
const agent = mastraClient.getAgent('support-agent')

// Load the latest draft
const draftAgent = mastraClient.getAgent('support-agent', { status: 'draft' })

// Load a specific version
const versionedAgent = mastraClient.getAgent('support-agent', { versionId: 'abc-123' })

Pour les Agents stockés, transmettez une option de statut à details() :

const storedAgent = mastraClient.getStoredAgent('my-agent')
const draft = await storedAgent.details(undefined, { status: 'draft' })

listVersions()

Répertorie toutes les versions d’un Agent :

const versions = await agent.listVersions()
console.log(versions.items) // Array of version snapshots
console.log(versions.total)

Avec pagination et tri :

const versions = await agent.listVersions({
  page: 0,
  perPage: 10,
  orderBy: {
    field: 'createdAt',
    direction: 'DESC',
  },
})

createVersion()

Crée un nouvel instantané de version :

const version = await agent.createVersion({
  changeMessage: 'Updated tone to be more friendly',
})

getVersion()

Récupère une version précise à partir de son ID :

const version = await agent.getVersion('version-123')
console.log(version.versionNumber)
console.log(version.changedFields)
console.log(version.createdAt)

activateVersion()

Définit une version comme version publiée active :

await agent.activateVersion('version-123')

restoreVersion()

Restaure une version antérieure en créant une nouvelle version avec la même configuration :

await agent.restoreVersion('version-456')

deleteVersion()

Supprime une version :

await agent.deleteVersion('version-789')

compareVersions()

Compare deux versions et renvoie leurs différences :

const diff = await agent.compareVersions('version-123', 'version-456')
console.log(diff.changes) // Fields that changed between versions

SDK React

Dans le SDK React, transmettez un agentVersionId au moyen de requestContext lorsque vous utilisez le hook useChat :

Version targeting with React SDK

import { useChat } from '@mastra/react'

function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    agentId: 'support-agent',
    requestContext: {
      agentVersionId: 'abc-123',
    },
  })

  // ... render chat UI
}