Agent

L'Agent et ses composants : paramètres du modèle, sous-agents, permissions, skills, secrets et masquage.

Guides : Qu'est-ce qu'un agent, Configurer l'agent, Secrets, Les mécanismes de contrôle, Skills et Sous-agents.

class Agent(
    *,
    model: str,
    instructions: str | None = None,
    provider: str = 'mistral',
    name: str = 'default_agent',
    max_iterations: int | None = None,
    first_output_timeout_seconds: float | None = None,
    builtins: Builtins | None = None,
    permission_mode: PermissionMode = 'auto',
    permission_policy: PermissionPolicy | None = None,
    auto_compact_threshold: int | None = None,
    description: str | None = None,
    reasoning_effort: Literal['off', 'none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] | None = None,
    temperature: float | None = None,
    output_type: type[BaseModel] | None = None,
    subagents: Sequence[Subagent] = (),
    subagent_policy: SubagentPolicy | None = None,
    tool_errors: Literal['hide', 'show', 'raise'] = 'hide',
    tools: Sequence[PythonTool[..., Any] | ClientTool[..., Any] | Callable[..., Any]] | None = None,
    environment: Sandbox | None = None,
    connectors: Sequence[Connector | AllConnectors] | None = None,
    mcps: dict[str, RemoteMCP] | None = None,
    skills: Sequence[LocalSkillBundle | RegistrySkill | SandboxWorkspaceSkills | AllRegistrySkills] | None = None,
    hooks: Sequence[Hook] | None = None,
    guardrails: Sequence[Hook] | None = None,
    secrets: Mapping[str, MistralSecret] | None = None,
    redaction: redaction.Redaction | None = None,
)

class Agent(
    *,
    model: str,
    instructions: str | None = None,
    provider: str = 'mistral',
    name: str = 'default_agent',
    max_iterations: int | None = None,
    first_output_timeout_seconds: float | None = None,
    builtins: Builtins | None = None,
    permission_mode: PermissionMode = 'auto',
    permission_policy: PermissionPolicy | None = None,
    auto_compact_threshold: int | None = None,
    description: str | None = None,
    reasoning_effort: Literal['off', 'none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] | None = None,
    temperature: float | None = None,
    output_type: type[BaseModel] | None = None,
    subagents: Sequence[Subagent] = (),
    subagent_policy: SubagentPolicy | None = None,
    tool_errors: Literal['hide', 'show', 'raise'] = 'hide',
    tools: Sequence[PythonTool[..., Any] | ClientTool[..., Any] | Callable[..., Any]] | None = None,
    environment: Sandbox | None = None,
    connectors: Sequence[Connector | AllConnectors] | None = None,
    mcps: dict[str, RemoteMCP] | None = None,
    skills: Sequence[LocalSkillBundle | RegistrySkill | SandboxWorkspaceSkills | AllRegistrySkills] | None = None,
    hooks: Sequence[Hook] | None = None,
    guardrails: Sequence[Hook] | None = None,
    secrets: Mapping[str, MistralSecret] | None = None,
    redaction: redaction.Redaction | None = None,
)

Un agent : un modèle et ses instructions, avec les outils, la sandbox, les connecteurs, les serveurs MCP, les skills, les hooks et les sous-agents qu'il peut utiliser.

Agent.run() exécute un tour dans une nouvelle session, Agent.start_session() démarre une session pour plusieurs tours et Agent.session(session_id) associe un handle à une session existante. Agent.load_from() donne accès à un agent que vous avez déployé.

async def run(
    content: str | Sequence[TextContentBlock | ImageContentBlock | Mapping[str, Any]],
    *,
    output_type: type[BaseModel] | None = None,
    on_approval: ApprovalHandler | None = None,
    on_sign_in: Callable[[OpenSignIn], SignInAnswer | Awaitable[SignInAnswer]] | None = None,
    on_client_tool: Callable[[ClientToolCall], Any] | ClientToolAnswers | None = None,
    on_event: Callable[[Event], Awaitable[None] | None] | None = None,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> TurnState[Any] | Busy

async def run(
    content: str | Sequence[TextContentBlock | ImageContentBlock | Mapping[str, Any]],
    *,
    output_type: type[BaseModel] | None = None,
    on_approval: ApprovalHandler | None = None,
    on_sign_in: Callable[[OpenSignIn], SignInAnswer | Awaitable[SignInAnswer]] | None = None,
    on_client_tool: Callable[[ClientToolCall], Any] | ClientToolAnswers | None = None,
    on_event: Callable[[Event], Awaitable[None] | None] | None = None,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> TurnState[Any] | Busy

Démarre une session, y exécute un tour et renvoie le résultat de ce tour.

Le résultat est une valeur, jamais une exception levée : Completed, Blocked, Interrupted, Failed, Running ou UnknownOutcome pour un résultat ajouté après votre version du SDK. Avec output_type=T, il s'agit d'un TurnState[T]. Ses champs session_id et turn_id permettent d'accéder à nouveau à la session et au tour, comme dans agent.session(state.session_id).

Sur un agent déployé, output_type analyse uniquement la réponse, et le modèle reçoit le format de l'agent déployé. output vaut InvalidOutput si la réponse ne passe pas la validation, et None si le tour s'est terminé prématurément.

Un callback sans gestionnaire, ou dont le gestionnaire renvoie KeepCallbackOpen(), fait renvoyer Blocked à l'exécution. Répondez-y avec agent.session(state.session_id).turn(state.turn_id).answer(cb.id, ...). Si un gestionnaire d'approbation ou de connexion lève une erreur, l'exécution lève cette erreur. Un gestionnaire d'approbation qui renvoie toute autre valeur, y compris None, lève SdkError. Un gestionnaire de connexion qui renvoie None, KeepCallbackOpen() ou une réponse omettant une source lève SdkError. Une réponse d'outil client qui ne peut pas être envoyée lève ClientToolAnswerError. Dans chaque cas, le callback reste ouvert et le tour continue de s'exécuter. Une réponse d'outil client ou un gestionnaire on_client_tool qui lève une erreur suit le paramètre tool_errors de l'agent : par défaut, le modèle reçoit un message indiquant que l'appel a échoué et l'exécution se poursuit. Avec "raise", l'exécution lève l'erreur et l'appel reste ouvert : le tour reste bloqué sur cet appel et la session n'accepte aucun nouveau tour jusqu'à l'expiration du callback (une heure par défaut).

def override(*, model: testing.ScriptedModel) -> Self

def override(*, model: testing.ScriptedModel) -> Self

Renvoie une copie de cet agent qui envoie ses appels au modèle à model. L'agent d'origine reste inchangé.

Appelez cette méthode sur un agent local : sur un agent déployé, elle lève SdkError.

async def start_session(
    *,
    history: Sequence[HistoryImportEntry] | None = None,
    session_inputs: Mapping[str, SessionInput] | None = None,
    agent: SessionAgentCustomization | Mapping[str, object] | None = None,
    idempotency_key: str | None = None,
    on_approval: ApprovalHandler | None = None,
    on_sign_in: Callable[[OpenSignIn], SignInAnswer | Awaitable[SignInAnswer]] | None = None,
    on_client_tool: Callable[[ClientToolCall], Any] | ClientToolAnswers | None = None,
) -> Session

async def start_session(
    *,
    history: Sequence[HistoryImportEntry] | None = None,
    session_inputs: Mapping[str, SessionInput] | None = None,
    agent: SessionAgentCustomization | Mapping[str, object] | None = None,
    idempotency_key: str | None = None,
    on_approval: ApprovalHandler | None = None,
    on_sign_in: Callable[[OpenSignIn], SignInAnswer | Awaitable[SignInAnswer]] | None = None,
    on_client_tool: Callable[[ClientToolCall], Any] | ClientToolAnswers | None = None,
) -> Session

Démarre une session et renvoie son handle.

Une session locale s'exécute dans ce processus jusqu'à l'arrêt de sa boucle d'événements, et son handle ne peut être réassocié à la session que dans cette boucle. Une session d'un agent déployé est conservée par Mistral, et son handle peut être réassocié depuis n'importe quel processus.

Un deuxième appel avec la même idempotency_key et les mêmes options renvoie la même session, même si elle exécute déjà un tour ou si elle est terminée. La même clé avec d'autres valeurs de session_inputs ou d'agent, ou depuis un agent dont les paramètres diffèrent, comme permission_mode, lève agents.SessionIdempotencyConflictError ; un autre history n'est pas vérifié et renvoie la première session. Générez la clé une fois par requête, par exemple sous forme d'UUID, et réutilisez-la uniquement pour les nouvelles tentatives de cette requête.

Les gestionnaires restent dans ce processus : ils ne font pas partie des paramètres de démarrage, donc la même idempotency_key accepte d'autres gestionnaires. Une réponse à un stub qui n'est pas un outil de cet agent, de ses mécanismes de contrôle et hooks, ou de ses sous-agents, lève SdkError avant le démarrage.

Le handle conserve le output_type de cet agent : session.run(), turn.get() et turn.result() l'utilisent pour analyser la sortie d'un Completed si aucun autre type n'est fourni.

def session(
    session_id: str,
    *,
    on_approval: ApprovalHandler | None = None,
    on_sign_in: Callable[[OpenSignIn], SignInAnswer | Awaitable[SignInAnswer]] | None = None,
    on_client_tool: Callable[[ClientToolCall], Any] | ClientToolAnswers | None = None,
) -> Session

def session(
    session_id: str,
    *,
    on_approval: ApprovalHandler | None = None,
    on_sign_in: Callable[[OpenSignIn], SignInAnswer | Awaitable[SignInAnswer]] | None = None,
    on_client_tool: Callable[[ClientToolCall], Any] | ClientToolAnswers | None = None,
) -> Session

Renvoie le handle d'une session de cet agent à partir de son identifiant. N'envoie aucune requête.

Pour un agent déployé, un identifiant qui n'est pas un UUID lève immédiatement SdkError. Un identifiant inconnu peut aussi être associé à un handle : la première requête via ce handle lève SessionNotFoundError. Le handle conserve le output_type de cet agent, comme celui de start_session(). Une réponse à un stub qui ne correspond pas à un outil de cet agent, de ses mécanismes de contrôle et hooks, ou de ses sous-agents lève SdkError ici.

Dans un bloc async with agents.local_runtime(journal_factory=...), une session locale enregistrée à cet emplacement par un processus précédent se rouvre à la première requête du handle et continue de s'exécuter dans ce processus jusqu'à la sortie du bloc. Elle doit appartenir à cet agent : une session avec d'autres outils, hooks, serveurs MCP, connecteurs ou une autre sandbox lève SessionConfigMismatchError, et une session qu'un autre processus maintient ouverte lève SessionInUseError.

@classmethod
def load_from(
    *,
    agent_name: str | None = None,
    agent_id: str | None = None,
    server_url: str | None = None,
    api_key: str | None = None,
    client: Client | None = None,
) -> Agent

@classmethod
def load_from(
    *,
    agent_name: str | None = None,
    agent_id: str | None = None,
    server_url: str | None = None,
    api_key: str | None = None,
    client: Client | None = None,
) -> Agent

Construit un handle à initialisation différée vers un agent déployé, à partir de son nom ou de son identifiant.

Passez exactement un des deux paramètres, agent_name ou agent_id, pour un agent déployé avec Studio, auto-hébergé ou géré par Mistral. Pour poursuivre une session, associez-lui un handle avec .session(session_id).

Sans client, server_url et api_key créent un client sans pool de connexions partagé : chaque session ouvre alors son propre pool, qui se ferme avec elle et sert la boucle d'événements qui l'a ouvert. Passez soit client, soit ces deux paramètres, mais pas les deux.

class Builtins(
    *,
    skills: bool = True,
    subagents: bool = True,
    programmatic_tool_calling: bool | ProgrammaticToolCallingConfig = True,
    background_processes: bool | None = None,
)

class Builtins(
    *,
    skills: bool = True,
    subagents: bool = True,
    programmatic_tool_calling: bool | ProgrammaticToolCallingConfig = True,
    background_processes: bool | None = None,
)

Fonctionnalités intégrées de l'agent. Toutes sont activées par défaut ; définissez un champ sur False pour le désactiver.

Les outils de fichiers et de shell ne figurent pas ici : ils dépendent du niveau access de la sandbox.

@classmethod
def none() -> Self

@classmethod
def none() -> Self

Aucune fonctionnalité intégrée. Avec NoSandbox, la valeur par défaut, le modèle ne voit que vos outils.

Une sandbox fournit toujours les outils de fichiers et de shell autorisés par son niveau access.

class ProgrammaticToolCallingConfig(*, sleep: bool = True)

class ProgrammaticToolCallingConfig(*, sleep: bool = True)

Options de l'appel programmatique d'outils. Les passer active cette fonctionnalité.

class SessionAgentCustomization(
    *,
    additional_instructions: str = '',
    model: str | None = None,
    reasoning_effort: Literal['off', 'none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] | None = None,
)

class SessionAgentCustomization(
    *,
    additional_instructions: str = '',
    model: str | None = None,
    reasoning_effort: Literal['off', 'none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] | None = None,
)

Remplacement des paramètres d'un agent pour une session : le paramètre agent= de Agent.start_session.

additional_instructions s'ajoute aux instructions de l'agent ; model et reasoning_effort remplacent ses valeurs par défaut pour la complétion. Un champ omis conserve la valeur de l'agent ; None pour model ou reasoning_effort, ainsi que les clés inconnues, lèvent une erreur de validation. agent= accepte aussi les mêmes clés dans un dictionnaire.

class Subagent(
    *,
    name: str,
    description: str,
    instructions: str,
    model: str | None = None,
    provider: str | None = None,
    reasoning_effort: Literal['off', 'none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] | None = None,
    temperature: float | None = None,
    max_iterations: int | None = None,
    first_output_timeout_seconds: float | None = None,
    auto_compact_threshold: int | None = None,
    tools: Sequence[PythonTool[..., Any] | ClientTool[..., Any] | Callable[..., Any]] | None = None,
    hooks: Sequence[Hook] | None = None,
    mcps: Mapping[str, RemoteMCP] | None = None,
    connectors: Sequence[Connector | AllConnectors] | None = None,
    skills: Sequence[LocalSkillBundle | RegistrySkill] | None = None,
    subagents: Sequence[Subagent] | None = None,
    builtins: Builtins | None = None,
    sandbox_access: Literal['none', 'files', 'full'] | None = None,
)

class Subagent(
    *,
    name: str,
    description: str,
    instructions: str,
    model: str | None = None,
    provider: str | None = None,
    reasoning_effort: Literal['off', 'none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] | None = None,
    temperature: float | None = None,
    max_iterations: int | None = None,
    first_output_timeout_seconds: float | None = None,
    auto_compact_threshold: int | None = None,
    tools: Sequence[PythonTool[..., Any] | ClientTool[..., Any] | Callable[..., Any]] | None = None,
    hooks: Sequence[Hook] | None = None,
    mcps: Mapping[str, RemoteMCP] | None = None,
    connectors: Sequence[Connector | AllConnectors] | None = None,
    skills: Sequence[LocalSkillBundle | RegistrySkill] | None = None,
    subagents: Sequence[Subagent] | None = None,
    builtins: Builtins | None = None,
    sandbox_access: Literal['none', 'files', 'full'] | None = None,
)

Un agent enfant que son parent démarre avec l'outil agents.spawn.

Un sous-agent s'exécute dans sa propre session, sous celle de son parent, avec l'identité de l'utilisateur qui a démarré la session racine. Il utilise la valeur du parent pour chaque champ laissé à None. Un champ que vous définissez remplace la valeur du parent, et une liste vide ne fournit aucun élément au sous-agent : aucune fusion n'est effectuée.

model, reasoning_effort et temperature suivent les mêmes règles que dans agents.Agent. provider nécessite aussi model. Le sous-agent n'hérite jamais du output_type du parent : son résultat est sa réponse finale.

Un sous-agent s'exécute toujours selon la politique et le mode d'autorisation de l'agent racine. Pour restreindre ses possibilités, donnez-lui moins d'outils.

Un sous-agent peut avoir des outils et des hooks que son parent n'a pas. Leurs fonctions s'exécutent au même endroit que celles du parent. Les noms d'outils sont partagés par toute l'arborescence : deux fonctions différentes ne peuvent donc pas porter le même nom, où qu'elles se trouvent dans celle-ci.

Connecteurs : connectors=[] n'en fournit aucun au sous-agent. Une liste accepte les mêmes éléments que Agent(connectors=...) : agents.connector(...) lui fournit exactement ces connecteurs, et agents.all_connectors(...) lui fournit tous les connecteurs que l'utilisateur peut utiliser.

builtins est le seul champ dont les valeurs sont fusionnées : chaque champ défini dans agents.Builtins(...) remplace la valeur du parent, et chaque champ omis la conserve. Par exemple, agents.Builtins(skills=False) désactive uniquement les skills. Désactiver programmatic_tool_calling nécessite aussi subagents=False. Un sous-agent qui définit ses propres skills ou sous-agents doit avoir la fonctionnalité intégrée correspondante activée. sandbox_access définit l'accès du sous-agent à la sandbox partagée par toute l'arborescence ; une arborescence sans sandbox n'accepte que "none".

skills accepte des bundles locaux et des skills du registre. Dans une sandbox qui stocke des fichiers, les skills propres au sous-agent sont écrits au démarrage de celui-ci. agents.all_registry_skills() est réservé à l'agent racine : un sous-agent qui ne définit pas skills utilise les skills de la racine.

Pour ajouter un outil à ceux du parent, passez la liste du parent et la liste étendue de l'enfant :

BASE = [lookup, search]
agent = agents.Agent(
    model="mistral-large-4",
    tools=BASE,
    subagents=[
        agents.Subagent(
            name="deployer",
            description="Deploys a reviewed build.",
            instructions="Deploy only what you are asked to deploy.",
            tools=[*BASE, deploy],
        )
    ],
)

BASE = [lookup, search]
agent = agents.Agent(
    model="mistral-large-4",
    tools=BASE,
    subagents=[
        agents.Subagent(
            name="deployer",
            description="Deploys a reviewed build.",
            instructions="Deploy only what you are asked to deploy.",
            tools=[*BASE, deploy],
        )
    ],
)

class SubagentPolicy(
    *,
    concurrent_child_turn_limit: int = 10,
    max_depth: int = 2,
    idle_message_starts: Literal['direct_children', 'none'] = 'direct_children',
)

class SubagentPolicy(
    *,
    concurrent_child_turn_limit: int = 10,
    max_depth: int = 2,
    idle_message_starts: Literal['direct_children', 'none'] = 'direct_children',
)

Limites applicables aux sous-agents d'une arborescence de sessions : la session racine et tous les sous-agents qu'elle contient.

Passez cette politique via Agent(subagent_policy=...). La politique de l'agent racine s'applique à tous ses sous-agents, et aucun sous-agent ne peut en augmenter les limites. Un agent qui possède des sous-agents sans politique explicite utilise les valeurs par défaut ci-dessous.

PermissionMode = Literal['auto', 'ask', 'deny']

PermissionMode = Literal['auto', 'ask', 'deny']

Définit les appels d'outils nécessitant une approbation : "auto" exécute chaque appel autorisé par la permission_policy de l'agent (tous les appels en l'absence de politique), "ask" ouvre une demande d'approbation pour chaque appel, et "deny" les refuse.

class PermissionPolicy(
    *,
    default: Literal['allow', 'deny', 'ask'],
    rules: tuple[PermissionRule, ...] = (),
)

class PermissionPolicy(
    *,
    default: Literal['allow', 'deny', 'ask'],
    rules: tuple[PermissionRule, ...] = (),
)

Règles d'autorisation ordonnées et décision par défaut pour les appels qui ne correspondent à aucune règle.

class PermissionRule(
    *,
    tools: tuple[str, ...],
    decision: Literal['allow', 'deny', 'ask'],
    allowlist: tuple[str, ...] = (),
    denylist: tuple[str, ...] = (),
    sensitive: tuple[str, ...] = (),
)

class PermissionRule(
    *,
    tools: tuple[str, ...],
    decision: Literal['allow', 'deny', 'ask'],
    allowlist: tuple[str, ...] = (),
    denylist: tuple[str, ...] = (),
    sensitive: tuple[str, ...] = (),
)

Définit si les appels des outils correspondant à tools sont exécutés, soumis à approbation ou refusés.

Une politique applique la première règle dont tools correspond à l'identifiant stable de l'outil appelé, par exemple client.deploy_service, et non au nom que voit le modèle ; un appel qui ne correspond à aucune règle utilise le default de la politique. Dans la règle qui s'applique :

1. Un motif de denylist correspond : refuser.
2. Un motif de sensitive correspond : demander une approbation.
3. allowlist n'est pas vide : autoriser si un motif correspond, sinon demander une approbation.
4. Sinon : la valeur decision de la règle.

Les motifs sont des glob patterns sensibles à la casse qui correspondent à l'ensemble du texte. Les motifs d'arguments correspondent aux arguments de l'appel sous forme de JSON avec des clés triées, avec ou sans espace après : et ,, par exemple '*"environment": "production"*'. Un motif tools sans espace de noms ni caractère générique, comme deploy_service, ne correspond à aucun outil et lève donc ValueError.

class RegistrySkill(*, id: UUID, version: int | None = None)

class RegistrySkill(*, id: UUID, version: int | None = None)

Un skill issu de votre espace de travail, dans Le registre de l'IA, identifié par son ID et, éventuellement, sa version.

class AllRegistrySkills()

class AllRegistrySkills()

Tous les skills présents dans Le registre de l'IA de votre espace de travail au démarrage de la session racine.

agents.all_registry_skills() renvoie cet objet.

def agents.all_registry_skills() -> AllRegistrySkills

def agents.all_registry_skills() -> AllRegistrySkills

Donnez à l'agent tous les skills présents dans Le registre de l'IA de votre espace de travail.

Un agent déployé reçoit les skills accessibles à l'utilisateur qui démarre la session. Une session locale utilise votre clé API Mistral. Les versions sont fixées au démarrage de la session, et chaque skill est téléchargé lors de sa première utilisation par l'agent. Un RegistrySkill présent dans la même liste conserve sa propre version.

class SandboxWorkspaceSkills(
    *,
    root: str | None = None,
    dirs: tuple[str, ...] = ('.agents/skills', '.vibe/skills'),
)

class SandboxWorkspaceSkills(
    *,
    root: str | None = None,
    dirs: tuple[str, ...] = ('.agents/skills', '.vibe/skills'),
)

Mettez à disposition les skills déjà présents dans la sandbox, par exemple ceux d'un dépôt cloné par un hook de sandbox.

Le SDK les recherche une seule fois, après l'exécution des hooks de sandbox et avant le premier tour. Un skill est un dossier contenant un SKILL.md dans l'un des répertoires de dirs, sous root ou dans un dépôt situé directement sous ce répertoire.

class LocalSkillBundle(*, files: list[LocalSkillFile] = [])

class LocalSkillBundle(*, files: list[LocalSkillFile] = [])

Un skill que l'agent emporte avec lui : les fichiers d'un dossier de skill sur votre machine.

Créez-en un avec LocalSkillBundle.from_directory(path).

@classmethod
def from_directory(path: str | Path) -> Self

@classmethod
def from_directory(path: str | Path) -> Self

Regroupez le contenu d'un répertoire de skill : son SKILL.md et tous les fichiers qui l'accompagnent.

class LocalSkillFile(*, path: str, content_base64: str, executable: bool = False)

class LocalSkillFile(*, path: str, content_base64: str, executable: bool = False)

Un fichier d'un LocalSkillBundle.

class MistralSecret(*, ref: str | None = None, worker_env: bool = False)

class MistralSecret(*, ref: str | None = None, worker_env: bool = False)

Un secret du gestionnaire de secrets Mistral.

Créez-le avec MistralSecret.workspace(NAME), ou omettez la référence avec MistralSecret() et associez-le au déploiement avec agents deploy --secret-binding NAME=secret:workspace:..., qui remplace également une référence existante. worker_env=True définit aussi le secret comme variable d'environnement là où vos outils Python s'exécutent, pour qu'ils puissent le lire ; sans cette option, le secret n'est transmis qu'aux destinations qui le désignent.

@classmethod
def workspace(name: str, *, worker_env: bool = False) -> Self

@classmethod
def workspace(name: str, *, worker_env: bool = False) -> Self

Le secret name de l'espace de travail dans le gestionnaire de secrets.

type Redaction = (
    redaction.RedactionPolicy
    | list[redaction.RedactionPolicy]
    | tuple[redaction.RedactionPolicy, ...]
)

type Redaction = (
    redaction.RedactionPolicy
    | list[redaction.RedactionPolicy]
    | tuple[redaction.RedactionPolicy, ...]
)

Ce qu'accepte Agent(redaction=...) : une RedactionPolicy ou une liste de politiques, appliquées dans l'ordre. [] désactive le masquage.

type RedactionPolicy = (
    OperationDataTransformer
    | Callable[[str, OperationDataValue], OperationDataValue | None]
)

type RedactionPolicy = (
    OperationDataTransformer
    | Callable[[str, OperationDataValue], OperationDataValue | None]
)

Une méthode de masquage des secrets et des données personnelles dans les traces de l'agent : une politique de masquage ou une fonction (key, value).

OperationDataTransformer représente une politique de masquage, telle que RegexRedactionPolicy : un objet dont la méthode transform renvoie la valeur à enregistrer, ou None pour l'omettre. OperationDataValue représente la valeur d'un champ de trace : une chaîne, un nombre, un booléen, des octets, None, ou une liste ou un dictionnaire de ces valeurs.

class RegexRedactionPolicy(
    patterns: Sequence[Pattern[str]] = redaction.DEFAULT_PII_SECRET_PATTERNS,
    *,
    safe_keys: frozenset[str] = redaction.DEFAULT_SAFE_ATTRIBUTE_KEYS,
    safe_key_patterns: Sequence[Pattern[str]] = redaction.DEFAULT_TOKEN_PATTERNS,
    redacted_value: str = '[REDACTED]',
)

class RegexRedactionPolicy(
    patterns: Sequence[Pattern[str]] = redaction.DEFAULT_PII_SECRET_PATTERNS,
    *,
    safe_keys: frozenset[str] = redaction.DEFAULT_SAFE_ATTRIBUTE_KEYS,
    safe_key_patterns: Sequence[Pattern[str]] = redaction.DEFAULT_TOKEN_PATTERNS,
    redacted_value: str = '[REDACTED]',
)

Remplace les correspondances de motifs, par exemple les clés API, les adresses e-mail et les numéros de carte, par [REDACTED] dans les traces de l'agent. Les valeurs des clés sûres sont analysées uniquement avec safe_key_patterns.

class AttributeRedactionPolicy(
    *,
    sensitive_keys: frozenset[str] = redaction.DEFAULT_SENSITIVE_ATTRIBUTE_KEYS,
    safe_keys: frozenset[str] = redaction.DEFAULT_SAFE_ATTRIBUTE_KEYS,
    sensitive_fragments: frozenset[str] = redaction.DEFAULT_SENSITIVE_ATTRIBUTE_FRAGMENTS,
    token_patterns: Sequence[Pattern[str]] = redaction.DEFAULT_TOKEN_PATTERNS,
    redact_non_primitive: bool = True,
    redacted_value: str = '[REDACTED]',
)

class AttributeRedactionPolicy(
    *,
    sensitive_keys: frozenset[str] = redaction.DEFAULT_SENSITIVE_ATTRIBUTE_KEYS,
    safe_keys: frozenset[str] = redaction.DEFAULT_SAFE_ATTRIBUTE_KEYS,
    sensitive_fragments: frozenset[str] = redaction.DEFAULT_SENSITIVE_ATTRIBUTE_FRAGMENTS,
    token_patterns: Sequence[Pattern[str]] = redaction.DEFAULT_TOKEN_PATTERNS,
    redact_non_primitive: bool = True,
    redacted_value: str = '[REDACTED]',
)

Masque intégralement les valeurs des champs de trace sensibles, tels que les messages et les arguments d'outils, et remplace les tokens dans les valeurs conservées.

class CallbackRedactionPolicy(
    mask_function: redaction.AttributeMaskCallback,
    *,
    recursive: bool = False,
)

class CallbackRedactionPolicy(
    mask_function: redaction.AttributeMaskCallback,
    *,
    recursive: bool = False,
)

Effectue le masquage avec votre fonction : elle reçoit la clé et la valeur de chaque champ et renvoie la valeur à conserver, ou None pour omettre le champ.

Avec recursive=True, la fonction reçoit chaque feuille d'une valeur structurée, par exemple le texte de chaque message, avec le nom du champ comme clé. Renvoyer None n'omet alors que cette feuille.

type AttributeMaskCallback = Callable[[str, OperationDataValue], OperationDataValue | None]

type AttributeMaskCallback = Callable[[str, OperationDataValue], OperationDataValue | None]

Une fonction de masquage : elle reçoit la clé et la valeur d'un champ et renvoie la valeur à conserver, ou None pour omettre le champ.