Configurer les sous-agents

Référence API : Subagent

Les champs que vous ne définissez pas, comme le modèle, les outils ou les hooks, sont hérités du parent, à quelques exceptions près, listées dans le tableau ci-dessous. name, description et instructions sont obligatoires. Un agents.Subagent ne définit que ce qui diffère :

Un champ que vous définissez remplace la valeur héritée.
Une liste vide supprime la valeur héritée ({} pour mcps). connectors=[] ne donne aucun connecteur au sous-agent.

Ce qu'un sous-agent hérite du parent

Élément	Ce qu'un sous-agent reçoit
`model`, `reasoning_effort`, `temperature`, `max_iterations`, `tools`, `hooks`, `mcps`, `connectors`, `skills`, `subagents`	Ceux du parent, sauf si vous les définissez
`builtins`	Ceux du parent ; chaque champ que vous définissez dans `agents.Builtins(...)` remplace ceux du parent
`sandbox_access`	Celui du parent, sauf si vous le définissez ; il s'applique dans la sandbox partagée par l'arborescence
Instructions	Les siennes, toujours
Mode d'autorisation et politique	Ceux de la racine, toujours
Sandbox	Celle de la racine, partagée par l'ensemble de l'arborescence
Politique relative aux sous-agents	Celle de la racine
`output_type`	Aucun : son résultat est sa réponse finale

Chaque session de sous-agent s'exécute en tant que l'utilisateur qui a démarré la session racine. Un sous-agent qui utilise l'identité de cet utilisateur, via all_connectors() ou des connecteurs avec la valeur par défaut run_as="auto", agit au nom de cet utilisateur, comme le font les mêmes connecteurs à la racine. Voir Connecteurs et MCP.

Un sous-agent démarre avec son seul message de tâche, sauf si le modèle du parent choisit d'y copier sa conversation. Demandez au parent d'inclure dans la tâche tout ce dont le sous-agent a besoin.

Donner à un sous-agent ses propres outils Python

Un sous-agent peut apporter des fonctions Python que le parent n'a pas. Passez-le dans Agent(subagents=[...]), comme sur Sous-agents :

from pydantic import BaseModel

from mistralai import agents


class DeployArgs(BaseModel):
    build_id: str


@agents.tool(name="deploy", description="Deploy one reviewed build.", input_schema=DeployArgs)
async def deploy(args: DeployArgs) -> dict[str, str]:
    return {"status": f"deployed {args.build_id}"}


deployer = agents.Subagent(
    name="deployer",
    description="Deploys a reviewed build.",
    instructions="Deploy only what you are asked to deploy.",
    tools=[deploy],
)

agent = agents.Agent(
    model="mistral-large-4",
    instructions="Review the build you are given. Ask the deployer to deploy it when the review passes.",
    subagents=[deployer],
)

from pydantic import BaseModel

from mistralai import agents


class DeployArgs(BaseModel):
    build_id: str


@agents.tool(name="deploy", description="Deploy one reviewed build.", input_schema=DeployArgs)
async def deploy(args: DeployArgs) -> dict[str, str]:
    return {"status": f"deployed {args.build_id}"}


deployer = agents.Subagent(
    name="deployer",
    description="Deploys a reviewed build.",
    instructions="Deploy only what you are asked to deploy.",
    tools=[deploy],
)

agent = agents.Agent(
    model="mistral-large-4",
    instructions="Review the build you are given. Ask the deployer to deploy it when the review passes.",
    subagents=[deployer],
)

Dans votre processus, les fonctions du sous-agent s'exécutent dans le même processus que celles du parent, et peuvent donc partager la mémoire du processus. Lorsque vous déployez avec Studio, en auto-hébergé ou en mode géré par Mistral, un sous-agent peut s'exécuter dans un autre processus. Conservez dans la sandbox ou dans un stockage externe l'état qu'un parent et ses sous-agents partagent.

Les noms d'outils sont partagés par l'ensemble de l'arborescence ; deux fonctions différentes ne peuvent donc pas porter le même nom, où que ce soit en son sein.

Permettre à un sous-agent de démarrer des sous-agents

Un Subagent peut embarquer ses propres subagents. Passez le coordinateur dans Agent(subagents=[...]) :

from mistralai import agents

coordinator = agents.Subagent(
    name="coordinator",
    description="Splits a product question across researchers.",
    instructions="Start one researcher per product, wait for every result, then summarize.",
    subagents=[
        agents.Subagent(
            name="researcher",
            description="Prices one product.",
            instructions="Answer with the product's price.",
        )
    ],
)

agent = agents.Agent(
    model="mistral-large-4",
    instructions="Ask the coordinator for the prices, then answer in one sentence.",
    subagents=[coordinator],
)

from mistralai import agents

coordinator = agents.Subagent(
    name="coordinator",
    description="Splits a product question across researchers.",
    instructions="Start one researcher per product, wait for every result, then summarize.",
    subagents=[
        agents.Subagent(
            name="researcher",
            description="Prices one product.",
            instructions="Answer with the product's price.",
        )
    ],
)

agent = agents.Agent(
    model="mistral-large-4",
    instructions="Ask the coordinator for the prices, then answer in one sentence.",
    subagents=[coordinator],
)

Le résultat de chaque chercheur remonte jusqu'au coordinateur, et celui du coordinateur jusqu'à la racine. Par défaut, l'arborescence a deux niveaux de profondeur : un chercheur ne peut donc pas ici démarrer ses propres sous-agents. Voir Limites.

Et après

Approbations sur l'ensemble des sous-agents : un seul handler répond pour toute l'arborescence.
Référence Subagent : chaque champ et son type.