AgentCore Gateway para Agent

O gerador connection pode registrar um agente (seja 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 de requisições para o agente em <gatewayUrl>/<targetName>/invocations, assinando o tráfego de saída para o runtime com IAM SigV4. Isso dá 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:

Um projeto agentcore-gateway gerado com protocol: http
Um componente de agente (ts#agent ou py#agent) criado com infra: agentcore. Tanto auth: iam (o Gateway o invoca com seu próprio papel) quanto auth: cognito (o Gateway encaminha o JWT do chamador — veja Encaminhando identidade do chamador) funcionam.

Uso

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

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

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

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

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

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

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

Selecione o projeto Gateway como origem e o projeto do agente como destino. Se o projeto do agente contém 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 a gateway.addAgent(agent) você mesmo.

CDK
Terraform

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

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 construct concede ao papel 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 seu próprio papel.

Colocar um agente atrás de um Gateway é o que torna um agente implantado em VPC acessível: os chamadores falam com o endpoint público do Gateway, e o Gateway alcança o runtime internamente. Passe uma configuração de rede VPC para o construct 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 VPC do AgentCore Runtime 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.

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

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

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 gateway NAT), 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 JSON-RPC A2A todos fazem proxy através. 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 site aos agentes do Gateway, use o gerador connection.

Encaminhando identidade do chamador para o runtime

Por padrão, o Gateway assina chamadas de saída com seu próprio papel IAM (o provedor de credenciais GATEWAY_IAM_ROLE), então o runtime vê a identidade do Gateway, não do chamador. Se em vez disso você quiser que o agente autorize 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 inalterado (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 na frente do mesmo user pool do Cognito.

Todo o resto é automático — gateway.addAgent(agent) (CDK) e o módulo de runtime Terraform gerado lidam com a 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 adiciona o cabeçalho Authorization à lista de permissões para que o token encaminhado alcance seu código de agente. Sem esta lista de permissões, o AgentCore valida o token mas remove o cabeçalho antes do seu container.

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:

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'], ...

Desenvolvimento Local

Executar o Gateway localmente com:

pnpm nx dev <gateway-name>

yarn nx dev <gateway-name>

npx nx dev <gateway-name>

bunx nx dev <gateway-name>

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