Politiques d'autorisation

Les politiques d'autorisation déterminent si les outils exécutés côté serveur (l'ensemble d'outils d'agent préconfiguré 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 always_allow par défaut, et les ensembles d'outils MCP utilisent always_ask par défaut.

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 lors de sa création, 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 en utilisant default_config.permission_policy :

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-8
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
YAML

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 de l'ensemble d'outils MCP

Les ensembles d'outils MCP utilisent always_ask par défaut. 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 <<'YAML'
name: Dev Assistant
model: claude-opus-4-8
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
YAML



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 complet d'outils d'agent 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-4-8
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 d'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 signalé 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 d'é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 responsable de décider s'il faut l'exécuter avant de renvoyer un user.custom_tool_result. Consultez Flux d'événements de session pour le flux complet.



Prochaines étapes