Políticas de permisos

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



Tipos de políticas de permisos

Cada tipo de conjunto de herramientas tiene su propio valor predeterminado: el conjunto de herramientas de agente usa always_allow de forma predeterminada, y los conjuntos de herramientas MCP usan always_ask de forma predeterminada.

Una política de permisos controla cuándo se ejecuta una herramienta habilitada. Para eliminar una herramienta del agente por completo, deshabilítala en su lugar. Consulta Deshabilitar herramientas específicas.



Establecer una política para un conjunto de herramientas

Estableces las políticas de permisos en la configuración de tools del agente cuando lo creas, y puedes cambiarlas más adelante actualizando el agente. Las sesiones en ejecución conservan la configuración del conjunto de herramientas con la que fueron creadas. Las actualizaciones se aplican a las sesiones creadas posteriormente.



Permisos del conjunto de herramientas de agente

Al crear un agente, puedes aplicar una política a todas las herramientas de agent_toolset_20260401 usando 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 es opcional. Si lo omites, el conjunto de herramientas de agente se habilita con la política de permisos predeterminada, always_allow.



Permisos del conjunto de herramientas MCP

Los conjuntos de herramientas MCP usan always_ask de forma predeterminada. Esto garantiza que las nuevas herramientas añadidas a un servidor MCP no se ejecuten en tu aplicación sin aprobación. Para aprobar automáticamente las herramientas de un servidor MCP de confianza, establece default_config.permission_policy en la entrada mcp_toolset.

El valor de mcp_server_name debe coincidir con el name de un servidor en el arreglo mcp_servers.

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

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



Anular la política de una herramienta individual

Usa el arreglo configs para anular el valor predeterminado de herramientas individuales. Los valores de name para el conjunto de herramientas de agente se enumeran en Herramientas disponibles. Este ejemplo permite todo el conjunto de herramientas de agente de forma predeterminada, pero requiere confirmación antes de que se ejecute cualquier comando 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

Pasa esta configuración de tools en la solicitud de creación del agente (la pestaña CLI muestra el comando completo). Los conjuntos de herramientas MCP admiten las mismas anulaciones por herramienta, con name establecido al nombre de la herramienta reportado por el servidor MCP. Consulta Configurar qué herramientas MCP están disponibles.



Responder a solicitudes de confirmación

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

1. La sesión emite un evento agent.tool_use o agent.mcp_tool_use.
2. La sesión se pausa con un evento session.status_idle cuyo stop_reason.type es requires_action. Los IDs de los eventos bloqueantes están en el arreglo stop_reason.event_ids. La sesión espera indefinidamente una respuesta.
3. Envía un evento user.tool_confirmation por cada evento bloqueante, pasando el ID del evento en el parámetro tool_use_id. Establece result en "allow" o "deny". Usa deny_message para explicar una denegación. Puedes enviar varias confirmaciones en una sola solicitud de events.
4. Una vez que todos los eventos bloqueantes se resuelven, la sesión vuelve al estado running. Las herramientas permitidas se ejecutan. Las herramientas denegadas no se ejecutan, y el agente recibe un resultado de herramienta que indica que la llamada fue rechazada, incluyendo tu deny_message.

En los siguientes ejemplos, los IDs de los eventos de uso de herramientas provienen del arreglo stop_reason.event_ids del evento session.status_idle. Obtén más información sobre cómo recibir eventos en la guía Flujo de eventos de sesión, o suscríbete a webhooks para recibir notificaciones cuando una sesión se pause esperando entrada.

# Permitir que la herramienta se ejecute
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}"

# O denegarla con una explicación
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.}"



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 de vuelta un user.custom_tool_result. Consulta Flujo de eventos de sesión para ver el flujo completo.



Próximos pasos