AgentCore Gateway para Agent

O gerador connection pode registrar um agente (TypeScript ou Python) como um destino de Runtime do AgentCore de um AgentCore Gateway gerado com protocol: http.

Uma vez conectado, o Gateway faz proxy das requisições para o agente em <gatewayUrl>/<targetName>/invocations, assinando o tráfego de saída para o runtime com IAM SigV4. Isso fornece aos seus agentes um único ponto de entrada governado — e como os chamadores só precisam alcançar o Gateway, os runtimes dos agentes podem ser implantados dentro de uma VPC atrás dele.

Pré-requisitos

Antes de usar este gerador, certifique-se de ter:

1. Um projeto agentcore-gateway gerado com protocol: http
2. Um componente de agente (ts#agent ou py#agent) criado com infra: agentcore. Tanto auth: iam (o Gateway o invoca com sua própria função) quanto auth: cognito (o Gateway encaminha o JWT do chamador — veja Encaminhando a identidade do chamador para o runtime) funcionam.

Agentes HTTP TypeScript

Um agente http TypeScript serve tRPC sobre WebSocket, e o AgentCore Gateway não suporta WebSocket ou streaming bidirecional — o gerador rejeita essa combinação. Gere o agente com o protocolo ag-ui em vez disso.

Uso

Executar o Gerador

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 - connection
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Selecione o projeto Gateway como origem e o projeto do agente como destino. Se o projeto do agente contiver múltiplos componentes, especifique targetComponent para desambiguar.

Opções

Parâmetro	Tipo	Padrão	Descrição
sourceProject Obrigatório	string	-	O projeto de origem
targetProject Obrigatório	string	-	O projeto de destino para conectar
sourceComponent	string	-	O componente de origem para conectar (nome do componente, caminho relativo à raiz do projeto de origem, ou id do gerador). Use '.' para selecionar explicitamente o projeto como origem.
targetComponent	string	-	O componente de destino para conectar (nome do componente, caminho relativo à raiz do projeto de destino, ou id do gerador). Use '.' para selecionar explicitamente o projeto como destino.
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 os geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador conecta projetos existentes em vez de emitir novos arquivos de origem. Os seguintes arquivos são modificados:

• Directorypackages/<gateway>

  • project.json o destino dev do Gateway ganha uma dependência no <agent>-dev do agente
  • local-dev.ts ATTACHED_AGENTS atualizado para que o gateway local faça proxy para o agente

Adicionando o destino do agente à sua stack

O gerador não pode conectar automaticamente o destino do agente à sua infraestrutura porque ele não sabe qual stack ou módulo instancia o Gateway. Adicione uma única chamada para gateway.addAgent(agent) você mesmo.

CDK

Na stack onde você instancia o Gateway, registre o agente como um destino:

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

const myAgent = new MyAgent(this, 'MyAgent');
const myGateway = new MyGateway(this, 'MyGateway');

// Register the agent as a runtime target of the Gateway. The target name
// defaults to the agent's `agentName` (its class name in kebab-case,
// e.g. `MyAgent` -> `my-agent`), and forms the target's invocation path:
// <gatewayUrl>/my-agent/invocations
myGateway.addAgent(myAgent);

Para substituir o nome de destino padrão, passe gatewayTargetName:

myGateway.addAgent(myAgent, { gatewayTargetName: 'my-target' });

O construtor concede à função de execução do Gateway acesso de invocação ao runtime do agente e configura o destino com o provedor de credenciais GATEWAY_IAM_ROLE, para que o Gateway assine chamadas de saída com sua própria função.

Implantando agentes em uma VPC

Colocar um agente atrás de um Gateway é o que torna um agente implantado em VPC acessível: os chamadores se comunicam com o endpoint público do Gateway, e o Gateway alcança o runtime internamente. Passe uma configuração de rede VPC para o construtor do agente:

import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';

const myAgent = new MyAgent(this, 'MyAgent', {
  // Give each agent its own scope for the network configuration — usingVpc
  // creates a security group named `SecurityGroup` under the scope you pass,
  // so passing `this` for more than one agent collides on the construct id.
  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(
    new Construct(this, 'MyAgentNetwork'),
    {
      vpc,
      vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
    },
  ),
});

Use uma sub-rede privada com egress, não uma sub-rede privada isolada: o runtime precisa de acesso de saída à internet para alcançar o Bedrock e ler sua configuração do AWS AppConfig.

Implantações de Runtime VPC do AgentCore são suportadas apenas em certas zonas de disponibilidade. Se uma implantação falhar com subnets are in unsupported availability zones, restrinja a VPC (ou a seleção de sub-rede) às zonas suportadas para sua região.

Terraform

No arquivo Terraform onde você instancia o Gateway, conecte o destino do agente:

packages/infra/src/main.tf

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"
  # ...
}

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

  # The Gateway signs outbound calls to the runtime with its own role and
  # validates access at target creation, so it needs invoke access first.
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
        # A2A targets additionally serve their agent card via the gateway
        "bedrock-agentcore:GetAgentCard",
      ]
      Resource = [
        module.my_agent.agent_core_runtime_arn,
        "${module.my_agent.agent_core_runtime_arn}/*",
      ]
    }
  ]
}

