AgentCore Gateway

Gera um projeto Amazon Bedrock AgentCore Gateway. Um AgentCore Gateway é um ponto de entrada gerenciado na frente dos seus servidores MCP ou agentes, autenticando solicitações de entrada (IAM ou Cognito) e assinando o tráfego de saída para seus destinos com IAM SigV4.

A opção protocol seleciona o que o Gateway frontaliza:

• mcp (padrão) — agrega um ou mais destinos de servidor MCP atrás de um único endpoint MCP, e avalia cada chamada de ferramenta contra um mecanismo de política Cedar.
• http — faz proxy de solicitações diretamente para destinos AgentCore Runtime (seus agentes) via roteamento baseado em caminho (/<targetName>/invocations), sem agregação ou tradução de protocolo. Use isso para frontalizar agentes com um único endpoint governado — por exemplo, para que um site possa alcançar agentes que estão implantados dentro de uma VPC através do Gateway.

Uso

Gerar um AgentCore Gateway

CLI

pnpm

pnpm nx g @aws/nx-plugin:agentcore-gateway

yarn

yarn nx g @aws/nx-plugin:agentcore-gateway

npm

npx nx g @aws/nx-plugin:agentcore-gateway

bun

bunx nx g @aws/nx-plugin:agentcore-gateway

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

pnpm nx g @aws/nx-plugin:agentcore-gateway --dry-run

yarn

yarn nx g @aws/nx-plugin:agentcore-gateway --dry-run

npm

npx nx g @aws/nx-plugin:agentcore-gateway --dry-run

bun

bunx nx g @aws/nx-plugin:agentcore-gateway --dry-run

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - agentcore-gateway
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	string	-	O nome do seu projeto AgentCore Gateway
directory	string	packages	Diretório pai onde o projeto gateway é colocado.
subDirectory	string	-	O subdiretório onde o projeto é colocado. Por padrão, este é o nome do projeto.
protocol	mcp | http	mcp	O protocolo de entrada exposto pelo seu gateway. Um gateway mcp agrega destinos de servidor MCP em um único endpoint MCP. Um gateway http encaminha requisições para destinos de runtime de agente via roteamento baseado em caminho, permitindo que chamadores (por exemplo, um website) alcancem agentes através do gateway.
auth	iam | cognito	iam	O método usado para autenticar solicitações de entrada ao seu gateway. Apenas iam é suportado atualmente; cognito e custom-jwt podem ser adicionados no futuro.
cedarPolicy	boolean	true	Se deve incluir um mecanismo de política Cedar aplicando autorização refinada no gateway.
infra	agentcore | none	agentcore	O tipo de infraestrutura para hospedar seu gateway. Selecione none para nenhuma hospedagem.
iac	inherit | cdk | terraform	inherit	O provedor IaC preferido. Por padrão, este é herdado da sua seleção inicial.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos do Nx); instale uma vez no final.

Saída do Gerador

O gerador cria um novo projeto em packages/<name>/, mais um construto CDK ou módulo Terraform para a infraestrutura:

• Directorypackages/<name>/

  • Directorypolicies/ Arquivos de origem de política Cedar (apenas protocolo mcp; omitido quando cedarPolicy: false)

    • permit-all.cedar Política Cedar padrão que permite chamadores autenticados
    • README.md Referência para escrever políticas Cedar
  • local-dev.ts Gateway local para desenvolvimento local — agrega servidores MCP anexados (mcp) ou faz proxy de agentes anexados (http)
  • project.json Adiciona os alvos serve e dev

Infraestrutura

A infraestrutura é gerada quando infra é agentcore (o padrão). Com infra: none nenhuma infraestrutura é gerada — execute novamente o gerador com infra: agentcore mais tarde para adicioná-la.

Como este gerador fornece infraestrutura como código baseada no seu iac escolhido, ele criará um projeto em packages/common que inclui os constructs CDK relevantes ou módulos Terraform.

O projeto comum de infraestrutura como código é estruturado da seguinte forma:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Projeto Gerado

Este projeto é gerado usando o gerador ts#project e, portanto, configura os mesmos alvos de build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Projeto Gerado

