As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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 reembolsos com as políticas da Cedar que impõem regras comerciais para valores de reembolso.

Pré-requisitos

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

A AgentCore CLI verifica a pilha de bootstrap do CDK durante a implantação. Se o bootstrap for necessário, a implantação interativa solicitará confirmação. Use agentcore deploy --yes para autorizá-lo automaticamente.

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 do Lambda e um mecanismo de política 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 uma meta de função do Lambda com uma ferramenta de reembolso

Registre sua função do Lambda como um destino de gateway com um esquema de ferramentas que define uma ferramenta de processamento de reembolsos. Crie um refund_tools.json arquivo no diretório do seu projeto com o seguinte conteúdo:

[
  {
    "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"]
    }
  }
]

Adicionar um mecanismo de políticas

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

Crie uma política de cedro

Forneça diretamente um arquivo de política do Cedar. O Cedar não permite recursos curingas em declarações de política. Isso requer uma implantação em duas fases: primeiro, implante sem a política para criar o gateway e, em seguida, recupere o ARN do gateway. Em seguida, adicione a política e reimplante.

Como alternativa, depois de implantar seus recursos na Etapa 3, você pode gerar uma política Cedar a partir de uma descrição em idioma 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 ele 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-o 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 seu 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 IAM ou JWT para proteger seu gateway.

Adicionar alvo Lambda

O comando agentcore add gateway-target registra uma função Lambda como um destino 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íticas

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 aplicação consistente da segurança, independentemente de como o agente é implementado.

Crie uma política de cedro

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

Veja a seguir um exemplo de política da Cedar que permite reembolsos abaixo de USD $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

Os --attach-mode ENFORCE sinalizadores --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 alvo do Lambda e provisiona o mecanismo de políticas. Se você forneceu um arquivo de política do ARN-based Cedar, adicione-o após essa implantação e execute o agentcore deploy novamente para anexá-lo. Esse processo leva aproximadamente de 2 a 3 minutos por implantação.

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.

O URL do gateway mostrado na saída do status do agentcore é o endpoint base. As solicitações de MCP vão para o /mcp caminho nesse endpoint, portanto, anexe à URL antes de /mcp enviar as solicitações.

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

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

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

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

O valor do reembolso de USD $2000 excede o limite de USD $1000, portanto, o mecanismo de política nega a solicitação:

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

O que você construiu

Por meio deste 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, em seguida, reimplante:

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

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