Configure subagents

API reference: Subagent

Fields you leave unset, such as the model, the tools or the hooks, are inherited from the parent, with the exceptions in the table below. name, description and instructions are required. An agents.Subagent sets only what differs:

• A field you set replaces the inherited value.
• An empty list clears it ({} for mcps). connectors=[] gives a subagent no connectors.

Every subagent session runs as the user who started the root session. A subagent that uses that user's identity, through all_connectors() or connectors with the default run_as="auto", acts on behalf of that user, as the same connectors on the root do. See Connectors and MCP.

A subagent starts with only its task message, unless the parent's model chooses to copy its conversation into it. Tell the parent to put everything the subagent needs in the task.

A subagent can bring Python functions that the parent does not have. Pass it in Agent(subagents=[...]), as on Subagents:

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],
)

In your process, the subagent's functions run in the same process as the parent's, so they can share process memory. When you deploy with Studio, self-hosted or Mistral-managed, a subagent can run in another process. Keep the state that a parent and its subagents share in the sandbox or in an external store.

Tool names are shared by the whole tree, so two different functions cannot use one name anywhere in it.

A Subagent can carry its own subagents. Pass the coordinator in 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],
)

Each researcher's result reaches the coordinator, and the coordinator's result reaches the root. By default the tree is two levels deep, so a researcher here cannot start subagents of its own. See Limits.

• Approvals across subagents: one handler answers the whole tree.
• Subagent reference: every field and its type.