Politiques d'autorisation

Les « permission policies » (politiques d'autorisation) déterminent si les outils exécutés par le serveur s'exécutent automatiquement, attendent votre approbation ou voient chaque appel évalué par le serveur. Ces outils sont le « toolset » (ensemble d'outils) d'agent prédéfini et l'ensemble d'outils MCP (« Model Context Protocol », ou MCP). Les « custom tools » (outils personnalisés) sont exécutés par votre application et contrôlés par vous. Ils ne sont donc pas régis par les politiques d'autorisation.

Types de politiques d'autorisation

Chaque type d'ensemble d'outils possède sa propre valeur par défaut : l'ensemble d'outils d'agent utilise par défaut always_allow, et les ensembles d'outils MCP utilisent par défaut always_ask.

Une politique d'autorisation contrôle quand un outil activé s'exécute. Pour retirer entièrement un outil de l'agent, désactivez-le plutôt. Consultez Désactiver des outils spécifiques.

Définir une politique pour un ensemble d'outils

Vous définissez les politiques d'autorisation dans la configuration tools de l'agent lorsque vous créez l'agent, et vous pouvez les modifier ultérieurement en mettant à jour l'agent. Les sessions en cours conservent la configuration d'ensemble d'outils avec laquelle elles ont été créées. Les mises à jour s'appliquent aux sessions créées par la suite.

Autorisations de l'ensemble d'outils d'agent

Lors de la création d'un agent, vous pouvez appliquer une politique à chaque outil de agent_toolset_20260401 à l'aide de default_config.permission_policy :

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
---

default_config est facultatif. Si vous l'omettez, l'ensemble d'outils d'agent est activé avec la politique d'autorisation par défaut, always_allow.

Autorisations des ensembles d'outils MCP

Les ensembles d'outils MCP utilisent par défaut always_ask. Cela garantit que les nouveaux outils ajoutés à un serveur MCP ne s'exécutent pas dans votre application sans approbation. Pour approuver automatiquement les outils d'un serveur MCP de confiance, définissez default_config.permission_policy sur l'entrée mcp_toolset.

Le mcp_server_name doit correspondre au name d'un serveur dans le tableau mcp_servers.

Cet exemple connecte un serveur MCP GitHub et permet à ses outils de s'exécuter sans confirmation :

ant apply agent.md

---
name: Dev Assistant
model: claude-opus-5-5
mcp_servers:
  - type: url
    name: github
    url: https://mcp.example.com/github
tools:
  - type: agent_toolset_20260401
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: always_allow
---

Remplacer la politique d'un outil individuel

Utilisez le tableau configs pour remplacer la valeur par défaut pour des outils individuels. Les valeurs name pour l'ensemble d'outils d'agent sont répertoriées dans Outils disponibles. Cet exemple autorise l'ensemble d'outils d'agent complet par défaut, mais exige une confirmation avant l'exécution de toute commande bash :

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_allow
    configs:
      - name: bash
        permission_policy:
          type: always_ask
---

Transmettez cette configuration tools dans la requête de création de l'agent (l'onglet CLI montre la commande complète). Les ensembles d'outils MCP prennent en charge les mêmes remplacements par outil, avec name défini sur le nom de l'outil indiqué par le serveur MCP. Consultez Configurer les outils MCP disponibles.

Laisser le serveur évaluer chaque appel avec auto

Avec la politique d'autorisation auto, le serveur évalue chaque appel avant son exécution. L'évaluation prend en compte l'outil, l'entrée de l'appel et le contenu de la session jusqu'à ce point. Le serveur peut donc traiter différemment deux appels au même outil. Chaque appel aboutit à l'un des trois résultats suivants :

• L'appel s'exécute. Lorsque le serveur détermine que l'appel est sûr, l'outil s'exécute comme il le ferait sous always_allow.
• L'appel est refusé. Lorsque le serveur évalue l'appel comme étant à haut risque, l'outil ne s'exécute pas. L'agent reçoit un résultat d'outil en erreur avec le contenu Permission to use {tool_name} has been denied. et is_error: true. La session continue de s'exécuter, et votre client ne peut pas annuler le refus.
• L'appel se met en pause pour obtenir votre approbation. Lorsque le serveur ne parvient à aucune conclusion, la session se met en pause comme sous always_ask. Consultez Répondre aux demandes de confirmation.

Pour activer auto, définissez permission_policy sur {"type": "auto"}. Cette valeur se place aux deux mêmes endroits que les autres politiques. Pour l'ensemble d'outils entier, utilisez le default_config de cet ensemble. Pour un seul outil, utilisez une entrée configs. L'ensemble d'outils d'agent et les ensembles d'outils MCP l'acceptent tous deux. Aucun ensemble d'outils n'utilise auto par défaut.

L'exemple suivant définit auto comme valeur par défaut pour l'ensemble d'outils d'agent et pour l'ensemble d'outils MCP github. Il remplace également la politique de bash par always_ask :

ant apply agent.md

---
name: Ops Agent
model: claude-opus-5-5
mcp_servers:
  - type: url
    name: github
    url: https://mcp.example.com/github
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: auto
    configs:
      - name: bash
        permission_policy:
          type: always_ask
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: auto
---

Ce que vous publiez dans les événements user.message compte comme votre intention. Cela peut amener le serveur à autoriser un appel qu'il refuserait autrement. Le serveur ne déduit pas d'intention des sources suivantes : un résultat d'outil, une page web récupérée, la réponse d'un serveur MCP ou un message entre fils de session. Il évalue ce contenu, mais n'en tire aucune instruction. Le serveur évalue certains appels comme étant à haut risque, quel que soit le demandeur. Si vous relayez des entrées non fiables d'utilisateurs finaux dans des événements user.message, le serveur interprète également ces entrées comme votre intention. Elles peuvent alors faire autoriser un appel. Configurez always_ask sur les outils que vous ne laisseriez pas cet utilisateur final exécuter sans vérification.

Voir comment chaque appel a été évalué

Quelle que soit la politique d'autorisation, chaque événement agent.tool_use et agent.mcp_tool_use comporte evaluated_permission. Ce champ indique le résultat de la vérification d'autorisation de l'appel : "allow", "ask" ou "deny". La plupart des événements comportent également un objet evaluation, dont le type nomme la politique qui a produit ce résultat. Sous auto, l'objet enregistre aussi la conclusion du serveur. Il inclut en outre un reason_code lorsque le résultat est ask ou deny.

Par exemple, lorsque bash est sous auto et que le serveur évalue un appel comme étant à haut risque, l'appel refusé apparaît ainsi dans le flux d'événements :

{
  "type": "agent.tool_use",
  "id": "sevt_01pqr...",
  "name": "bash",
  "input": {
    "command": "rm -rf /workspace/reports"
  },
  "evaluated_permission": "deny",
  "evaluation": {
    "type": "auto",
    "evaluated_permission": {
      "type": "deny",
      "reason_code": "high_risk"
    }
  },
  "processed_at": "2026-03-25T14:05:12Z"
}

L'objet evaluation prend l'une des formes du tableau suivant.

Lorsque evaluation.type vaut "auto", son champ imbriqué evaluated_permission.type reprend le evaluated_permission de niveau supérieur de l'événement. Vous pouvez donc lire le résultat dans l'un ou l'autre champ. Un reason_code est une valeur destinée à orienter la logique de votre client et à être conservée dans les journaux d'audit. Ce n'est pas un texte à afficher aux utilisateurs finaux.

evaluation est absent dans deux cas. Dans le premier, l'agent nomme un outil qui n'est pas activé dans la session. Le serveur refuse alors l'appel sans évaluer de politique : l'événement comporte evaluated_permission: "deny" et aucun evaluation. Dans le second, les événements ont été enregistrés avant l'introduction de evaluation et l'omettent donc. Interprétez-les comme always_allow lorsque evaluated_permission vaut "allow", et comme always_ask lorsqu'il vaut "ask".

Concevez votre client pour qu'il tolère un evaluation.type ou un reason_code qu'il ne reconnaît pas. Les événements agent.custom_tool_use ne comportent aucun de ces deux champs, car les politiques d'autorisation ne régissent pas les outils personnalisés.

Répondre aux demandes de confirmation

Un appel d'outil aboutit à ask dans deux cas : sous une politique always_ask, ou sous auto lorsque le serveur ne parvient à aucune conclusion. Dans ce cas :

1. La session émet un événement agent.tool_use ou agent.mcp_tool_use.
2. La session se met en pause avec un événement session.status_idle dont le stop_reason.type est requires_action. Les identifiants des événements bloquants se trouvent dans le tableau stop_reason.event_ids. La session attend indéfiniment une réponse.
3. Envoyez un événement user.tool_confirmation pour chaque événement bloquant, en transmettant l'identifiant de l'événement dans le paramètre tool_use_id. Définissez result sur "allow" ou "deny". Utilisez deny_message pour expliquer un refus. Vous pouvez envoyer plusieurs confirmations dans une seule requête events.
4. Une fois tous les événements bloquants résolus, la session repasse à l'état running. Les outils autorisés s'exécutent. Les outils refusés ne s'exécutent pas, et l'agent reçoit un résultat d'outil indiquant que l'appel a été rejeté, incluant votre deny_message.

Si vous envoyez un user.tool_confirmation pour un événement dont le evaluated_permission n'est pas ask, l'API le rejette avec une erreur 400. Cela inclut les appels que le serveur a refusés sous auto : votre client ne peut pas annuler ces refus.

Pour répondre de manière interactive, utilisez plutôt ant beta:sessions connect. Cette commande affiche l'appel en attente et envoie cet événement lorsque vous l'autorisez ou le refusez. Consultez Se connecter à une session Managed Agents depuis votre terminal.

Dans les exemples suivants, les identifiants des événements d'utilisation d'outils proviennent du tableau stop_reason.event_ids de l'événement session.status_idle. Apprenez-en davantage sur la réception des événements dans le guide Flux d'événements de session, ou abonnez-vous aux webhooks pour être averti lorsqu'une session se met en pause en attente d'une entrée.

# Autoriser l'exécution de l'outil
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# Ou la refuser avec une explication
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": mcp_tool_use_event.id,
            "result": "deny",
            "deny_message": "Don't create issues in the production project. Use the staging project.",
        },
    ],
)

Outils personnalisés

Les politiques d'autorisation ne s'appliquent pas aux outils personnalisés. Lorsque l'agent invoque un outil personnalisé, votre application reçoit un événement agent.custom_tool_use et est chargée de décider de l'exécuter ou non avant de renvoyer un user.custom_tool_result. Consultez Flux d'événements de session pour le flux complet.

Étapes suivantes