AgentCore Gateway

Genera un progetto Amazon Bedrock AgentCore Gateway. Un AgentCore Gateway è un punto di ingresso gestito davanti ai tuoi server MCP o agenti, che autentica le richieste in entrata (IAM o Cognito) e firma il traffico in uscita verso i suoi target con IAM SigV4.

L’opzione protocol seleziona cosa il Gateway fronteggia:

• mcp (predefinito) — aggrega uno o più target di server MCP dietro un singolo endpoint MCP e valuta ogni chiamata di strumento rispetto a un motore di policy Cedar.
• http — inoltra le richieste direttamente ai target AgentCore Runtime (i tuoi agenti) tramite routing basato su percorso (/<targetName>/invocations), senza aggregazione o traduzione di protocollo. Usa questo per fronteggiare gli agenti con un singolo endpoint governato — ad esempio in modo che un sito web possa raggiungere agenti distribuiti all’interno di un VPC attraverso il Gateway.

Utilizzo

Genera un AgentCore Gateway

CLI

pnpm

pnpm nx g @aws/nx-plugin:agentcore-gateway

yarn

yarn nx g @aws/nx-plugin:agentcore-gateway

npm

npx nx g @aws/nx-plugin:agentcore-gateway

bun

bunx nx g @aws/nx-plugin:agentcore-gateway

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:agentcore-gateway --dry-run

yarn

yarn nx g @aws/nx-plugin:agentcore-gateway --dry-run

npm

npx nx g @aws/nx-plugin:agentcore-gateway --dry-run

bun

bunx nx g @aws/nx-plugin:agentcore-gateway --dry-run

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 - agentcore-gateway
5. Compila i parametri richiesti
6. Clicca su Generate

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	Il nome del tuo progetto AgentCore Gateway
directory	string	packages	Directory padre in cui viene posizionato il progetto gateway.
subDirectory	string	-	La sotto-directory in cui viene posizionato il progetto. Per impostazione predefinita corrisponde al nome del progetto.
protocol	mcp | http	mcp	Il protocollo in ingresso esposto dal tuo gateway. Un gateway mcp aggrega i target dei server MCP in un singolo endpoint MCP. Un gateway http inoltra le richieste ai target del runtime degli agenti tramite routing basato sul percorso, in modo che i chiamanti (ad esempio un sito web) possano raggiungere gli agenti attraverso il gateway.
auth	iam | cognito	iam	Il metodo utilizzato per autenticare le richieste in ingresso al tuo gateway. Attualmente è supportato solo iam; cognito e custom-jwt potrebbero essere aggiunti in futuro.
cedarPolicy	boolean	true	Se includere un motore di policy Cedar che applica autorizzazioni granulari sul gateway.
infra	agentcore | none	agentcore	Il tipo di infrastruttura per ospitare il tuo gateway. Seleziona none per nessun hosting.
iac	inherit | cdk | terraform	inherit	Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla tua selezione iniziale.
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 crea un nuovo progetto in packages/<name>/, più un costrutto CDK o un modulo Terraform per l’infrastruttura:

• Directorypackages/<name>/

  • Directorypolicies/ File sorgente delle policy Cedar (solo protocollo mcp; omesso quando cedarPolicy: false)

    • permit-all.cedar Policy Cedar predefinita che permette ai chiamanti autenticati
    • README.md Riferimento per scrivere policy Cedar
  • local-dev.ts Gateway locale per lo sviluppo locale — aggrega i server MCP collegati (mcp) o inoltra gli agenti collegati (http)
  • project.json Aggiunge i target serve e dev

Infrastruttura

L’infrastruttura viene generata quando infra è agentcore (il valore predefinito). Con infra: none non viene generata alcuna infrastruttura — riesegui il generatore con infra: agentcore successivamente per aggiungerla.

Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iac scelto, creerà un progetto in packages/common che include i costrutti CDK o i moduli Terraform pertinenti.

Il progetto comune di infrastruttura come codice è strutturato come segue:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Progetto Generato

Questo progetto è generato utilizzando il generatore ts#project e quindi configura gli stessi target di build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Progetto Generato

Questo progetto è generato utilizzando il generatore terraform#project e quindi configura gli stessi target di build.

