Politiche di autorizzazione

Le politiche di autorizzazione controllano se gli strumenti eseguiti dal server (il set di strumenti dell'agente precostruito e il set di strumenti MCP) vengono eseguiti automaticamente o in attesa della tua approvazione. Gli strumenti personalizzati vengono eseguiti dalla tua applicazione e controllati da te, quindi non sono regolati dalle politiche di autorizzazione.

Tipi di politica di autorizzazione

Impostare una politica per un set di strumenti

Autorizzazioni del set di strumenti dell'agente

Quando crei un agente, puoi facoltativamente applicare una politica a ogni strumento in agent_toolset_20260401 utilizzando default_config.permission_policy:

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-7
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
YAML

default_config è un'impostazione facoltativa. Se la ometti, il set di strumenti dell'agente sarà abilitato con la politica di autorizzazione predefinita, always_allow.

Autorizzazioni del set di strumenti MCP

I set di strumenti 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 permission_policy sulla voce mcp_toolset.

mcp_server_name deve corrispondere al name referenziato nell'array mcp_servers.

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

ant beta:agents create <<'YAML'
name: Dev Assistant
model: claude-opus-4-7
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 politica di uno strumento individuale

Utilizza l'array configs per sovrascrivere l'impostazione predefinita per i singoli strumenti. Questo esempio consente il set di strumenti dell'agente completo per impostazione predefinita ma richiede conferma prima che venga eseguito qualsiasi comando bash:

tools = [
    {
        "type": "agent_toolset_20260401",
        "default_config": {
            "permission_policy": {"type": "always_allow"},
        },
        "configs": [
            {
                "name": "bash",
                "permission_policy": {"type": "always_ask"},
            },
        ],
    },
]

Rispondere alle richieste di conferma

Quando l'agente richiama uno strumento con una politica 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 contenente stop_reason: requires_action. Gli ID degli eventi di blocco si trovano nell'array stop_reason.requires_action.event_ids.
3. Invia un evento user.tool_confirmation per ciascuno, passando l'ID dell'evento nel parametro tool_use_id. Imposta result su "allow" o "deny". Utilizza deny_message per spiegare un rifiuto.
4. Una volta risolti tutti gli eventi di blocco, la sessione torna a running.

Scopri di più sulla gestione degli eventi nella guida session event stream.

# Allow the tool to execute
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# Or deny it with an explanation
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 politiche di autorizzazione non si applicano agli strumenti personalizzati. Quando l'agente richiama uno strumento personalizzato, la tua applicazione riceve un evento agent.custom_tool_use ed è responsabile di decidere se eseguirlo prima di inviare indietro un user.custom_tool_result. Vedi Session event stream per il flusso completo.