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, ils ne sont donc 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 :

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Coding Assistant",
    "model": "claude-sonnet-4-6",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "default_config": {
          "permission_policy": {"type": "always_ask"}
        }
      }
    ]
  }')

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 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 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 :

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Dev Assistant",
    "model": "claude-sonnet-4-6",
    "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 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.

# Permettre l'exécution de l'outil
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "'$AGENT_TOOL_USE_EVENT_ID'",
        "result": "allow"
      }
    ]
  }'

# Ou le refuser avec une explication
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "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 si l'exécuter avant d'envoyer un user.custom_tool_result. Voir Flux d'événements de session pour le flux complet.