Policy di autorizzazione

Le policy di autorizzazione controllano se gli strumenti eseguiti dal server (il toolset dell'agente predefinito e il toolset MCP) vengono eseguiti automaticamente o attendono la tua approvazione. Gli strumenti personalizzati vengono 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 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 beta:agents create < agent.yaml

name: Coding Assistant
model: claude-opus-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 beta:agents create < agent.yaml

name: Dev Assistant
model: claude-opus-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 beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-5
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 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.

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

Prossimi passi