Políticas de permisos

Las políticas de permisos controlan si las herramientas ejecutadas por el servidor (el conjunto de herramientas del agente preintegrado y el conjunto de herramientas MCP) se ejecutan automáticamente o esperan tu aprobación. Las herramientas personalizadas se ejecutan por tu aplicación y están controladas por ti, por lo que no se rigen por políticas de permisos.

Todas las solicitudes de la API de Managed Agents requieren el encabezado beta managed-agents-2026-04-01. El SDK establece el encabezado beta automáticamente.

Tipos de políticas de permisos

Política	Comportamiento
`always_allow`	La herramienta se ejecuta automáticamente sin confirmación.
`always_ask`	La sesión emite un evento `session.status_idle` y espera un evento `user.tool_confirmation` antes de ejecutar.

Establecer una política para un conjunto de herramientas

Permisos del conjunto de herramientas del agente

Al crear un agente, puedes aplicar opcionalmente una política a cada herramienta en agent_toolset_20260401 usando default_config.permission_policy:

default_config es una configuración opcional. Si la omites, el conjunto de herramientas del agente se habilitará con la política de permisos predeterminada, always_allow.

Permisos del conjunto de herramientas MCP

Los conjuntos de herramientas MCP tienen always_ask por defecto. Esto asegura que las nuevas herramientas que se agreguen a un servidor MCP no se ejecuten en tu aplicación sin aprobación. Para aprobar automáticamente herramientas de un servidor MCP de confianza, establece permission_policy en la entrada mcp_toolset.

El mcp_server_name debe coincidir con el name referenciado en el array mcp_servers.

Este ejemplo conecta un servidor MCP de GitHub y permite que sus herramientas se ejecuten sin confirmación:

Anular la política de una herramienta individual

Usa el array configs para anular el valor predeterminado para herramientas individuales. Este ejemplo permite el conjunto completo de herramientas del agente por defecto pero requiere confirmación antes de que se ejecute cualquier comando bash:

Responder a solicitudes de confirmación

Cuando el agente invoca una herramienta con una política always_ask:

La sesión emite un evento agent.tool_use o agent.mcp_tool_use.
La sesión se pausa con un evento session.status_idle que contiene stop_reason: requires_action. Los IDs de eventos de bloqueo están en el array stop_reason.requires_action.event_ids.
Envía un evento user.tool_confirmation para cada uno, pasando el ID del evento en el parámetro tool_use_id. Establece result en "allow" o "deny". Usa deny_message para explicar un rechazo.
Una vez que se resuelven todos los eventos de bloqueo, la sesión vuelve a running.

Obtén más información sobre el manejo de eventos en la guía flujo de eventos de sesión.

Herramientas personalizadas

Las políticas de permisos no se aplican a las herramientas personalizadas. Cuando el agente invoca una herramienta personalizada, tu aplicación recibe un evento agent.custom_tool_use y es responsable de decidir si ejecutarla antes de enviar un user.custom_tool_result. Consulta Flujo de eventos de sesión para el flujo completo.

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

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

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

# Permitir que la herramienta se ejecute
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# O rechazarla con una explicación
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.",
        },
    ],
)