Skills

Un skill est un bloc d'instructions que l'agent charge à la demande. Vous écrivez le skill, un SKILL.md et les fichiers qui l'accompagnent ; le SDK place ses fichiers dans la sandbox et ne liste que son nom et sa description dans le prompt système. L'agent lit le corps de texte avec l'outil intégré skill.read lorsqu'il juge que le skill s'applique.

Utilisez un skill pour une procédure trop longue pour figurer dans instructions= et nécessaire seulement dans certains tours. La référence API recense chaque type de skill et ses options.

Le paramètre skills= de l'Agent accepte tous les skills de l'agent, dans une seule liste : les bundles de skills locaux et les skills du registre.

Écrivez chaque skill dans son propre répertoire, sous un répertoire skills/ dans votre projet, nommé d'après le skill — la structure qu'utilisent tous les agents de codage :

hello_agent/
├── main.py
└── skills/
    └── refund-policy/
        └── SKILL.md

hello_agent/
├── main.py
└── skills/
    └── refund-policy/
        └── SKILL.md

SKILL.md se compose d'un frontmatter YAML, puis du corps de texte :

---
name: refund-policy
description: The refund rules. Use when a customer asks for a refund.
---

Refund a customer only when the order is under 30 days old.

---
name: refund-policy
description: The refund rules. Use when a customer asks for a refund.
---

Refund a customer only when the order is under 30 days old.

description est ce que le modèle voit dans le prompt système ; écrivez-la donc sous la forme ce que c'est et quand l'utiliser. LocalSkillBundle.from_directory() lit un répertoire de ce type et en fait un bundle. L'exemple utilise BashkitSandbox : uv add "mistralai-agents[bashkit]".

import asyncio
from pathlib import Path

from mistralai import agents

SKILLS = Path(__file__).with_name("skills")  # resolve against __file__, not the working directory

agent = agents.Agent(
    model="mistral-large-4",
    name="refund-agent",
    environment=agents.BashkitSandbox(),
    skills=[
        agents.LocalSkillBundle.from_directory(SKILLS / "refund-policy"),
    ],
)


async def main() -> None:
    result = await agent.run("My order is 45 days old. Can I get a refund? Answer in one sentence.")
    if isinstance(result, agents.Completed):
        print(result.text)
        print([call.name for call in result.tool_calls])


if __name__ == "__main__":
    asyncio.run(main())

import asyncio
from pathlib import Path

from mistralai import agents

SKILLS = Path(__file__).with_name("skills")  # resolve against __file__, not the working directory

agent = agents.Agent(
    model="mistral-large-4",
    name="refund-agent",
    environment=agents.BashkitSandbox(),
    skills=[
        agents.LocalSkillBundle.from_directory(SKILLS / "refund-policy"),
    ],
)


async def main() -> None:
    result = await agent.run("My order is 45 days old. Can I get a refund? Answer in one sentence.")
    if isinstance(result, agents.Completed):
        print(result.text)
        print([call.name for call in result.tool_calls])


if __name__ == "__main__":
    asyncio.run(main())

No, since your order is 45 days old and refunds are only available for orders under 30 days old.
['skill.read']

No, since your order is 45 days old and refunds are only available for orders under 30 days old.
['skill.read']

Le modèle a vu la description du skill, a chargé son corps de texte avec skill.read et a appliqué la règle.

Quand le corps de texte n'a pas de répertoire, par exemple dans un test, construisez plutôt le bundle à partir d'objets agents.LocalSkillFile.

Un skill nécessite une sandbox capable de contenir ses fichiers, comme BashkitSandbox ou MistralSandbox : chaque skill y est un dossier, avec SKILL.md et tous les fichiers qui l'accompagnent, et le modèle lit et exécute ces fichiers comme tous les autres. La NoSandbox() par défaut ne peut pas contenir de fichiers : le SDK refuse donc les skills dessus avant tout appel au modèle.

Un skill du registre est un skill stocké dans le registre de l'IA Mistral et identifié par son UUID. Passez-le dans skills=, dans la même liste que vos skills locaux :

import uuid
from pathlib import Path

from mistralai import agents

SKILLS = Path(__file__).with_name("skills")

agent = agents.Agent(
    model="mistral-large-4",
    environment=agents.BashkitSandbox(),
    skills=[
        agents.LocalSkillBundle.from_directory(SKILLS / "refund-policy"),
        agents.RegistrySkill(id=uuid.UUID("0199c5e1-8a3b-7d42-9f10-3c5e7a2b1d84"), version=3),
    ],
)

import uuid
from pathlib import Path

from mistralai import agents

SKILLS = Path(__file__).with_name("skills")

agent = agents.Agent(
    model="mistral-large-4",
    environment=agents.BashkitSandbox(),
    skills=[
        agents.LocalSkillBundle.from_directory(SKILLS / "refund-policy"),
        agents.RegistrySkill(id=uuid.UUID("0199c5e1-8a3b-7d42-9f10-3c5e7a2b1d84"), version=3),
    ],
)

Définissez version= : la session refuse un skill du registre sans version, chaque session exécute donc la version exacte que vous indiquez. Si le SDK ne peut pas récupérer le skill, la session ne s'ouvre pas. Un agent déployé ne voit que les skills partagés avec son espace de travail : partagez chaque skill du registre avec l'espace de travail avant de déployer.

Pour mettre à disposition tous les skills du registre accessibles à l'utilisateur de la session, ajoutez agents.all_registry_skills() à skills=. Chaque skill ajoute des tokens au prompt ; désignez donc ceux dont vous avez besoin comme des entrées RegistrySkill quand ils sont nombreux. Ses options figurent dans la référence API.

agents deploy construit le commit que vous avez poussé : un répertoire skills/ commité est donc livré avec lui et n'a pas besoin de son propre COPY. Si vous l'excluez dans .dockerignore, ou si vous ne le committez pas, from_directory() lève une erreur au démarrage de l'agent déployé.

Sortie structurée : récupérez la réponse de l'agent sous forme de modèle Pydantic.