Este projeto é gerado usando o gerador terraform#project e, portanto, configura os mesmos alvos de build.

CDK

• Directorypackages/common/constructs/src

  • Directorycore

    • Directoryagentcore-gateway/ Construto de gateway compartilhado (sonda de prontidão, carregamento de política Cedar)

      • …
  • Directoryapp

    • Directorygateways

      • Directory<name>/

        • <name>.ts Construto CDK para implantar o Gateway

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorygateways

      • Directory<name>/

        • <name>.tf Módulo Terraform para implantar o Gateway

O construto gerado cria os seguintes recursos AWS:

• Um AgentCore::Gateway com autenticação IAM de entrada (padrão) ou autenticação JWT Cognito (veja Autenticação). Um gateway mcp é configurado para o protocolo MCP; um gateway http não tem tipo de protocolo, o que o AgentCore requer para seus destinos de runtime
• Um AgentCore::PolicyEngine executando em modo ENFORCE, anexado ao Gateway (apenas gateways mcp; omitido quando cedarPolicy: false)
• Uma AgentCore::Policy por arquivo .cedar em policies/ (apenas gateways mcp)
• Um AWS WAFv2 Web ACL associado ao Gateway, com registro de solicitações no CloudWatch (habilitado por padrão — veja AWS WAF)

A URL do Gateway é automaticamente registrada no namespace agentcore.gateways.<ClassName> da Configuração de Runtime para que os agentes possam descobri-la em tempo de execução.

Arquitetura

O Gateway implantado tem a seguinte arquitetura, com um AWS WAFv2 Web ACL na frente do Gateway, que roteia para seus destinos de servidor MCP downstream:

Autenticação

A opção auth configura como o Gateway autentica solicitações de entrada. Escolha entre iam (padrão) e cognito.

IAM

Por padrão, o Gateway é configurado com GatewayAuthorizer.usingAwsIam(). Os chamadores assinam solicitações com SigV4, e a identidade IAM do chamador está disponível para políticas Cedar como um principal AgentCore::IamEntity. Esta é a opção recomendada quando seus chamadores são agentes ou serviços executando na AWS — por exemplo, um agente conectado via o gerador de conexão de agente para Gateway, que assina suas chamadas com sua própria função de execução.

Cognito

Quando você seleciona cognito, o Gateway é configurado com um autorizador JWT personalizado apontando para um user pool do Cognito. Os chamadores se autenticam apresentando um token bearer JWT, e a reivindicação sub do token está disponível para políticas Cedar como um principal AgentCore::OAuthUser. Use isso quando seus chamadores se autenticam através do Cognito — por exemplo, um site ou um agente de codificação conectando via o gerador ts#dcr-proxy.

A infraestrutura gerada consome um user pool e cliente Cognito existentes — ela não os cria. Você pode gerar um UserIdentity usando o gerador ts#website#auth, ou fornecer o seu próprio.

CDK

O construto gerado requer uma propriedade identity fornecendo o user pool e cliente:

packages/infra/src/stacks/application-stack.ts

import { MyGateway, UserIdentity } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const identity = new UserIdentity(this, 'Identity');

    new MyGateway(this, 'MyGateway', {
      identity,
    });
  }
}

Terraform

O módulo gerado requer variáveis user_pool_id e user_pool_client_ids:

packages/infra/src/main.tf

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_gateway" {
  source               = "../../common/terraform/src/app/gateways/my-gateway"
  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Provedores OIDC personalizados

Para autenticar com um provedor OIDC não-Cognito, modifique o construto Gateway gerado ou módulo Terraform diretamente — troque a URL de descoberta do autorizador e os clientes permitidos pelos do seu provedor. Os geradores de conexão de agente para Gateway suportam apenas gateways autenticados por IAM, já que os agentes assinam suas chamadas com SigV4.

Escrevendo Políticas

cedarPolicy = true

Cedar é a linguagem de política usada pelo AgentCore Gateway para autorizar chamadas de ferramentas. Cada solicitação tools/list e tools/call fluindo através do Gateway é avaliada contra o conjunto de políticas anexado, e o chamador deve ter pelo menos uma declaração permit correspondente (e nenhum forbid correspondente) para que a solicitação seja bem-sucedida.

