Policy di autorizzazione

Le "permission policies" (criteri di autorizzazione) controllano se gli strumenti eseguiti dal server (il "toolset" (set di strumenti) predefinito dell'agente e il set di strumenti MCP) vengono eseguiti automaticamente, attendono la tua approvazione oppure vengono valutati dal server chiamata per chiamata. I "custom tools" (strumenti personalizzati) vengono eseguiti dalla tua applicazione e sono sotto il tuo controllo, quindi i criteri di autorizzazione non si applicano a essi.

Tipi di policy di autorizzazione

Ogni tipo di toolset ha il proprio valore predefinito: il toolset dell'agente ha come valore predefinito always_allow, mentre i toolset MCP hanno come valore predefinito always_ask.

Una policy di autorizzazione controlla quando viene eseguito uno strumento abilitato. Per rimuovere completamente uno strumento dall'agente, disabilitalo invece. Consulta Disabilitare strumenti specifici.

Impostare una policy per un toolset

Imposti le policy di autorizzazione nella configurazione tools dell'agente quando crei l'agente, e puoi modificarle in seguito aggiornando l'agente. Le sessioni in esecuzione mantengono la configurazione del toolset con cui sono state create. Gli aggiornamenti si applicano alle sessioni create successivamente.

Autorizzazioni del toolset dell'agente

Quando crei un agente, puoi applicare una policy a ogni strumento in 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 è opzionale. Se lo ometti, il toolset dell'agente viene abilitato con la policy di autorizzazione predefinita, always_allow.

Autorizzazioni del toolset MCP

I toolset MCP hanno come valore predefinito always_ask. Questo garantisce che i nuovi strumenti aggiunti a un server MCP non vengano eseguiti nella tua applicazione senza approvazione. Per approvare automaticamente gli strumenti di un server MCP affidabile, imposta default_config.permission_policy sulla voce mcp_toolset.

Il mcp_server_name deve corrispondere al name di un server nell'array mcp_servers.

Questo esempio connette un server MCP GitHub e consente l'esecuzione dei suoi strumenti senza conferma:

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

Sovrascrivere la policy di un singolo strumento

Usa l'array configs per sovrascrivere il valore predefinito per singoli strumenti. I valori name per il toolset dell'agente sono elencati in Strumenti disponibili. Questo esempio consente l'intero toolset dell'agente per impostazione predefinita ma richiede una conferma prima dell'esecuzione di qualsiasi 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
---

Passa questa configurazione tools nella richiesta di creazione dell'agente (la scheda CLI mostra il comando completo). I toolset MCP supportano le stesse sovrascritture per singolo strumento, con name impostato sul nome dello strumento riportato dal server MCP. Consulta Configurare quali strumenti MCP sono disponibili.

Lasciare che il server valuti ogni chiamata con auto

Con il criterio di autorizzazione auto, il server valuta ogni chiamata prima che venga eseguita. Poiché la valutazione considera lo strumento, l'input della chiamata e il contenuto della sessione fino a quel momento, il server può trattare in modo diverso due chiamate allo stesso strumento. Ogni chiamata ha uno di tre esiti:

• La chiamata viene eseguita. Quando il server determina che la chiamata è sicura, lo strumento viene eseguito come farebbe con always_allow.
• La chiamata viene negata. Quando il server valuta la chiamata come ad alto rischio, lo strumento non viene eseguito. L'agente riceve un risultato dello strumento di errore con il contenuto Permission to use {tool_name} has been denied. e is_error: true. La sessione continua a essere eseguita e il tuo client non può sovrascrivere il diniego.
• La chiamata si mette in pausa in attesa della tua approvazione. Quando il server non giunge a una determinazione, la sessione si mette in pausa come avviene con always_ask. Consulta Rispondere alle richieste di conferma.

Per attivare auto, imposta permission_policy su {"type": "auto"}. Va inserito negli stessi due punti degli altri criteri: nel default_config di un set di strumenti per l'intero set, oppure in una voce configs per un singolo strumento. Sia il set di strumenti dell'agente sia i set di strumenti MCP lo accettano. Nessun set di strumenti usa auto per impostazione predefinita.

L'esempio seguente imposta auto come predefinito per il set di strumenti dell'agente e per il set di strumenti MCP github, e sovrascrive bash con 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
---

Ciò che pubblichi negli eventi user.message conta come tua intenzione e può portare il server a consentire una chiamata che altrimenti negherebbe. Il server non ricava l'intenzione da un risultato dello strumento, da una pagina web recuperata, dalla risposta di un server MCP o da un messaggio tra thread di sessione. Valuta quel contenuto, ma non ne accetta istruzioni. Il server valuta alcune chiamate come ad alto rischio indipendentemente da chi le richieda. Se inoltri input non attendibile dell'utente finale negli eventi user.message, il server interpreta anche quell'input come tua intenzione, e ciò può far consentire una chiamata. Configura always_ask sugli strumenti che non lasceresti eseguire a quell'utente finale senza revisione.

Vedere come è stata valutata ogni chiamata

Con qualsiasi criterio di autorizzazione, ogni evento agent.tool_use e agent.mcp_tool_use contiene evaluated_permission, l'esito del controllo di autorizzazione della chiamata: "allow", "ask" o "deny". La maggior parte degli eventi contiene anche un oggetto evaluation il cui type indica il criterio che ha prodotto quell'esito. Con auto, l'oggetto registra anche la determinazione del server, più un reason_code quando l'esito è ask o deny.

Ad esempio, quando bash è sotto auto e il server valuta una chiamata come ad alto rischio, la chiamata negata appare nel flusso di eventi come segue:

{
  "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"
}

L'oggetto evaluation assume una delle forme riportate nella tabella seguente.

Quando evaluation.type è "auto", il suo evaluated_permission.type annidato ripete l'evaluated_permission di primo livello dell'evento, quindi puoi leggere l'esito da entrambi i campi. Un reason_code è un valore su cui il tuo client può basare le proprie diramazioni logiche e da conservare nei registri di audit, non un testo da mostrare agli utenti finali.

evaluation è assente in due casi. Quando l'agente indica uno strumento non abilitato nella sessione, il server nega la chiamata senza valutare alcun criterio: l'evento contiene evaluated_permission: "deny" e nessun evaluation. Anche gli eventi registrati prima dell'introduzione di evaluation lo omettono: interpretali come always_allow quando evaluated_permission è "allow" e come always_ask quando è "ask".

Scrivi il tuo client in modo che tolleri un evaluation.type o un reason_code che non riconosce. Gli eventi agent.custom_tool_use non contengono nessuno dei due campi, perché i criteri di autorizzazione non si applicano agli strumenti personalizzati.

Rispondere alle richieste di conferma

Una chiamata a uno strumento viene valutata come ask con un criterio always_ask, oppure con auto quando il server non giunge a una determinazione. Quando ciò accade:

1. La sessione emette un evento agent.tool_use o agent.mcp_tool_use.
2. La sessione si mette in pausa con un evento session.status_idle il cui stop_reason.type è requires_action. Gli ID degli eventi bloccanti si trovano nell'array stop_reason.event_ids. La sessione attende indefinitamente una risposta.
3. Invia un evento user.tool_confirmation per ogni evento bloccante, passando l'ID dell'evento nel parametro tool_use_id. Imposta result su "allow" o "deny". Usa deny_message per spiegare un rifiuto. Puoi inviare diverse conferme in una singola richiesta events.
4. Una volta risolti tutti gli eventi bloccanti, la sessione torna allo stato running. Gli strumenti consentiti vengono eseguiti. Gli strumenti rifiutati non vengono eseguiti, e l'agente riceve un risultato dello strumento che indica che la chiamata è stata rifiutata, incluso il tuo deny_message.

Se invii un user.tool_confirmation per un evento il cui evaluated_permission non è ask, l'API lo rifiuta con un errore 400. Ciò include le chiamate che il server ha negato con auto: il tuo client non può sovrascriverle.

Per rispondere invece in modo interattivo, usa ant beta:sessions connect, che mostra la chiamata in attesa e invia questo evento quando la consenti o la neghi. Consulta Connettersi a una sessione Managed Agents dal terminale.

Negli esempi seguenti, gli ID degli eventi di uso degli strumenti provengono dall'array stop_reason.event_ids dell'evento session.status_idle. Scopri di più sulla ricezione degli eventi nella guida Flusso di eventi della sessione, oppure iscriviti ai webhook per essere notificato quando una sessione si mette in pausa in attesa di input.

# Consenti l'esecuzione dello strumento
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# Oppure negala con una spiegazione
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.",
        },
    ],
)

Strumenti personalizzati

Le policy di autorizzazione non si applicano agli strumenti personalizzati. Quando l'agente invoca uno strumento personalizzato, la tua applicazione riceve un evento agent.custom_tool_use ed è responsabile di decidere se eseguirlo prima di inviare un user.custom_tool_result. Consulta Flusso di eventi della sessione per il flusso completo.

Prossimi passi