AgentCore Gateway

Gere um projeto Amazon Bedrock AgentCore Gateway. Um AgentCore Gateway é um ponto de entrada gerenciado que agrega um ou mais alvos de servidor MCP atrás de um único endpoint MCP, autentica requisições de entrada (IAM ou Cognito), avalia cada chamada de ferramenta contra um motor de políticas Cedar e assina o tráfego de saída para servidores MCP com IAM SigV4.

Uso

Gerar um AgentCore Gateway

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

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

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	mcp	O protocolo de entrada exposto pelo seu gateway. Apenas mcp é suportado atualmente; protocolos adicionais podem ser adicionados no futuro.
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>/, além de um construto CDK ou módulo Terraform para a infraestrutura:

• Directorypackages/<name>/

  • Directorypolicies/ Arquivos de origem de política Cedar (omitidos quando cedarPolicy: false)

    • permit-all.cedar Política Cedar padrão que permite chamadores autenticados (chamadores IAM da mesma conta AWS, ou qualquer usuário Cognito — veja Authentication)
    • README.md Referência para escrever políticas Cedar
  • local-dev.ts Gateway local agregando servidores MCP anexados para desenvolvimento local
  • 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 com base no iac escolhido, ele criará um projeto em packages/common que inclui os constructs CDK ou módulos Terraform relevantes.

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

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Constructs genéricos reutilizados pelos constructs em app

      • …
    • index.ts Ponto de entrada exportando os constructs de app
  • project.json Metas de build e configuração do projeto

Projeto gerado

Este projeto é gerado usando o gerador ts#project e portanto configura as mesmas metas de build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Módulos Terraform para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Módulos genéricos reutilizados pelos módulos em app

      • …
  • project.json Metas de build e configuração do projeto

Projeto gerado

Este projeto é gerado usando o gerador terraform#project e portanto configura as mesmas metas 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 configurado para o protocolo MCP com autenticação IAM de entrada (padrão) ou autenticação JWT Cognito (veja Authentication)
• Um AgentCore::PolicyEngine executando em modo ENFORCE, anexado ao Gateway (omitido quando cedarPolicy: false)
• Uma AgentCore::Policy por arquivo .cedar em policies/
• Um AWS WAFv2 Web ACL associado ao Gateway, com registro de requisiçõ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 possui a seguinte arquitetura, com um AWS WAFv2 Web ACL na frente do Gateway, que roteia para seus alvos de servidor MCP downstream:

Authentication

A opção auth configura como o Gateway autentica requisições de entrada. Escolha entre IAM (padrão) e Cognito.

IAM

Por padrão, o Gateway é configurado com GatewayAuthorizer.usingAwsIam(). Os chamadores assinam requisiçõ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 autenticam apresentando um token bearer JWT, e a claim sub do token está disponível para políticas Cedar como um principal AgentCore::OAuthUser. Use isso quando seus chamadores são usuários finais autenticando através do Cognito (por exemplo, um site ou um cliente não-AWS).

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 prop identity fornecendo o user pool e o 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. Geradores de conexão de agente para Gateway suportam apenas gateways autenticados com IAM, já que agentes assinam suas chamadas com SigV4.

Escrevendo Políticas

cedarPolicy = true

Cedar é a linguagem de políticas usada pelo AgentCore Gateway para autorizar chamadas de ferramentas. Cada requisição tools/list e tools/call que flui 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 nenhuma forbid correspondente) para que a requisiçã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íticas.

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 torna-se 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 que uma função de agente específica invoque 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 diretamente. Execute re-synth ou re-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 está implantado

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

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 através do 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 ao 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, action, resource), a requisiçã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 fica 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 o cliente do token antes das políticas serem 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 Authentication).

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, então uma função pode 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 de 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 claim sub do token JWT, e as claims JWT (username, scope, etc.) estão disponíveis como tags de principal:

principal is AgentCore::OAuthUser

Combine claims 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"
};

Invocações de ferramentas chegam ao motor de políticas como ações com a forma:

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

onde <target-name> é o nome do alvo 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 underscores). Cedar não suporta curingas em ações — combine ações exatas, ou omita action == para combinar 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 “Overly Restrictive”, mesmo quando delimitado com uma cláusula when. A aplicação não é afetada; ela é configurada pelo modo ENFORCE do motor de políticas.

Uma restrição de ordenação ainda se aplica: uma política referenciando AgentCore::Action::"<target>___<tool>" só valida depois que o alvo registrou essa ferramenta com o Gateway, razão pela qual a infraestrutura gerada cria políticas após os alvos 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 de agente Python a chamada de ts-mcp___divide enquanto mantém 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: um gateway local expondo 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. Executá-lo inicia o gateway local e todos os servidores MCP anexados juntos:

pnpm

pnpm nx dev <name>

yarn

yarn nx dev <name>

npm

npx nx dev <name>

bun

bunx nx dev <name>

Consulte o guia 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 fica 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 alvos 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 motor de políticas Cedar e o AWS WAF Web ACL (veja AWS WAF abaixo). Registre alvos 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 ao Gateway. O AWS WAF inspeciona cada requisição de entrada inline antes de alcançar um alvo, protegendo seu Gateway de explorações 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 explorações web comuns, incluindo o OWASP Top 10. Os logs de requisições 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 do 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. Requisições superdimensionadas ainda serão registradas como métricas para que você possa monitorá-las. Consulte o guia AWS WAF body size limits 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 você 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 em seu workspace. As seguintes conexões envolvem este projeto:

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

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

TypeScript Agent para AgentCore GatewayConecte um TypeScript Agent a um AgentCore Gateway

Python Agent para AgentCore GatewayConecte um Python Agent a um AgentCore Gateway