Politiques d'autorisation

Les « permission policies » (politiques d'autorisation) contrôlent si les outils exécutés côté serveur (l'ensemble d'outils d'agent préconstruit et l'ensemble d'outils MCP) s'exécutent automatiquement ou attendent votre approbation. Les 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 beta:agents create < agent.yaml

name: Coding Assistant
model: claude-opus-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 beta:agents create < agent.yaml

name: Dev Assistant
model: claude-opus-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 beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_allow
    configs:
      - name: bash
        permission_policy:
          type: always_ask
YAML

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.

Répondre aux demandes de confirmation

Lorsque l'agent invoque un outil avec une politique always_ask :

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.

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
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}"

# Ou la refuser avec une explication
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{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