CDK

• Directorypackages/common/constructs/src

  • Directorycore

    • Directoryagentcore-gateway/ Costrutto gateway condiviso (readiness probe, caricamento policy Cedar)

      • …
  • Directoryapp

    • Directorygateways

      • Directory<name>/

        • <name>.ts Costrutto CDK per distribuire il Gateway

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorygateways

      • Directory<name>/

        • <name>.tf Modulo Terraform per distribuire il Gateway

Il costrutto generato crea le seguenti risorse AWS:

• Un AgentCore::Gateway con autenticazione IAM in entrata (predefinito) o autenticazione JWT Cognito (vedi Autenticazione). Un gateway mcp è configurato per il protocollo MCP; un gateway http non ha tipo di protocollo, come richiesto da AgentCore per i suoi target runtime
• Un AgentCore::PolicyEngine in esecuzione in modalità ENFORCE, collegato al Gateway (solo gateway mcp; omesso quando cedarPolicy: false)
• Una AgentCore::Policy per ogni file .cedar in policies/ (solo gateway mcp)
• Un Web ACL AWS WAFv2 associato al Gateway, con registrazione delle richieste su CloudWatch (abilitato per impostazione predefinita — vedi AWS WAF)

L’URL del Gateway viene automaticamente registrato nello spazio dei nomi agentcore.gateways.<ClassName> della Configurazione Runtime in modo che gli agenti possano scoprirlo a runtime.

Architettura

Il Gateway distribuito ha la seguente architettura, con un Web ACL AWS WAFv2 davanti al Gateway, che instrada verso i suoi target di server MCP downstream:

Autenticazione

L’opzione auth configura come il Gateway autentica le richieste in entrata. Scegli tra iam (predefinito) e cognito.

IAM

Per impostazione predefinita, il Gateway è configurato con GatewayAuthorizer.usingAwsIam(). I chiamanti firmano le richieste con SigV4 e l’identità IAM del chiamante è disponibile per le policy Cedar come principal AgentCore::IamEntity. Questa è l’opzione consigliata quando i tuoi chiamanti sono agenti o servizi in esecuzione in AWS — ad esempio un agente connesso tramite il generatore di connessione da agente a Gateway, che firma le sue chiamate con il proprio ruolo di esecuzione.

Cognito

Quando selezioni cognito, il Gateway è configurato con un autorizzatore JWT personalizzato che punta a un user pool Cognito. I chiamanti si autenticano presentando un token bearer JWT e il claim sub del token è disponibile per le policy Cedar come principal AgentCore::OAuthUser. Usa questo quando i tuoi chiamanti si autenticano tramite Cognito — ad esempio un sito web o un agente di codifica che si connette tramite il generatore ts#dcr-proxy.

L’infrastruttura generata consuma un user pool e un client Cognito esistenti — non li crea. Puoi generare un UserIdentity usando il generatore ts#website#auth, o fornire il tuo.

CDK

Il costrutto generato richiede una prop identity che fornisce l’user pool e il client:

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

import { MyGateway, UserIdentity } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const identity = new UserIdentity(this, 'Identity');

    new MyGateway(this, 'MyGateway', {
      identity,
    });
  }
}

Terraform

Il modulo generato richiede le variabili user_pool_id e user_pool_client_ids:

packages/infra/src/main.tf

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_gateway" {
  source               = "../../common/terraform/src/app/gateways/my-gateway"
  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Provider OIDC personalizzati

Per autenticare con un provider OIDC non-Cognito, modifica direttamente il costrutto Gateway o il modulo Terraform generato — sostituisci l’URL di discovery dell’autorizzatore e i client consentiti con quelli del tuo provider. I generatori di connessione da agente a Gateway supportano solo gateway autenticati con IAM, poiché gli agenti firmano le loro chiamate con SigV4.

Scrittura delle Policy

cedarPolicy = true

Cedar è il linguaggio di policy utilizzato da AgentCore Gateway per autorizzare le chiamate agli strumenti. Ogni richiesta tools/list e tools/call che fluisce attraverso il Gateway viene valutata rispetto al set di policy collegato e il chiamante deve avere almeno un’istruzione permit corrispondente (e nessun forbid corrispondente) affinché la richiesta abbia successo.

