Agent.network()

La méthode .network() permet la collaboration et le routage entre plusieurs Agents. Elle accepte des messages et des options d’exécution facultatives.

Obsolète

La primitive .network() est obsolète et sera supprimée dans une prochaine version majeure. Utilisez plutôt des Agents superviseurs avec agent.stream() ou agent.generate(). Consultez le guide de migration pour effectuer la mise à niveau.

Exemple d’utilisation

import { Agent } from '@mastra/core/agent'
import { agent1, agent2 } from './agents'
import { workflow1 } from './workflows'
import { tool1, tool2 } from './tools'

const agent = new Agent({
  id: 'network-agent',
  name: 'Network Agent',
  instructions: 'You are a network agent that can help users with a variety of tasks.',
  model: 'openai/gpt-5.6-sol',
  agents: {
    agent1,
    agent2,
  },
  workflows: {
    workflow1,
  },
  tools: {
    tool1,
    tool2,
  },
})

await agent.network(`
  Find me the weather in Tokyo.
  Based on the weather, plan an activity for me.
`)

Paramètres

messages:

string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]

Messages à envoyer à l’Agent. Il peut s’agir d’une chaîne, d’un tableau de chaînes ou d’objets de message structurés.

options?:

MultiPrimitiveExecutionOptions

Configuration facultative du processus réseau.

MultiPrimitiveExecutionOptions

maxSteps?:

number

Nombre maximal d’étapes à exécuter.

abortSignal?:

AbortSignal

Signal permettant d’interrompre l’exécution du réseau. Lors de l’interruption, le réseau arrête le routage, annule toute exécution en cours de sous-Agent, de Tool ou de Workflow et n’enregistre pas les résultats partiels dans la mémoire.

onAbort?:

(event: { primitiveType: string; primitiveId: string; iteration: number }) => void | Promise<void>

Fonction de rappel déclenchée lorsque le réseau est interrompu. Elle reçoit un événement contenant le type et l’ID de la primitive en cours d’exécution au moment de l’interruption.

memory?:

object

Configuration de la mémoire. Il s’agit de la méthode recommandée pour la gérer.

object

thread:

string | { id: string; metadata?: Record<string, any>, title?: string }

Fil de conversation, sous forme d’ID de chaîne ou d’objet contenant un id et des metadata facultatives.

resource:

string

Identifiant de l’utilisateur ou de la ressource associé au fil.

options?:

MemoryConfig

Configuration du comportement de la mémoire, notamment l’historique des messages et le rappel sémantique.

tracingContext?:

TracingContext

Contexte de traçage permettant de créer des spans enfants et d’ajouter des métadonnées. Injecté automatiquement lors de l’utilisation du système de traçage de Mastra.

TracingContext

currentSpan?:

Span

Span actuel permettant de créer des spans enfants et d’ajouter des métadonnées. Utilisez-le pour créer des spans enfants personnalisés ou mettre à jour leurs attributs pendant l’exécution.

tracingOptions?:

TracingOptions

Options de configuration du traçage.

TracingOptions

metadata?:

Record<string, any>

Métadonnées à ajouter au span racine de la trace. Utiles pour ajouter des attributs personnalisés tels que des ID utilisateur, des ID de session ou des indicateurs de fonctionnalité.

requestContextKeys?:

string[]

Clés RequestContext supplémentaires à extraire comme métadonnées de cette trace. Prend en charge la notation par points pour les valeurs imbriquées (par exemple 'user.id').

traceId?:

string

ID de trace à utiliser pour cette exécution (1 à 32 caractères hexadécimaux). S’il est fourni, cette trace fera partie de la trace indiquée.

parentSpanId?:

string

ID du span parent à utiliser pour cette exécution (1 à 16 caractères hexadécimaux). S’il est fourni, le span racine sera créé comme enfant de ce span.

tags?:

string[]

Tags à appliquer à cette trace. Libellés de chaîne permettant de catégoriser et de filtrer les traces.

telemetry?:

TelemetrySettings

Paramètres de collecte de la télémétrie OTLP pendant le streaming (et non du traçage).

TelemetrySettings

isEnabled?:

boolean

Active ou désactive la télémétrie. Désactivée par défaut pendant la phase expérimentale.

recordInputs?:

boolean

Active ou désactive l’enregistrement des entrées. Activé par défaut. Vous pouvez le désactiver afin de ne pas enregistrer d’informations sensibles.

recordOutputs?:

boolean

Active ou désactive l’enregistrement des sorties. Activé par défaut. Vous pouvez le désactiver afin de ne pas enregistrer d’informations sensibles.

functionId?:

string

Identifiant de cette fonction. Sert à regrouper les données de télémétrie par fonction.

modelSettings?:

CallSettings

Model-specific settings like temperature, maxOutputTokens, topP, etc. These settings control how the language model generates responses.

temperature?:

number

Controls randomness in generation (0-2). Higher values make output more random.

maxOutputTokens?:

number

Maximum number of tokens to generate in the response. Note: Use maxOutputTokens (not maxTokens) as per AI SDK v5 convention.

maxRetries?:

number

Maximum number of retry attempts for failed requests.

topP?:

number

Nucleus sampling parameter (0-1). Controls diversity of generated text.

