Agente TypeScript para Gateway

O gerador connection pode conectar seu Agente TypeScript a um AgentCore Gateway.

O gerador configura o agente para que ele se autentique no Gateway com IAM SigV4 quando implantado, e se conecte ao gateway local iniciado pelo projeto Gateway quando executado localmente.

Pré-requisitos

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

1. Um projeto TypeScript com um componente Agent (infra: agentcore)
2. Um projeto agentcore-gateway

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 do agente como origem e o projeto do Gateway como destino.

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 emite arquivos de cliente principais compartilhados em seu pacote agent-connection, além de um wrapper por Gateway, e modifica seu agente:

• Directorypackages/common/agent-connection

  • Directorysrc

    • Directorycore/

      • agentcore-endpoints.ts Resolução de ARN/URL independente de framework
      • agentcore-gateway-mcp-transport.ts Transporte MCP Gateway independente de framework
      • agentcore-gateway-mcp-client-strands.ts Cliente MCP Strands para o Gateway implantado
    • Directoryapp/

      • <gateway-kebab>-client-strands.ts Wrapper de cliente Strands por Gateway
    • index.ts Re-exporta o cliente do Gateway

Além disso, o gerador:

• Modifica o agent.ts do seu agente para importar a classe do cliente do Gateway, chamar <Gateway>ClientStrands.create() e registrar o cliente retornado no array tools
• Conecta o target <agent>-dev do agente para depender do target dev do Gateway
• Instala as dependências SigV4 / MCP necessárias

Usando o Gateway conectado

O gerador transforma o agent.ts do seu agente para usar o cliente do Gateway:

packages/example/src/my-agent/agent.ts

import { Agent } from '@strands-agents/sdk';
import { MyGatewayClientStrands } from ':my-scope/agent-connection';

export const getAgent = async () => {
  const myGateway = await MyGatewayClientStrands.create();
  return new Agent({
    systemPrompt: '...',
    tools: [myGateway],
  });
};

Quando implantado (SERVE_LOCAL não definido), o cliente aponta para o endpoint MCP do Gateway e autentica com SigV4. Quando SERVE_LOCAL=true, ele aponta para o gateway local iniciado pelo target serve-local do projeto Gateway, então o mesmo agent.ts funciona uniformemente em ambos os modos.

O ID da sessão é propagado automaticamente para os servidores MCP downstream através do cabeçalho X-Amzn-Bedrock-AgentCore-Runtime-Session-Id.

Infraestrutura

Após executar o gerador, você deve conceder ao agente permissão para invocar o Gateway.

CDK

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

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

// Grant the agent permissions to invoke the Gateway
gateway.grantInvokeAccess(myAgent);

A URL do Gateway é automaticamente registrada no namespace agentcore.gateways.<ClassName> da Configuração de Runtime pelo construto CDK gerado, para que o agente possa descobri-la em tempo de execução.

Terraform

packages/infra/src/main.tf

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

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

# Grant the agent permission to invoke the Gateway
resource "aws_iam_policy" "agent_invoke_gateway" {
  name = "AgentInvokeGatewayPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = "bedrock-agentcore:InvokeGateway"
      Resource = module.my_gateway.gateway_arn
    }]
  })
}

resource "aws_iam_role_policy_attachment" "agent_invoke_gateway" {
  role       = module.my_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_gateway.arn
}

A URL do Gateway é automaticamente registrada no namespace agentcore.gateways.<ClassName> da Configuração de Runtime pelo módulo Terraform gerado, para que o agente possa descobri-la em tempo de execução.

Desenvolvimento Local

O gerador configura o target dev do agente para:

1. Iniciar o gateway local do Gateway conectado e todos os servidores MCP anexados
2. Definir LOCAL_DEV=true para que o cliente gerado aponte para o gateway local em vez do Gateway implantado

Execute o agente localmente com:

pnpm

pnpm nx <agent-name>-dev <project-name>

yarn

yarn nx <agent-name>-dev <project-name>

npm

npx nx <agent-name>-dev <project-name>

bun

bunx nx <agent-name>-dev <project-name>

Para executar o agente localmente contra o Gateway implantado (por exemplo, para exercitar políticas Cedar), use o target serve do agente. Sem LOCAL_DEV definido, o cliente resolve a URL do Gateway implantado a partir da configuração de runtime e assina solicitações SigV4 com suas credenciais AWS locais:

pnpm

pnpm nx <agent-name>-serve <project-name>

yarn

yarn nx <agent-name>-serve <project-name>

npm

npx nx <agent-name>-serve <project-name>

bun

bunx nx <agent-name>-serve <project-name>

Fidelidade local

O gateway local substitui o Gateway implantado, então:

• Sem avaliação de política Cedar. Todas as ferramentas são visíveis para o agente, independentemente das políticas. Use o target serve para exercitar políticas contra o Gateway implantado.
• A prefixação de nomes de ferramentas é preservada. As ferramentas de cada servidor MCP local são encapsuladas para expor nomes no formato <target-name>___<tool-name>, correspondendo ao que o Gateway implantado emite. Isso mantém o prompt do sistema de um agente e os nomes de ação Cedar que você referencia consistentes entre execuções locais e implantadas.