Políticas de permisos

Las "permission policies" (políticas de permisos) controlan si las herramientas ejecutadas por el servidor (el conjunto de herramientas del agente predefinido y el conjunto de herramientas de MCP) se ejecutan automáticamente, esperan tu aprobación o hacen que el servidor evalúe cada llamada. Las herramientas personalizadas las ejecuta tu aplicación y las controlas tú, por lo que no están sujetas a 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 del agente usa always_allow de forma predeterminada, y los conjuntos de herramientas de MCP usan always_ask de forma predeterminada.

Una política de permisos controla cuándo se ejecuta una herramienta habilitada. Para quitar una herramienta del agente por completo, desactívala en su lugar. Consulta Desactivar herramientas específicas.

Establecer una política para un conjunto de herramientas

Estableces las políticas de permisos en la configuración tools del agente cuando creas el agente, 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 del agente

Al crear un agente, puedes aplicar una política a todas las herramientas de agent_toolset_20260401 usando default_config.permission_policy:

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
---

default_config es opcional. Si lo omites, el conjunto de herramientas del agente se habilita con la política de permisos predeterminada, always_allow.

Permisos del conjunto de herramientas de MCP

Los conjuntos de herramientas de MCP usan always_ask de forma predeterminada. Esto garantiza que las nuevas herramientas agregadas 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 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 apply agent.md

---
name: Dev Assistant
model: claude-opus-5-5
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
---

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 del agente se enumeran en Herramientas disponibles. Este ejemplo permite el conjunto de herramientas del agente completo de forma predeterminada, pero requiere confirmación antes de que se ejecute cualquier comando bash:

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_allow
    configs:
      - name: bash
        permission_policy:
          type: always_ask
---

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

Deja que el servidor evalúe cada llamada con auto

Con la política de permisos auto, el servidor evalúa cada llamada antes de que se ejecute. Como la evaluación considera la herramienta, la entrada de la llamada y el contenido de la sesión hasta ese momento, el servidor puede tratar de forma diferente dos llamadas a la misma herramienta. Cada llamada tiene uno de tres resultados:

• La llamada se ejecuta. Cuando el servidor determina que la llamada es segura, la herramienta se ejecuta como lo haría con always_allow.
• La llamada se deniega. Cuando el servidor evalúa la llamada como de alto riesgo, la herramienta no se ejecuta. El agente recibe un resultado de herramienta de error con el contenido Permission to use {tool_name} has been denied. y is_error: true. La sesión sigue ejecutándose, y tu cliente no puede anular la denegación.
• La llamada se pausa para esperar tu aprobación. Cuando el servidor no llega a ninguna determinación, la sesión se pausa como lo hace con always_ask. Consulta Responder a solicitudes de confirmación.

Para activar auto, establece permission_policy en {"type": "auto"}. Va en los mismos dos lugares que las demás políticas: el default_config de un conjunto de herramientas para todo el conjunto, o una entrada de configs para una sola herramienta. Tanto el conjunto de herramientas del agente como los conjuntos de herramientas de MCP lo aceptan. Ningún conjunto de herramientas usa auto de forma predeterminada.

El siguiente ejemplo establece auto como valor predeterminado para el conjunto de herramientas del agente y para el conjunto de herramientas de MCP github, y anula bash a always_ask:

ant apply agent.md

---
name: Ops Agent
model: claude-opus-5-5
mcp_servers:
  - type: url
    name: github
    url: https://mcp.example.com/github
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: auto
    configs:
      - name: bash
        permission_policy:
          type: always_ask
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: auto
---

Lo que publicas en los eventos user.message cuenta como tu intención, y puede llevar al servidor a permitir una llamada que de otro modo denegaría. El servidor no lee la intención de un resultado de herramienta, una página web obtenida, la respuesta de un servidor MCP ni un mensaje entre hilos de sesión. Evalúa ese contenido, pero no toma instrucciones de él. El servidor evalúa algunas llamadas como de alto riesgo sin importar quién lo pida. Si retransmites entradas no confiables de usuarios finales en eventos user.message, el servidor también lee esa entrada como tu intención, y puede lograr que se permita una llamada. Configura always_ask en las herramientas que no dejarías que ese usuario final ejecutara sin revisión.

Ver cómo se evaluó cada llamada

Con cualquier política de permisos, cada evento agent.tool_use y agent.mcp_tool_use incluye evaluated_permission, el resultado de la verificación de permisos de la llamada: "allow", "ask" o "deny". La mayoría de los eventos también incluyen un objeto evaluation cuyo type nombra la política que produjo ese resultado. Con auto, el objeto también registra la determinación del servidor, además de un reason_code cuando el resultado es ask o deny.

Por ejemplo, cuando bash está bajo auto y el servidor evalúa una llamada como de alto riesgo, la llamada denegada aparece en el flujo de eventos de la siguiente manera:

{
  "type": "agent.tool_use",
  "id": "sevt_01pqr...",
  "name": "bash",
  "input": {
    "command": "rm -rf /workspace/reports"
  },
  "evaluated_permission": "deny",
  "evaluation": {
    "type": "auto",
    "evaluated_permission": {
      "type": "deny",
      "reason_code": "high_risk"
    }
  },
  "processed_at": "2026-03-25T14:05:12Z"
}

El objeto evaluation adopta una de las formas de la siguiente tabla.

Cuando evaluation.type es "auto", su evaluated_permission.type anidado repite el evaluated_permission de nivel superior del evento, por lo que puedes leer el resultado desde cualquiera de los dos campos. Un reason_code es un valor para que tu cliente tome decisiones de ramificación y lo conserve en registros de auditoría, no un texto para mostrar a los usuarios finales.

evaluation está ausente en dos casos. Cuando el agente nombra una herramienta que no está habilitada en la sesión, el servidor deniega la llamada sin evaluar una política: el evento incluye evaluated_permission: "deny" y ningún evaluation. Los eventos registrados antes de que se introdujera evaluation también lo omiten: interprétalos como always_allow cuando evaluated_permission es "allow" y como always_ask cuando es "ask".

Escribe tu cliente para que tolere un evaluation.type o un reason_code que no reconozca. Los eventos agent.custom_tool_use no incluyen ninguno de los dos campos, porque las políticas de permisos no rigen las herramientas personalizadas.

Responder a solicitudes de confirmación

Una llamada a herramienta se evalúa como ask con una política always_ask, o con auto cuando el servidor no llega a ninguna determinación. Cuando eso sucede:

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

Si envías un user.tool_confirmation para un evento cuyo evaluated_permission no es ask, la API lo rechaza con un error 400. Eso incluye las llamadas que el servidor denegó con auto: tu cliente no puede anularlas.

Para responder de forma interactiva, usa ant beta:sessions connect, que muestra la llamada en espera y envía este evento cuando la permites o la deniegas. Consulta Conectarse a una sesión de Managed Agents desde tu terminal.

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 la sesión, o suscríbete a webhooks para recibir notificaciones cuando una sesión se pause en espera de una entrada.

# Permite 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 deniégala 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.",
        },
    ],
)

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 la sesión para ver el flujo completo.

Próximos pasos