Fai riferimento alla documentazione AWS sulle policy AgentCore Gateway per il riferimento completo, inclusi i pattern di policy comuni.

Aggiungere una policy

Per aggiungere una policy, crea un nuovo file .cedar accanto a permit-all.cedar. Ogni file .cedar in policies/ deve contenere esattamente una istruzione permit o forbid e viene distribuito come una singola risorsa AWS::BedrockAgentCore::Policy. Il nome della risorsa policy deriva dal nome del file: permit-all.cedar diventa PermitAll (kebab/snake-case viene convertito in PascalCase). I file contenenti più istruzioni producono errori unexpected token 'forbid' al momento della distribuzione — dividili in file separati.

Ad esempio, per permettere solo a un ruolo agente specifico di invocare un particolare strumento, crea:

packages/<name>/policies/ts-agent-divide.cedar

permit (
  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= tsAgentRoleName %>",
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

Passa il nome del ruolo come variabile di template (vedi Variabili di template sotto) piuttosto che codificarlo direttamente. Riesegui synth o plan per distribuire la nuova policy.

Variabili di template

Le policy sono template EJS renderizzati al momento di synth/plan in modo che rimangano portabili tra account e ridistribuzioni del Gateway:

Variabile	Sostituita con
<%= gatewayArn %>	L’ARN del Gateway distribuito
<%= accountId %>	L’account AWS in cui questo Gateway è distribuito

Fai sempre riferimento a queste variabili piuttosto che codificare i valori.

Aggiungere le tue variabili

Aggiungi nuove variabili dove vengono renderizzate le policy, ad esempio per passare il nome del ruolo di esecuzione di un agente all’esempio ts-agent-divide.cedar sopra:

CDK

In packages/common/constructs/src/app/gateways/<name>/<name>.ts, passa cedarPolicyVariables al costrutto condiviso:

super(scope, id, {
  cedarPolicyPath: path.join(
    ...
  ),
  cedarPolicyVariables: {
    tsAgentRoleName: cdk.Token.asString(tsAgent.agentCoreRuntime.role.roleName),
  },
});

Terraform

In packages/common/terraform/src/app/gateways/<name>/<name>.tf, aggiungi alla query della data source rendered_policies:

query = {
  template        = "${local.policies_dir}/${each.value}"
  gatewayArn      = aws_bedrockagentcore_gateway.this.gateway_arn
  tsAgentRoleName = var.ts_agent_role_name
  # ...
}

Modalità ENFORCE e default-deny

Il PolicyEngine viene eseguito in modalità ENFORCE, il che significa che si applicano semantiche default-deny: se nessuna istruzione permit corrisponde alla tupla (principal, action, resource), la richiesta viene negata. Le chiamate agli strumenti che vengono negate restituiscono:

Tool Execution Denied: Tool call not allowed due to policy enforcement
[No policy applies to the request (denied by default).]

Inoltre, il Gateway filtra la risposta di tools/list in modo che i chiamanti vedano solo gli strumenti per cui hanno almeno un permit corrispondente: se un agente non ha il permesso per un dato strumento, lo strumento viene nascosto completamente piuttosto che apparire e fallire al momento della chiamata.

permit-all.cedar predefinito

Il generatore fornisce una policy predefinita con ambito al tipo di autenticazione del Gateway.

Per un Gateway IAM, permette a qualsiasi chiamante IAM dall’account AWS in cui il Gateway è distribuito:

packages/<name>/policies/permit-all.cedar

permit (
  principal is AgentCore::IamEntity,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
) when {
  principal.id like "arn:aws:*::<%= accountId %>:*"
};

Per un Gateway Cognito, permette a qualsiasi utente OAuth autenticato (l’autorizzatore JWT ha già validato l’user pool e il client del token prima che le policy vengano valutate):

packages/<name>/policies/permit-all.cedar

permit (
  principal is AgentCore::OAuthUser,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

Per bloccare ulteriormente le cose, aggiungi policy più ristrette accanto ad essa. Mantieni sempre almeno un permit corrispondente nel set di policy, altrimenti default-deny bloccherà ogni chiamata.

Riferimento all’ambito delle policy

Il tipo di principal dipende da come il Gateway autentica i chiamanti (vedi Autenticazione).

Per un Gateway IAM, i chiamanti sono principal IAM:

principal is AgentCore::IamEntity

I chiamanti vengono valutati come ARN di ruoli assunti STS con il nome della sessione rimosso, quindi un ruolo può essere abbinato esattamente — non sono necessari caratteri jolly:

principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= myAgentRoleName %>"

Lo stesso valore è disponibile come principal.id per le clausole when. Riserva like per pattern genuini, come la corrispondenza a livello di account nel permit-all.cedar predefinito.

Per un Gateway Cognito, i chiamanti sono utenti OAuth costruiti dal claim sub del token JWT e i claim JWT (username, scope, ecc.) sono disponibili come tag del principal:

principal is AgentCore::OAuthUser

Abbina i singoli claim nelle clausole when — ad esempio per richiedere uno scope:

permit (
  principal is AgentCore::OAuthUser,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
) when {
  principal.scope == "gateway/invoke"
};

Le invocazioni degli strumenti raggiungono il motore di policy come azioni con la forma:

AgentCore::Action::"<target-name>___<tool-name>"

dove <target-name> è il nome del target Gateway (il mcpServerName del server MCP per impostazione predefinita quando si usa gateway.addMcpServer(...), derivato dal nome della classe del progetto MCP in kebab-case — ad es. TsMcp → ts-mcp), <tool-name> è il nome dello strumento MCP e il separatore è ___ (tre underscore). Cedar non supporta caratteri jolly sulle azioni — abbina azioni esatte o ometti action == per abbinare tutte le azioni.

La risorsa è sempre il Gateway stesso:

resource == AgentCore::Gateway::"<%= gatewayArn %>"

Considerazioni sulla validazione

L’infrastruttura generata crea policy con IGNORE_ALL_FINDINGS: l’analizzatore Cedar di AgentCore (FAIL_ON_ANY_FINDINGS, il valore predefinito del servizio) rifiuta molte policy legittime — ad esempio, un forbid che disabilita un singolo strumento per ogni chiamante viene rifiutato come “Overly Restrictive”, anche quando ha un ambito con una clausola when. L’applicazione non è influenzata; è configurata dalla modalità ENFORCE del motore di policy.

Si applica ancora un vincolo di ordinamento: una policy che fa riferimento a AgentCore::Action::"<target>___<tool>" si valida solo una volta che il target ha registrato quello strumento con il Gateway, motivo per cui l’infrastruttura generata crea le policy dopo i target del Gateway.

Se una policy non riesce a essere distribuita, CloudFormation mostra il rifiuto come un errore opaco Resource stabilization failed — esegui aws bedrock-agentcore-control list-policies --policy-engine-id <id> per recuperare i statusReasons del validatore, che contengono il motivo effettivo.

Esempio: vietare uno strumento mantenendo un permit più ampio

Abbina un forbid ristretto con un permit più ampio (Cedar valuta forbid su permit):

packages/<name>/policies/forbid-divide-for-py-agent.cedar

forbid (
  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= pyAgentRoleName %>",
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

Questo nega al ruolo dell’agente Python di chiamare ts-mcp___divide lasciando il permit-all.cedar più ampio in vigore per tutti gli altri chiamanti.

Sviluppo Locale

Il generatore aggiunge un target dev al progetto Gateway, che esegue local-dev.ts. Eseguendolo si avvia il gateway locale e ogni target collegato insieme:

pnpm

pnpm nx dev <name>

yarn

yarn nx dev <name>

npm

npx nx dev <name>

bun

bunx nx dev <name>

protocol = mcp

Il gateway locale espone un singolo endpoint MCP che aggrega ogni server MCP collegato (connesso tramite il generatore agentcore-gateway#mcp-connection), con strumenti prefissati <target>___<tool> per corrispondere al Gateway distribuito.

protocol = http

Il gateway locale inoltra i percorsi /<targetName>/... al server locale di ciascun agente collegato (connesso tramite il generatore agentcore-gateway#agent-connection), corrispondendo al routing basato su percorso del Gateway distribuito.

Vedi le guide di connessione per la storia completa dello sviluppo locale.

Distribuzione del tuo AgentCore Gateway

Il generatore AgentCore Gateway crea infrastruttura come codice CDK o Terraform in base al tuo iac selezionato. Puoi usarlo per distribuire il tuo Gateway.

CDK

Il costrutto CDK per distribuire il tuo Gateway si trova nella cartella common/constructs. Puoi consumarlo in un’applicazione CDK, ad esempio:

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

import { MyGateway } from '@my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new MyGateway(this, 'MyGateway');
  }
}

Questo configura l’infrastruttura del tuo Gateway, inclusi l’AgentCore::Gateway, il suo PolicyEngine Cedar e il Web ACL AWS WAF (vedi AWS WAF sotto). Registra i target dei server MCP con gateway.addMcpServer(...) — vedi la guida di connessione del server MCP.

Terraform

Il modulo Terraform per distribuire il tuo Gateway si trova nella cartella common/terraform. Puoi usarlo in una configurazione Terraform, ad esempio:

packages/infra/src/main.tf

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

Questo configura l’infrastruttura del tuo Gateway, inclusi l’aws_bedrockagentcore_gateway, il suo motore di policy Cedar e il Web ACL AWS WAF (vedi AWS WAF sotto). Registra i target dei server MCP con una risorsa aws_bedrockagentcore_gateway_target — vedi la guida di connessione del server MCP.

AWS WAF

Per impostazione predefinita, il costrutto generato associa un Web ACL AWS WAFv2 al Gateway. AWS WAF ispeziona ogni richiesta in entrata in linea prima che raggiunga un target, proteggendo il tuo Gateway da exploit web, traffico bot e attacchi volumetrici. Il Web ACL utilizza il set di regole predefinito gestito da AWS (AWSManagedRulesCommonRuleSet e AWSManagedRulesKnownBadInputsRuleSet), fornendo protezione contro exploit web comuni inclusi gli OWASP Top 10. I log delle richieste WAF vengono scritti in un gruppo CloudWatch Logs.

Il Web ACL è REGIONAL e creato nella regione del Gateway, come richiesto per le associazioni AgentCore Gateway.

Deviazione di SizeRestrictions_BODY dai valori predefiniti

La regola SizeRestrictions_BODY da AWSManagedRulesCommonRuleSet viene sovrascritta a Count invece di Block, poiché il limite di 8 KB della regola è troppo restrittivo per i payload tipici degli strumenti MCP. Le richieste sovradimensionate verranno comunque registrate come metriche in modo da poterle monitorare. Vedi la guida AWS WAF body size limits per maggiori dettagli.

Puoi modificare il costrutto Gateway generato per aggiungere, rimuovere o regolare le regole (ad esempio, per aggiungere regole basate sulla frequenza o gruppi di regole gestite aggiuntivi).

CDK

Per rinunciare (ad esempio, per collegare il tuo Web ACL), imposta enableWaf su false quando istanzi il costrutto Gateway:

new MyGateway(this, 'MyGateway', {
  enableWaf: false,
});

Il costrutto espone il Web ACL creato come webAcl per ulteriori configurazioni.

Terraform

Per rinunciare (ad esempio, per collegare il tuo Web ACL), imposta enable_waf su false sul modulo Gateway:

module "my_gateway" {
  enable_waf = false
}

Il modulo restituisce l’ARN del Web ACL creato come waf_web_acl_arn per ulteriori configurazioni.

Connessioni

Usa il generatore connection per integrare questo progetto con altri nel tuo workspace. Le seguenti connessioni coinvolgono questo progetto:

AgentCore Gateway a MCP ServerAggrega un server MCP dietro un AgentCore Gateway

AgentCore Gateway a AgentCore GatewayAggrega un AgentCore Gateway dietro un altro AgentCore Gateway

TypeScript Agent a AgentCore GatewayConnetti un TypeScript Agent a un AgentCore Gateway

Python Agent a AgentCore GatewayConnetti un Python Agent a un AgentCore Gateway

AgentCore Gateway a AgentFronteggia un agente con un AgentCore Gateway come target runtime

React Website a AgentCore GatewayConnetti un sito web React agli agenti attraverso un AgentCore Gateway