Consulte a documentação AWS sobre políticas do AgentCore Gateway para a referência completa, incluindo padrões comuns de política.

Adicionando uma política

Para adicionar uma política, crie um novo arquivo .cedar ao lado de permit-all.cedar. Cada arquivo .cedar em policies/ deve conter exatamente uma declaração permit ou forbid e é implantado como um único recurso AWS::BedrockAgentCore::Policy. O nome do recurso de política é derivado do nome do arquivo: permit-all.cedar se torna PermitAll (kebab/snake-case é convertido para PascalCase). Arquivos contendo múltiplas declarações produzem erros unexpected token 'forbid' no momento da implantação — divida-os em arquivos separados.

Por exemplo, para permitir apenas uma função de agente específica invocar uma ferramenta particular, crie:

packages/<name>/policies/ts-agent-divide.cedar

permit (
  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= tsAgentRoleName %>",
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

Passe o nome da função como uma variável de template (veja Variáveis de template abaixo) em vez de codificá-lo. Execute novamente synth ou plan para implantar a nova política.

Variáveis de template

As políticas são templates EJS renderizados no momento do synth/plan para que permaneçam portáveis entre contas e reimplantações do Gateway:

Variável	Substituída por
<%= gatewayArn %>	O ARN do Gateway implantado
<%= accountId %>	A conta AWS na qual este Gateway é implantado

Sempre referencie essas variáveis em vez de codificar valores.

Adicionando suas próprias variáveis

Adicione novas variáveis onde as políticas são renderizadas, por exemplo, para passar o nome da função de execução de um agente para o exemplo ts-agent-divide.cedar acima:

CDK

Em packages/common/constructs/src/app/gateways/<name>/<name>.ts, passe cedarPolicyVariables para o construto compartilhado:

super(scope, id, {
  cedarPolicyPath: path.join(
    ...
  ),
  cedarPolicyVariables: {
    tsAgentRoleName: cdk.Token.asString(tsAgent.agentCoreRuntime.role.roleName),
  },
});

Terraform

Em packages/common/terraform/src/app/gateways/<name>/<name>.tf, adicione à query da fonte de dados rendered_policies:

query = {
  template        = "${local.policies_dir}/${each.value}"
  gatewayArn      = aws_bedrockagentcore_gateway.this.gateway_arn
  tsAgentRoleName = var.ts_agent_role_name
  # ...
}

Modo ENFORCE e negação padrão

O PolicyEngine executa em modo ENFORCE, o que significa que a semântica de negação padrão se aplica: se nenhuma declaração permit corresponder à tupla (principal, ação, recurso), a solicitação é negada. Chamadas de ferramentas que são negadas retornam:

Tool Execution Denied: Tool call not allowed due to policy enforcement
[No policy applies to the request (denied by default).]

Além disso, o Gateway filtra a resposta de tools/list para que os chamadores vejam apenas as ferramentas para as quais têm pelo menos um permit correspondente: se um agente não tiver permissão para uma determinada ferramenta, a ferramenta é completamente oculta em vez de aparecer e falhar no momento da chamada.

permit-all.cedar padrão

O gerador fornece uma política padrão com escopo para o tipo de autenticação do Gateway.

Para um Gateway IAM, ele permite qualquer chamador IAM da conta AWS na qual o Gateway está implantado:

packages/<name>/policies/permit-all.cedar

permit (
  principal is AgentCore::IamEntity,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
) when {
  principal.id like "arn:aws:*::<%= accountId %>:*"
};

Para um Gateway Cognito, ele permite qualquer usuário OAuth autenticado (o autorizador JWT já validou o user pool e cliente do token antes que as políticas sejam avaliadas):

packages/<name>/policies/permit-all.cedar

permit (
  principal is AgentCore::OAuthUser,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

Para restringir ainda mais, adicione políticas mais estreitas ao lado dela. Sempre mantenha pelo menos um permit correspondente no conjunto de políticas, caso contrário a negação padrão bloqueará todas as chamadas.

Referência de escopo de política

O tipo de principal depende de como o Gateway autentica os chamadores (veja Autenticação).

Para um Gateway IAM, os chamadores são principais IAM:

principal is AgentCore::IamEntity

Os chamadores são avaliados como ARNs de assumed-role do STS com o nome da sessão removido, para que uma função possa ser correspondida exatamente — sem necessidade de curingas:

principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= myAgentRoleName %>"

O mesmo valor está disponível como principal.id para cláusulas when. Reserve like para padrões genuínos, como a correspondência em toda a conta no permit-all.cedar padrão.

Para um Gateway Cognito, os chamadores são usuários OAuth construídos a partir da reivindicação sub do token JWT, e as reivindicações JWT (nome de usuário, escopo, etc.) estão disponíveis como tags de principal:

principal is AgentCore::OAuthUser

Corresponda reivindicações individuais em cláusulas when — por exemplo, para exigir um escopo:

permit (
  principal is AgentCore::OAuthUser,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
) when {
  principal.scope == "gateway/invoke"
};

As invocações de ferramentas chegam ao mecanismo de política como ações com a forma:

AgentCore::Action::"<target-name>___<tool-name>"

onde <target-name> é o nome do destino do Gateway (o mcpServerName do servidor MCP por padrão ao usar gateway.addMcpServer(...), derivado do nome da classe do projeto MCP em kebab-case — por exemplo, TsMcp → ts-mcp), <tool-name> é o nome da ferramenta MCP, e o separador é ___ (três sublinhados). Cedar não suporta curingas em ações — corresponda ações exatas, ou omita action == para corresponder todas as ações.

O recurso é sempre o próprio Gateway:

resource == AgentCore::Gateway::"<%= gatewayArn %>"

Considerações de validação

A infraestrutura gerada cria políticas com IGNORE_ALL_FINDINGS: o analisador Cedar do AgentCore (FAIL_ON_ANY_FINDINGS, o padrão do serviço) rejeita muitas políticas legítimas — por exemplo, um forbid desabilitando uma única ferramenta para todos os chamadores é rejeitado como “Excessivamente Restritivo”, mesmo quando com escopo com uma cláusula when. A aplicação não é afetada; ela é configurada pelo modo ENFORCE do mecanismo de política.

Uma restrição de ordenação ainda se aplica: uma política referenciando AgentCore::Action::"<target>___<tool>" só valida uma vez que o destino tenha registrado essa ferramenta com o Gateway, razão pela qual a infraestrutura gerada cria políticas após os destinos do Gateway.

Se uma política falhar ao implantar, o CloudFormation apresenta a rejeição como um erro opaco Resource stabilization failed — execute aws bedrock-agentcore-control list-policies --policy-engine-id <id> para recuperar os statusReasons do validador, que contêm o motivo real.

Exemplo: proibir uma ferramenta mantendo um permit mais amplo

Emparelhe um forbid estreito com um permit mais amplo (Cedar avalia forbid sobre permit):

packages/<name>/policies/forbid-divide-for-py-agent.cedar

forbid (
  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= pyAgentRoleName %>",
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

Isso nega à função do agente Python chamar ts-mcp___divide enquanto deixa o permit-all.cedar mais amplo no lugar para todos os outros chamadores.

Desenvolvimento Local

O gerador adiciona um alvo dev ao projeto Gateway, que executa local-dev.ts. Executá-lo inicia o gateway local e cada destino anexado juntos:

pnpm

pnpm nx dev <name>

yarn

yarn nx dev <name>

npm

npx nx dev <name>

bun

bunx nx dev <name>

protocol = mcp

O gateway local expõe um único endpoint MCP que agrega cada servidor MCP anexado (conectado via o gerador agentcore-gateway#mcp-connection), com ferramentas prefixadas <target>___<tool> para corresponder ao Gateway implantado.

protocol = http

O gateway local faz proxy de caminhos /<targetName>/... para o servidor local de cada agente anexado (conectado via o gerador agentcore-gateway#agent-connection), correspondendo ao roteamento baseado em caminho do Gateway implantado.

Veja os guias de conexão para a história completa de desenvolvimento local.

Implantando seu AgentCore Gateway

O gerador AgentCore Gateway cria infraestrutura como código CDK ou Terraform com base no seu iac selecionado. Você pode usar isso para implantar seu Gateway.

CDK

O construto CDK para implantar seu Gateway está na pasta common/constructs. Você pode consumir isso em uma aplicação CDK, por exemplo:

packages/infra/src/stacks/application-stack.ts

import { MyGateway } from '@my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new MyGateway(this, 'MyGateway');
  }
}

Isso configura sua infraestrutura de Gateway, incluindo o AgentCore::Gateway, seu PolicyEngine Cedar, e o AWS WAF Web ACL (veja AWS WAF abaixo). Registre destinos de servidor MCP com gateway.addMcpServer(...) — veja o guia de conexão de servidor MCP.

Terraform

O módulo Terraform para implantar seu Gateway está na pasta common/terraform. Você pode usar isso em uma configuração Terraform, por exemplo:

packages/infra/src/main.tf

module "my_gateway" {
  source = "../../common/terraform/src/app/gateways/my-gateway"
}

Isso configura sua infraestrutura de Gateway, incluindo o aws_bedrockagentcore_gateway, seu mecanismo de política Cedar, e o AWS WAF Web ACL (veja AWS WAF abaixo). Registre destinos de servidor MCP com um recurso aws_bedrockagentcore_gateway_target — veja o guia de conexão de servidor MCP.

AWS WAF

Por padrão, o construto gerado associa um AWS WAFv2 Web ACL com o Gateway. O AWS WAF inspeciona cada solicitação de entrada inline antes de atingir um destino, protegendo seu Gateway de exploits da web, tráfego de bots e ataques volumétricos. O Web ACL usa o conjunto de regras padrão gerenciado pela AWS (AWSManagedRulesCommonRuleSet e AWSManagedRulesKnownBadInputsRuleSet), fornecendo proteção contra exploits comuns da web, incluindo o OWASP Top 10. Os logs de solicitação do WAF são gravados em um grupo do CloudWatch Logs.

O Web ACL é REGIONAL e criado na região do Gateway, conforme exigido para associações do AgentCore Gateway.

Desvio de SizeRestrictions_BODY dos padrões

A regra SizeRestrictions_BODY de AWSManagedRulesCommonRuleSet é substituída para Count em vez de Block, já que o limite de 8 KB da regra é muito restritivo para cargas úteis típicas de ferramentas MCP. Solicitações superdimensionadas ainda serão registradas como métricas para que você possa monitorá-las. Veja o guia limites de tamanho de corpo do AWS WAF para mais detalhes.

Você pode editar o construto Gateway gerado para adicionar, remover ou ajustar regras (por exemplo, para adicionar regras baseadas em taxa ou grupos de regras gerenciadas adicionais).

CDK

Para desativar (por exemplo, para anexar seu próprio Web ACL), defina enableWaf como false quando instanciar o construto Gateway:

new MyGateway(this, 'MyGateway', {
  enableWaf: false,
});

O construto expõe o Web ACL criado como webAcl para configuração adicional.

Terraform

Para desativar (por exemplo, para anexar seu próprio Web ACL), defina enable_waf como false no módulo Gateway:

module "my_gateway" {
  enable_waf = false
}

O módulo produz o ARN do Web ACL criado como waf_web_acl_arn para configuração adicional.

Conexões

Use o gerador connection para integrar este projeto com outros no seu workspace. As seguintes conexões envolvem este projeto:

AgentCore Gateway para Servidor MCPAgregar um servidor MCP atrás de um AgentCore Gateway

AgentCore Gateway para AgentCore GatewayAgregar um AgentCore Gateway atrás de outro AgentCore Gateway

Agente TypeScript para AgentCore GatewayConectar um Agente TypeScript a um AgentCore Gateway

Agente Python para AgentCore GatewayConectar um Agente Python a um AgentCore Gateway

AgentCore Gateway para AgenteFrontalizar um agente com um AgentCore Gateway como destino de runtime

Site React para AgentCore GatewayConectar um site React a agentes através de um AgentCore Gateway