Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Guida introduttiva a Policy in AgentCore

In questo tutorial, imparerai come configurare Policy AgentCore e integrarla con un Amazon Bedrock AgentCore Gateway utilizzando l'interfaccia a riga di AgentCore comando. Creerai uno strumento di elaborazione dei rimborsi con politiche Cedar che applicano le regole aziendali per gli importi dei rimborsi.

Prerequisiti

Prima di iniziare, assicurati di avere quanto segue:

La AgentCore CLI controlla lo stack di bootstrap del CDK durante la distribuzione. Se è richiesto il bootstrap, la distribuzione interattiva richiede una conferma. Usalo agentcore deploy --yes per autorizzarlo automaticamente.

Fase 1: Configurazione e installazione

Installa la AgentCore CLI:

npm install -g @aws/agentcore

Crea un nuovo AgentCore progetto:

Fase 2: Aggiungere un gateway con un motore di policy

Usa la AgentCore CLI per aggiungere un gateway, un target di funzione Lambda e un motore di policy al tuo progetto.

Aggiungi un gateway

Crea un gateway senza autorizzazione in entrata (per semplicità in questo tutorial) e collega il tuo agente ad esso:

Aggiungi un obiettivo di funzione Lambda con uno strumento di rimborso

Registra la tua funzione Lambda come gateway target con uno schema di strumenti che definisce uno strumento di elaborazione dei rimborsi. Crea un refund_tools.json file nella directory del tuo progetto con i seguenti contenuti:

[
  {
    "name": "process_refund",
    "description": "Process a customer refund request for a given dollar amount",
    "inputSchema": {
      "type": "object",
      "description": "Input for processing a refund",
      "properties": {
        "amount": {
          "type": "integer",
          "description": "The refund amount in dollars"
        }
      },
      "required": ["amount"]
    }
  }
]

Aggiungi un motore di policy

Crea un motore di policy e collegalo al gateway in modalità ENFORCE:

Crea una policy Cedar

Fornisci direttamente un file di policy Cedar. Cedar non ammette l'uso di risorse jolly nelle dichiarazioni politiche. Ciò richiede una distribuzione in due fasi: prima l'implementazione senza la politica per creare il gateway, quindi recuperare l'ARN del gateway. Quindi aggiungi la policy e ridistribuiscila.

In alternativa, dopo aver distribuito le risorse nella Fase 3, potete generare una policy Cedar partendo da una descrizione in linguaggio naturale:

agentcore add policy --name RefundLimit \
  --engine RefundPolicyEngine \
  --generate "Only allow refunds under 1000 dollars" \
  --gateway PolicyGateway

Il --generate flag richiede che il gateway venga prima implementato, perché chiama un' AWS API che necessita dell'ARN del gateway per convertire il linguaggio naturale in Cedar. Questo approccio risolve automaticamente gli ARN del gateway, rendendolo il percorso più semplice per la creazione di policy.

Comprendere la configurazione

I comandi CLI precedenti configurano diverse risorse nel AgentCore progetto. Ecco una spiegazione dettagliata di ogni componente.

Crea un gateway

Il comando agentcore add gateway crea un gateway che funge da endpoint del server MCP. L'impostazione --authorizer-type NONE disabilita l'autorizzazione in entrata per semplicità in questo tutorial. In produzione, usa l'autorizzazione IAM o JWT per proteggere il tuo gateway.

Aggiungi un target Lambda

Il comando agentcore add gateway-target registra una funzione Lambda come destinazione nel gateway. Il file di schema dello strumento definisce gli input che gli agenti possono passare alla funzione, ad esempio l'importo del rimborso.

Crea un Policy Engine

Il comando agentcore add policy-engine crea un motore di policy, una raccolta di policy Cedar che valuta e autorizza le chiamate agli strumenti degli agenti. Il policy engine intercetta tutte le richieste al confine del gateway e determina se consentire o negare ogni azione in base alle politiche definite. Ciò fornisce un'autorizzazione deterministica al di fuori del codice dell'agente, garantendo un'applicazione coerente della sicurezza indipendentemente dal modo in cui l'agente è implementato.

Crea una politica Cedar

Cedar è un linguaggio politico open source sviluppato da AWS per scrivere politiche di autorizzazione. Il comando agentcore add policy crea una policy Cedar che governa le chiamate agli strumenti tramite il gateway. È possibile generare una policy da una descrizione in linguaggio naturale utilizzando o fornire direttamente un file di policy Cedar utilizzando--generate. --source

Di seguito è riportato un esempio di polizza Cedar che consente rimborsi inferiori a 1000 USD:

permit(principal,
  action == AgentCore::Action::"RefundTarget___process_refund",
  resource == AgentCore::Gateway::"<gateway-arn>")
when {
  context.input.amount < 1000
};

La politica utilizza:

Allega la policy a Gateway

I --attach-mode ENFORCE flag --attach-to-gateways and sul comando agentcore add policy-engine collegano il policy engine al gateway in modalità ENFORCE. In questa modalità:

Ciò garantisce che tutte le operazioni degli agenti attraverso il gateway siano regolate dalle politiche di sicurezza dell'utente.

Fase 3: Distribuzione

Implementa tutte le risorse per: AWS

agentcore deploy

La AgentCore CLI crea il gateway, registra il target Lambda ed esegue il provisioning del policy engine. Se hai fornito un file di policy ARN-based Cedar, aggiungilo dopo questa distribuzione ed esegui nuovamente agentcore deploy per allegarlo. Questo processo richiede circa 2-3 minuti per distribuzione.

Al termine della distribuzione, puoi verificare lo stato delle tue risorse:

agentcore status

Fase 4: verifica la policy

Verifica la policy inviando richieste al gateway. Poiché il gateway utilizza--authorizer-type NONE, puoi inviare richieste direttamente con curl.

L'URL del gateway mostrato nell'output di agentcore status è l'endpoint di base. Le richieste MCP vanno al /mcp percorso di quell'endpoint, quindi aggiungile /mcp all'URL prima di inviare le richieste.

Test 1: rimborso di 500 USD (dovrebbe essere consentito)

L'importo del rimborso di 500 USD è inferiore al limite di 1000 USD, pertanto il policy engine consente la richiesta:

curl -X POST ++<GATEWAY_URL>++/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":500}}}'

Test 2: rimborso di 2000 USD (dovrebbe essere negato)

L'importo del rimborso di 2000 USD supera il limite di 1000 USD, pertanto il policy engine respinge la richiesta:

curl -X POST ++<GATEWAY_URL>++/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":2000}}}'

Cosa hai costruito

Attraverso questo tutorial, hai creato:

Risoluzione dei problemi

Se riscontri problemi durante la configurazione o il test, fai riferimento ai seguenti problemi e soluzioni comuni:

Eliminazione

Per rimuovere le risorse create in questo tutorial, rimuovi sia il gateway che il policy engine, quindi ridistribuisci:

agentcore remove gateway --name PolicyGateway
agentcore remove policy-engine --name RefundPolicyEngine
agentcore deploy

La rimozione di un gateway non rimuove automaticamente il motore di policy associato. È necessario rimuovere il policy engine separatamente utilizzandoagentcore remove policy-engine.