Policy di autorizzazione

Le "permission policies" (policy di autorizzazione) controllano se gli strumenti eseguiti dal server (il toolset predefinito dell'agente e il toolset MCP) vengono eseguiti automaticamente o attendono la tua approvazione. Gli strumenti personalizzati sono eseguiti dalla tua applicazione e controllati da te, quindi non sono regolati dalle policy di autorizzazione.



Tipi di policy di autorizzazione

Ogni tipo di toolset ha il proprio valore predefinito: il toolset dell'agente ha come impostazione predefinita always_allow, mentre i toolset MCP hanno come impostazione predefinita 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 utilizzando 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 è 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 impostazione predefinita 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 da un server MCP affidabile, imposta default_config.permission_policy sulla voce mcp_toolset.

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

Questo esempio connette un server MCP di GitHub e consente ai suoi strumenti di essere eseguiti senza conferma:

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



Sovrascrivere la policy di un singolo strumento

Usa l'array configs per sovrascrivere l'impostazione predefinita 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 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

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.



Rispondere alle richieste di conferma

Quando l'agente invoca uno strumento con una policy always_ask:

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

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 ricevere una notifica quando una sessione si mette in pausa in attesa di input.

# Consenti l'esecuzione dello strumento
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}"

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



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.



Passaggi successivi