topK?:

number

Top-k sampling parameter. Limits vocabulary to k most likely tokens.

presencePenalty?:

number

Penalty for token presence (-2 to 2). Reduces repetition.

frequencyPenalty?:

number

Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.

stopSequences?:

string[]

Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.

structuredOutput?:

StructuredOutputOptions

Configuration permettant de générer une sortie structurée typée à partir du résultat du réseau.

StructuredOutputOptions

schema:

ZodSchema | JSONSchema7

Schéma par rapport auquel valider la sortie. Peut être un schéma Zod ou JSON Schema.

model?:

MastraModelConfig

Modèle à utiliser pour générer la sortie structurée. Utilise par défaut le modèle de l’Agent.

instructions?:

string

Instructions personnalisées pour générer la sortie structurée.

runId?:

string

ID unique de cette exécution de génération. Utile pour le suivi et le débogage.

requestContext?:

RequestContext

Contexte de requête destiné à l’injection de dépendances et aux informations contextuelles.

traceId?:

string

ID de trace associé à cette exécution lorsque le traçage est activé. Utilisez-le pour corréler les journaux et déboguer le flux d’exécution.

spanId?:

string

ID du span racine associé à cette exécution lorsque le traçage est activé. Utilisez-le pour la recherche et la corrélation au niveau du span.

onStepFinish?:

(event: any) => Promise<void> | void

Fonction de rappel déclenchée après chaque étape du LLM au cours de l’exécution d’un sous-Agent. Elle reçoit les détails de l’étape, notamment le motif de fin et l’utilisation des tokens.

onError?:

({ error }: { error: Error | string }) => Promise<void> | void

Fonction de rappel déclenchée lorsqu’une erreur survient pendant l’exécution d’un sous-Agent.

Valeurs renvoyées

stream:

MastraAgentNetworkStream<NetworkChunkType>

Flux personnalisé qui étend ReadableStream<NetworkChunkType> avec des propriétés supplémentaires propres au réseau

status:

Promise<RunStatus>

Promesse qui se résout avec l’état actuel d’exécution du Workflow

result:

Promise<WorkflowResult<TState, TOutput, TSteps>>

Promesse qui se résout avec le résultat final du Workflow

usage:

Promise<{ promptTokens: number; completionTokens: number; totalTokens: number }>

Promesse qui se résout avec les statistiques d’utilisation des tokens

object:

Promise<OUTPUT | undefined>

Promesse qui se résout avec l’objet de sortie structurée. Disponible uniquement lorsque l’option structuredOutput est fournie. Elle se résout avec undefined si aucun schéma n’a été indiqué.

objectStream:

ReadableStream<Partial<OUTPUT>>

Flux d’objets partiels pendant la génération de la sortie structurée. Utile pour diffuser les résultats partiels à mesure qu’ils sont générés.

Sortie structurée

Lorsque vous avez besoin de résultats typés et validés provenant de votre réseau, utilisez l’option structuredOutput. Le réseau génère une réponse correspondant à votre schéma une fois la tâche terminée.

import { z } from 'zod'

const resultSchema = z.object({
  summary: z.string().describe('A brief summary of the findings'),
  recommendations: z.array(z.string()).describe('List of recommendations'),
  confidence: z.number().min(0).max(1).describe('Confidence score'),
})

const stream = await agent.network('Research AI trends and summarize', {
  structuredOutput: {
    schema: resultSchema,
  },
})

// Consume the stream
for await (const chunk of stream) {
  // Handle streaming events
}

// Get the typed result
const result = await stream.object
// result is typed as { summary: string; recommendations: string[]; confidence: number }
console.log(result?.summary)
console.log(result?.recommendations)

Diffusion d’objets partiels

Vous pouvez également diffuser les objets partiels à mesure qu’ils sont générés :

const stream = await agent.network('Analyze data', {
  structuredOutput: { schema: resultSchema },
})

// Stream partial objects
for await (const partial of stream.objectStream) {
  console.log('Partial result:', partial)
}

// Get final result
const final = await stream.object

Types de fragments

Lors de l’utilisation d’une sortie structurée, des types de fragments supplémentaires sont émis :

• network-object : émis avec les objets partiels pendant la diffusion en continu
• network-object-result : émis avec l’objet structuré final

Interrompre un réseau

Utilisez abortSignal pour annuler un réseau en cours d’exécution. Lors de l’interruption, le réseau arrête le routage, annule toute exécution en cours de sous-Agent, de Tool ou de Workflow et n’enregistre pas les résultats partiels dans la mémoire.

const controller = new AbortController()

// Abort after 30 seconds
setTimeout(() => controller.abort(), 30_000)

const stream = await agent.network('Research this topic thoroughly', {
  abortSignal: controller.signal,
  onAbort: ({ primitiveType, primitiveId, iteration }) => {
    console.log(`Aborted ${primitiveType} "${primitiveId}" at iteration ${iteration}`)
  },
})

for await (const chunk of stream) {
  if (
    chunk.type === 'routing-agent-abort' ||
    chunk.type === 'agent-execution-abort' ||
    chunk.type === 'tool-execution-abort' ||
    chunk.type === 'workflow-execution-abort'
  ) {
    console.log('Network was aborted')
  }
}