# Register the agent as a runtime target of the Gateway. The target name
# forms the invocation path: <gatewayUrl>/my-agent/invocations
resource "aws_bedrockagentcore_gateway_target" "my_agent" {
  gateway_identifier = module.my_gateway.gateway_id
  name               = "my-agent"
  # AgentCore fills in a description when none is set, which the provider
  # reports as an inconsistent result after apply — so always set one.
  description = "Agent runtime target my-agent"

  target_configuration {
    http {
      agentcore_runtime {
        arn = module.my_agent.agent_core_runtime_arn
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {}
  }
}

Implantando agentes em uma VPC

Colocar um agente atrás de um Gateway é o que torna um agente implantado em VPC acessível: os chamadores se comunicam com o endpoint público do Gateway, e o Gateway alcança o runtime internamente. Defina as variáveis VPC do módulo do agente:

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"

  enable_vpc = true
  vpc_id     = aws_vpc.my_vpc.id
  subnet_ids = [aws_subnet.private_a.id, aws_subnet.private_b.id]
}

Use sub-redes privadas com egress (uma rota para um NAT gateway), não sub-redes privadas isoladas: o runtime precisa de acesso de saída à internet para alcançar o Bedrock e ler sua configuração do AWS AppConfig.

Invocando o agente através do Gateway

Requisições para <gatewayUrl origin>/<targetName>/invocations são encaminhadas para o runtime do agente sem tradução de protocolo, então os chamadores usam a mesma forma de requisição que usariam diretamente contra o runtime — streams SSE (AG-UI), streaming JSON (Python HTTP) e A2A JSON-RPC todos fazem proxy. Os chamadores se autenticam com o Gateway (IAM SigV4 ou Cognito JWT dependendo do auth do Gateway) em vez de com o agente.

Para conectar um website aos agentes do Gateway, use o gerador connection.

Encaminhando a identidade do chamador para o runtime

Por padrão, o Gateway assina chamadas de saída com sua própria função IAM (o provedor de credenciais GATEWAY_IAM_ROLE), então o runtime vê a identidade do Gateway, não a do chamador. Se, em vez disso, você quiser que o agente autorize com base no chamador — por exemplo, para ler as claims sub ou scope do usuário — coloque um agente Cognito atrás de um Gateway Cognito. O Gateway então encaminha o JWT do chamador para o runtime sem alterações (o provedor de credenciais JWT_PASSTHROUGH), e o runtime o revalida.

Gere ambas as extremidades com auth: cognito e conecte-as como acima:

• um agente (ts#agent ou py#agent) criado com auth: cognito, e
• um Gateway criado com auth: cognito fronteando o mesmo user pool do Cognito.

Todo o resto é automático — gateway.addAgent(agent) (CDK) e o módulo de runtime Terraform gerado cuidam da conexão para você com base no auth do agente:

• o destino é criado com o provedor de credenciais JWT_PASSTHROUGH (em vez de GATEWAY_IAM_ROLE), e
• o runtime coloca o cabeçalho Authorization na lista de permissões para que o token encaminhado chegue ao código do seu agente. Sem essa lista de permissões, o AgentCore valida o token mas remove o cabeçalho antes do seu contêiner.

Os chamadores invocam o Gateway com Authorization: Bearer <jwt> (sem SigV4), e o agente lê as claims do cabeçalho Authorization — pulando a validação de assinatura, já que o autorizador de entrada do runtime já verificou o token:

packages/py_project/.../my_agent/main.py

import jwt  # PyJWT

@app.post('/invocations')
async def invoke(input: InvokeInput, request: Request):
    token = request.headers['authorization'].removeprefix('Bearer ')
    claims = jwt.decode(token, options={'verify_signature': False})
    # authorize on claims['sub'], claims['scope'], ...

Nota

O passthrough de JWT é adequado para um único provedor de identidade cujo audience do token já cobre o runtime. Se um Gateway frontaliza agentes em múltiplos tenants ou audiences, use a troca de token on-behalf-of do OAuth em vez disso.

Desenvolvimento Local

Executar o Gateway localmente com:

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

inicia um gateway local mais cada agente anexado em sua porta local atribuída. O gateway local faz proxy dos caminhos /<targetName>/... para o servidor local de cada agente, correspondendo ao roteamento baseado em caminho do Gateway implantado.