Começando com a Política em AgentCore

Neste tutorial, você aprenderá como configurar a política AgentCore e integrá-la a um Amazon Bedrock AgentCore Gateway usando a AgentCore CLI. Você criará uma ferramenta de processamento de reembolso com as políticas da Cedar que aplicam regras comerciais para valores de reembolso.

Pré-requisitos

Antes de começar, verifique se você tem o seguinte:

Etapa 1: configurar e instalar

Instale a AgentCore CLI:

npm install -g @aws/agentcore

Crie um novo AgentCore projeto:

Etapa 2: Adicionar um gateway com um mecanismo de políticas

Use a AgentCore CLI para adicionar um gateway, um destino de função Lambda e um mecanismo de políticas ao seu projeto.

Adicionar um gateway

Crie um gateway sem autorização de entrada (para simplificar este tutorial) e conecte seu agente a ele:

Adicione um alvo de função Lambda com uma ferramenta de reembolso

Registre sua função Lambda como um destino de gateway com um esquema de ferramentas que define uma ferramenta de processamento de reembolso:

Adicionar um mecanismo de política

Crie um mecanismo de política e conecte-o ao gateway no modo ENFORCE:

Crie uma política de cedro

Forneça um arquivo de política do Cedar diretamente:

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

Como alternativa, depois de implantar seus recursos na Etapa 3, você pode gerar uma política do Cedar a partir de uma descrição em linguagem natural:

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

O --generate sinalizador exige que o gateway seja implantado primeiro, porque chama uma AWS API que precisa do ARN do gateway para converter a linguagem natural em Cedar. Essa abordagem resolve automaticamente os ARNs do gateway, tornando-a o caminho mais simples para criar políticas.

Entendendo a configuração

Os comandos da CLI acima configuram vários recursos em seu AgentCore projeto. Aqui está uma explicação detalhada de cada componente.

Crie um gateway

O comando agentcore add gateway cria um gateway que atua como o endpoint do servidor MCP. A configuração --authorizer-type NONE desativa a autorização de entrada para simplificar este tutorial. Na produção, use a autorização do IAM ou do JWT para proteger seu gateway.

Adicionar alvo Lambda

O comando agentcore add gateway-target registra uma função Lambda como alvo no gateway. O arquivo do esquema da ferramenta define as entradas que os agentes podem passar para a função, como o valor do reembolso.

Crie um mecanismo de política

O comando agentcore add policy-engine cria um mecanismo de políticas — uma coleção de políticas do Cedar que avalia e autoriza chamadas de ferramentas do agente. O mecanismo de políticas intercepta todas as solicitações no limite do gateway e determina se deve permitir ou negar cada ação com base nas políticas definidas. Isso fornece autorização determinística fora do código do agente, garantindo uma fiscalização de segurança consistente, independentemente de como o agente é implementado.

Crie uma política de cedro

Cedar é uma linguagem de políticas de código aberto desenvolvida por AWS para escrever políticas de autorização. O comando agentcore add policy cria uma política Cedar que controla as chamadas de ferramentas por meio do gateway. Você pode gerar uma política a partir de uma descrição em linguagem natural usando --generate ou fornecer um arquivo de política do Cedar diretamente usando. --source

A seguir está um exemplo de política da Cedar que permite reembolsos abaixo de $1000:

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

A política usa:

Anexar política ao gateway

As --attach-mode ENFORCE bandeiras --attach-to-gateways e no comando agentcore add policy-engine conectam o mecanismo de política ao gateway no modo ENFORCE. Neste modo:

Isso garante que todas as operações do agente por meio do gateway sejam regidas por suas políticas de segurança.

Etapa 3: Implantar

Implante todos os recursos para AWS:

agentcore deploy

A AgentCore CLI cria o gateway, registra o destino do Lambda, provisiona o mecanismo de políticas e anexa a política do Cedar. Esse processo leva aproximadamente de 2 a 3 minutos.

Após a conclusão da implantação, você poderá verificar o status dos seus recursos:

agentcore status

Etapa 4: testar a política

Teste a política enviando solicitações para o gateway. Como o gateway usa--authorizer-type NONE, você pode enviar solicitações diretamente com curl.

Teste 1: Reembolso de $500 (deve ser permitido)

O valor do reembolso de $500 está abaixo do limite de $1000, então o mecanismo de política permite a solicitação:

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}}}'

Teste 2: Reembolso de $2000 (deve ser negado)

O valor do reembolso de $2.000 excede o limite de $1.000, então o mecanismo de política nega a solicitação:

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}}}'

O que você construiu

Por meio desse tutorial, você criou:

Solução de problemas

Se você encontrar problemas durante a configuração ou o teste, consulte os seguintes problemas e soluções comuns:

Fazer a limpeza.

Para remover os recursos criados neste tutorial, remova o gateway e o mecanismo de políticas e reimplante:

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

A remoção de um gateway não remove automaticamente o mecanismo de políticas anexado. Você deve remover o mecanismo de políticas separadamente usandoagentcore remove policy-engine.