Guida introduttiva a Policy in AgentCore

In questo tutorial, imparerai come configurare Policy AgentCore e integrarla con un Amazon Bedrock AgentCore Gateway utilizzando la AgentCore CLI. 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:

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

Utilizza 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 destinazione gateway con uno schema di strumenti che definisce uno strumento di elaborazione dei rimborsi:

Aggiungi un motore di policy

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

Crea una politica Cedar

Fornisci direttamente un file di policy Cedar:

agentcore add policy --name RefundLimit \
  --engine RefundPolicyEngine \
  --source refund_policy.cedar

In alternativa, dopo aver distribuito le risorse nella Fase 3, è possibile 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 distribuito per primo, poiché richiama un' AWS API che richiede l'ARN del gateway per convertire il linguaggio naturale in Cedar. Questo approccio risolve automaticamente gli ARN gateway, rendendolo il percorso più semplice per la creazione di policy.

Comprendere la configurazione

I comandi CLI sopra riportati configurano diverse risorse nel progetto. AgentCore 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, utilizza l'autorizzazione IAM o JWT per proteggere il gateway.

Aggiungi obiettivo 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 trasmettere 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 Cedar Policy

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

Di seguito è riportato un esempio di politica 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 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 la destinazione Lambda, effettua il provisioning del motore delle policy e allega la policy Cedar. Questo processo richiede circa 2-3 minuti.

Una volta completata la distribuzione, puoi verificare lo stato delle tue risorse:

agentcore status

Fase 4: Verificare la politica

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

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

L'importo del rimborso di 500 USD è inferiore al limite di 1000 USD, quindi il motore delle politiche consente la richiesta:

curl -X POST ++<GATEWAY_URL>++ \
  -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$ (dovrebbe essere negato)

L'importo del rimborso di 2000 USD supera il limite di 1000 USD, pertanto il motore della politica respinge la richiesta:

curl -X POST ++<GATEWAY_URL>++ \
  -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 motore delle politiche, quindi ridistribuisci:

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

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