Politiques de permission

Les politiques de permission contrôlent si les outils exécutés par le 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, donc ils ne sont pas régis par les politiques de permission.

Types de politiques de permission

Définir une politique pour un ensemble d'outils

Permissions de l'ensemble d'outils d'agent

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

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

default_config est un paramètre optionnel. Si vous l'omettez, l'ensemble d'outils d'agent sera activé avec la politique de permission par défaut, always_allow.

Permissions de l'ensemble d'outils MCP

Les ensembles d'outils MCP sont 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 permission_policy sur l'entrée mcp_toolset.

Le mcp_server_name doit correspondre au name référencé 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-7
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 une politique d'outil individuelle

Utilisez le tableau configs pour remplacer la valeur par défaut pour les outils individuels. Cet exemple permet l'ensemble complet d'outils d'agent par défaut mais nécessite une confirmation avant l'exécution de toute commande bash :

tools = [
    {
        "type": "agent_toolset_20260401",
        "default_config": {
            "permission_policy": {"type": "always_allow"},
        },
        "configs": [
            {
                "name": "bash",
                "permission_policy": {"type": "always_ask"},
            },
        ],
    },
]

Répondre aux demandes de confirmation

Quand 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 s'interrompt avec un événement session.status_idle contenant stop_reason: requires_action. Les ID d'événements bloquants se trouvent dans le tableau stop_reason.requires_action.event_ids.
3. Envoyez un événement user.tool_confirmation pour chacun, en passant l'ID d'événement dans le paramètre tool_use_id. Définissez result sur "allow" ou "deny". Utilisez deny_message pour expliquer un refus.
4. Une fois que tous les événements bloquants sont résolus, la session revient à running.

En savoir plus sur la gestion des événements dans le guide flux d'événements de session.

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

# Ou le 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 de permission ne s'appliquent pas aux outils personnalisés. Quand 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 d'envoyer un user.custom_tool_result. Voir Flux d'événements de session pour le flux complet.