Agente TypeScript a Gateway

El generador connection puede conectar tu Agente TypeScript a un AgentCore Gateway.

El generador configura el agente para que se autentique en el Gateway con IAM SigV4 cuando se despliega, y se conecta al gateway local iniciado por el proyecto Gateway cuando se ejecuta localmente.

Requisitos previos

Antes de usar este generador, asegúrate de tener:

Un proyecto TypeScript con un componente Agent (infra: agentcore)
Un proyecto agentcore-gateway

Uso

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - connection
Complete los parámetros requeridos
Haga clic en Generate

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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Selecciona el proyecto del agente como origen y el proyecto Gateway como destino.

Opciones

Parámetro	Tipo	Predeterminado	Descripción
sourceProject Requerido	string	-	El proyecto de origen
targetProject Requerido	string	-	El proyecto de destino al que conectar
sourceComponent	string	-	El componente de origen desde el que conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Use '.' para seleccionar explícitamente el proyecto como origen.
targetComponent	string	-	El componente de destino al que conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Use '.' para seleccionar explícitamente el proyecto como destino.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del generador

El generador emite archivos de cliente compartidos en tu paquete agent-connection, además de un wrapper por Gateway, y modifica tu agente:

Directoriopackages/common/agent-connection
- Directoriosrc
  - Directoriocore/
    agentcore-endpoints.ts Resolución de ARN/URL independiente del framework
    agentcore-gateway-mcp-transport.ts Transporte MCP Gateway independiente del framework
    agentcore-gateway-mcp-client-strands.ts Cliente MCP Strands para el Gateway desplegado
  - Directorioapp/
    <gateway-kebab>-client-strands.ts Wrapper de cliente Strands por Gateway
  - index.ts Re-exporta el cliente Gateway

Además, el generador:

Modifica el agent.ts de tu agente para importar la clase del cliente Gateway, llamar a <Gateway>ClientStrands.create(), y registrar el cliente devuelto en el array tools
Conecta el target <agent>-dev del agente para que dependa del target dev del Gateway
Instala las dependencias requeridas de SigV4 / MCP

Usar el Gateway conectado

El generador transforma el agent.ts de tu agente para usar el cliente Gateway:

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

Cuando se despliega (SERVE_LOCAL no establecido), el cliente apunta al endpoint MCP del Gateway y se autentica con SigV4. Cuando SERVE_LOCAL=true, apunta al gateway local iniciado por el target serve-local del proyecto Gateway, por lo que el mismo agent.ts funciona uniformemente en ambos modos.

El ID de sesión se propaga automáticamente a los servidores MCP descendentes a través del encabezado X-Amzn-Bedrock-AgentCore-Runtime-Session-Id.

Infraestructura

Después de ejecutar el generador, debes otorgar al agente permiso para invocar el Gateway.

CDK
Terraform

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

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

La URL del Gateway se registra automáticamente en el namespace agentcore.gateways.<ClassName> de Runtime Configuration por el constructo CDK generado, para que el agente pueda descubrirlo en tiempo de ejecución.

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
}

La URL del Gateway se registra automáticamente en el namespace agentcore.gateways.<ClassName> de Runtime Configuration por el módulo Terraform generado, para que el agente pueda descubrirlo en tiempo de ejecución.

Desarrollo local

El generador configura el target serve-local del agente para:

Iniciar el gateway local del Gateway conectado y cada servidor MCP adjunto
Establecer SERVE_LOCAL=true para que el cliente generado apunte al gateway local en lugar del Gateway desplegado

Ejecuta el agente localmente con:

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

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

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

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

Para ejecutar el agente localmente contra el Gateway desplegado en su lugar (por ejemplo, para ejercitar políticas Cedar), usa el objetivo serve del agente. Sin LOCAL_DEV establecido, el cliente resuelve la URL del Gateway desplegado desde la configuración de tiempo de ejecución y firma las solicitudes con SigV4 usando tus credenciales AWS locales:

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

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

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

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

Fidelidad local

El gateway local sustituye al Gateway desplegado, por lo que:

Sin evaluación de políticas Cedar. Cada herramienta es visible para el agente independientemente de las políticas. Usa el objetivo serve para ejercitar políticas contra el Gateway desplegado.
Se preserva el prefijo de nombres de herramientas. Las herramientas de cada servidor MCP local se envuelven para exponer nombres de la forma <target-name>___<tool-name>, coincidiendo con lo que emite el Gateway desplegado. Esto mantiene el prompt del sistema de un agente y los nombres de acción Cedar que referencias consistentes entre ejecuciones locales y desplegadas.