TypeScript Agent a Gateway

Il generatore connection può connettere il tuo TypeScript Agent a un AgentCore Gateway.

Il generatore configura l’agent in modo che si autentichi al Gateway con IAM SigV4 quando viene distribuito, e si colleghi al gateway locale avviato dal progetto Gateway quando viene eseguito localmente.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

1. Un progetto TypeScript con un componente Agent (infra: agentcore)
2. Un progetto agentcore-gateway

Utilizzo

Eseguire il Generatore

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - connection
5. Compila i parametri richiesti
6. Clicca su 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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Seleziona il progetto agent come sorgente e il progetto Gateway come destinazione.

Opzioni

Parametro	Tipo	Predefinito	Descrizione
sourceProject Obbligatorio	string	-	Il progetto sorgente
targetProject Obbligatorio	string	-	Il progetto di destinazione a cui connettersi
sourceComponent	string	-	Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come sorgente.
targetComponent	string	-	Il componente di destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto di destinazione, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come destinazione.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore emette file client core condivisi nel tuo package agent-connection, più un wrapper per-Gateway, e modifica il tuo agent:

• Directorypackages/common/agent-connection

  • Directorysrc

    • Directorycore/

      • agentcore-endpoints.ts Risoluzione ARN/URL indipendente dal framework
      • agentcore-gateway-mcp-transport.ts Trasporto MCP Gateway indipendente dal framework
      • agentcore-gateway-mcp-client-strands.ts Client MCP Strands per il Gateway distribuito
    • Directoryapp/

      • <gateway-kebab>-client-strands.ts Wrapper client Strands per-Gateway
    • index.ts Ri-esporta il client Gateway

Inoltre, il generatore:

• Modifica il file agent.ts del tuo agent per importare la classe client Gateway, chiamare <Gateway>ClientStrands.create(), e registrare il client restituito nell’array tools
• Collega il target <agent>-dev dell’agent per dipendere dal target dev del Gateway
• Installa le dipendenze SigV4 / MCP richieste

Utilizzare il Gateway connesso

Il generatore trasforma il file agent.ts del tuo agent per utilizzare il client 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 distribuito (SERVE_LOCAL non impostato), il client punta all’endpoint MCP del Gateway e si autentica con SigV4. Quando SERVE_LOCAL=true, punta al gateway locale avviato dal target serve-local del progetto Gateway, quindi lo stesso agent.ts funziona uniformemente in entrambe le modalità.

L’ID di sessione viene propagato automaticamente ai server MCP downstream tramite l’header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id.

Infrastruttura

Dopo aver eseguito il generatore devi concedere all’agent il permesso di invocare il Gateway.

CDK

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

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

// Concedi all'agent i permessi per invocare il Gateway
gateway.grantInvokeAccess(myAgent);

L’URL del Gateway viene automaticamente registrato nel namespace agentcore.gateways.<ClassName> della Runtime Configuration dal costrutto CDK generato, in modo che l’agent possa scoprirlo a runtime.

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

# Concedi all'agent il permesso di invocare il 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
}

L’URL del Gateway viene automaticamente registrato nel namespace agentcore.gateways.<ClassName> della Runtime Configuration dal modulo Terraform generato, in modo che l’agent possa scoprirlo a runtime.

Sviluppo Locale

Il generatore configura il target dev dell’agent per:

1. Avviare il gateway locale del Gateway connesso e ogni server MCP collegato
2. Impostare LOCAL_DEV=true in modo che il client generato punti al gateway locale invece del Gateway distribuito

Esegui l’agent localmente con:

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>

Per eseguire l’agent localmente contro il Gateway distribuito invece (ad esempio, per esercitare le policy Cedar), utilizza il target serve dell’agent. Senza LOCAL_DEV impostato, il client risolve l’URL del Gateway distribuito dalla configurazione runtime e firma le richieste con SigV4 utilizzando le tue credenziali AWS locali:

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>

Fedeltà locale

Il gateway locale sostituisce il Gateway distribuito, quindi:

• Nessuna valutazione delle policy Cedar. Ogni strumento è visibile all’agent indipendentemente dalle policy. Utilizza il target serve per esercitare le policy contro il Gateway distribuito.
• Il prefisso del nome dello strumento è preservato. Gli strumenti di ogni server MCP locale sono wrappati per esporre nomi nella forma <target-name>___<tool-name>, corrispondenti a ciò che emette il Gateway distribuito. Questo mantiene il prompt di sistema dell’agent e i nomi delle azioni Cedar a cui fai riferimento coerenti tra esecuzioni locali e distribuite.

buite. te. te.