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, 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

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

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

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

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

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

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

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

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

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

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	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 de dentro da mesma conta AWS
  - 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 iacProvider 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
Terraform

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

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

CDK
Terraform

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

O construto gerado cria os seguintes recursos AWS:

Um AgentCore::Gateway configurado para o protocolo MCP com GatewayAuthorizer.usingAwsIam() (autenticação IAM de entrada)
Um AgentCore::PolicyEngine executando em modo ENFORCE, anexado ao Gateway (omitido quando cedarPolicy: false)
Uma AgentCore::Policy por arquivo .cedar em policies/

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.

Escrevendo Políticas

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:

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
Terraform

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),
  },
});

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 que permite qualquer chamador IAM da conta AWS na qual o Gateway está implantado:

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

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

Para Gateways gerados por este plugin, todos os chamadores são principais IAM (o Gateway é configurado com GatewayAuthorizer.usingAwsIam()):

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.

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):

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 <name>-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. Use o alvo dev do projeto:

pnpm nx dev <name>

yarn nx dev <name>

npx nx dev <name>

bunx nx dev <name>

Consulte o guia de conexão para a história completa de desenvolvimento local.

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 MCP Agregue um servidor MCP atrás de um AgentCore Gateway

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

TypeScript Agent para AgentCore Gateway Conecte um TypeScript Agent a um AgentCore Gateway

Python Agent para AgentCore Gateway Conecte um Python Agent a um AgentCore Gateway