TypeScript Agent para Gateway

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

O gerador configura o agente para que ele 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 com auth: iam

O Gateway deve usar autenticação IAM — o agente assina suas requisições com SigV4 usando sua própria função de execução. O gerador rejeita gateways autenticados com Cognito.

Uso

Executar o Gerador

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

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

Selecione o projeto do agente como origem e o projeto 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 compartilhados do cliente principal 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 Framework-agnostic ARN/URL resolution
      • agentcore-gateway-mcp-transport.ts Framework-agnostic Gateway MCP transport
      • agentcore-gateway-mcp-client-strands.ts Strands MCP client for the deployed Gateway
    • Directoryapp/

      • <gateway-kebab>-client-strands.ts Per-Gateway Strands client wrapper
    • index.ts Re-exports the Gateway client

Além disso, o gerador:

• Modifica o agent.ts do seu agente para importar a classe do cliente Gateway, chamar <Gateway>ClientStrands.create() e registrar o cliente retornado no array tools
• Configura 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 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 (LOCAL_DEV não definido), o cliente aponta para o endpoint MCP do Gateway e autentica com SigV4. Quando LOCAL_DEV=true, ele aponta para o gateway local iniciado pelo target dev do projeto Gateway, então o mesmo agent.ts funciona uniformemente em ambos os modos.

O ID da sessão é propagado automaticamente para 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 Runtime Configuration 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
  additional_iam_policy_statements = [{
    Effect   = "Allow"
    Action   = ["bedrock-agentcore:InvokeGateway"]
    Resource = [module.my_gateway.gateway_arn]
  }]
}

A URL do Gateway é automaticamente registrada no namespace agentcore.gateways.<ClassName> da Runtime Configuration 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 tempo de execução e assina requisiçõ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 do agente e os nomes de ação Cedar que você referencia consistentes entre execuções locais e implantadas.