AgentCore Gateway

Genera un progetto Amazon Bedrock AgentCore Gateway. Un AgentCore Gateway è un punto di ingresso gestito che aggrega uno o più target di server MCP dietro un singolo endpoint MCP, autentica le richieste in ingresso (IAM o Cognito), valuta ogni chiamata di strumento rispetto a un motore di policy Cedar e firma il traffico in uscita verso i server MCP con IAM SigV4.

Utilizzo

Generare un AgentCore Gateway

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

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

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	mcp	Il protocollo in ingresso esposto dal tuo gateway. Attualmente è supportato solo mcp; protocolli aggiuntivi potrebbero essere aggiunti in futuro.
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 (omessi quando cedarPolicy: false)

    • permit-all.cedar Policy Cedar predefinita che permette ai chiamanti autenticati (chiamanti IAM dallo stesso account AWS, o qualsiasi utente Cognito — vedi Autenticazione)
    • README.md Riferimento per scrivere policy Cedar
  • local-dev.ts Gateway locale che aggrega i server MCP collegati per lo sviluppo locale
  • project.json Aggiunge i target serve e dev

Infrastruttura

L’infrastruttura viene generata quando infra è agentcore (l’impostazione predefinita). Con infra: none non viene generata alcuna infrastruttura — riesegui il generatore con infra: agentcore in seguito per aggiungerla.

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

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

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Construct per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Construct generici riutilizzati dai construct in app

      • …
    • index.ts Punto di ingresso che esporta i construct da app
  • project.json Target di build e configurazione del progetto

Progetto generato

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

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Moduli Terraform per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Moduli generici riutilizzati dai moduli in app

      • …
  • project.json Target di build e configurazione del progetto

Progetto generato

Questo progetto è generato utilizzando il terraform#project generator 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 il deploy del Gateway

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorygateways

      • Directory<name>/

        • <name>.tf Modulo Terraform per il deploy del Gateway

Il costrutto generato crea le seguenti risorse AWS:

• Un AgentCore::Gateway configurato per il protocollo MCP con autenticazione IAM in ingresso (predefinita) o autenticazione JWT Cognito (vedi Autenticazione)
• Un AgentCore::PolicyEngine in esecuzione in modalità ENFORCE, collegato al Gateway (omesso quando cedarPolicy: false)
• Una AgentCore::Policy per ogni file .cedar in policies/
• Un AWS WAFv2 Web ACL associato al Gateway, con registrazione delle richieste su CloudWatch (abilitato per impostazione predefinita — vedi AWS WAF)

L’URL del Gateway viene automaticamente registrato nel namespace 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 AWS WAFv2 Web ACL 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 ingresso. 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 questa opzione quando i tuoi chiamanti sono utenti finali che si autenticano tramite Cognito (ad esempio un sito web o un client non-AWS).

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

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.

Scrivere 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 attraversa il Gateway viene valutata rispetto al set di policy allegato, e il chiamante deve avere almeno un’istruzione permit corrispondente (e nessun forbid corrispondente) affinché la richiesta abbia successo.

Consulta la documentazione AWS sulle policy di 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 del deploy — suddividili 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 di seguito) anziché codificarlo in modo fisso. Esegui nuovamente 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 anziché codificare i valori in modo fisso.

Aggiungere le proprie variabili

Aggiungi nuove variabili dove le policy vengono renderizzate, 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 determinato strumento, lo strumento viene nascosto completamente anziché 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 sull’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 assumed-role 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 formato 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, oppure 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, l’impostazione predefinita 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 delimitato con una clausola when. L’applicazione non è influenzata; è configurata dalla modalità ENFORCE del motore di policy.

Un vincolo di ordinamento si applica ancora: una policy che fa riferimento a AgentCore::Action::"<target>___<tool>" viene validata solo dopo 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 presenta 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 sopra 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 agente Python la chiamata a 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: un gateway locale che 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. Eseguendolo si avviano insieme il gateway locale e tutti i server MCP collegati:

pnpm

pnpm nx dev <name>

yarn

yarn nx dev <name>

npm

npx nx dev <name>

bun

bunx nx dev <name>

Consulta la guida alla connessione per la storia completa dello sviluppo locale.

Distribuire il tuo AgentCore Gateway

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

CDK

Il costrutto CDK per distribuire il tuo Gateway si trova nella cartella common/constructs. Puoi utilizzarlo 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 AgentCore::Gateway, il suo PolicyEngine Cedar e il AWS WAF Web ACL (vedi AWS WAF di seguito). Registra i target dei server MCP con gateway.addMcpServer(...) — vedi la guida alla 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 aws_bedrockagentcore_gateway, il suo motore di policy Cedar e il AWS WAF Web ACL (vedi AWS WAF di seguito). Registra i target dei server MCP con una risorsa aws_bedrockagentcore_gateway_target — vedi la guida alla connessione del server MCP.

AWS WAF

Per impostazione predefinita, il costrutto generato associa un AWS WAFv2 Web ACL al Gateway. AWS WAF ispeziona ogni richiesta in ingresso 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 dalle impostazioni predefinite

La regola SizeRestrictions_BODY di AWSManagedRulesCommonRuleSet viene sovrascritta a Count anziché Block, poiché il limite di 8 KB della regola è troppo restrittivo per i payload tipici degli strumenti MCP. Le richieste di dimensioni eccessive verranno comunque registrate come metriche in modo da poterle monitorare. Consulta la guida sui limiti di dimensione del corpo di AWS WAF 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 disattivare (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 disattivare (ad esempio, per collegare il tuo Web ACL), imposta enable_waf su false nel 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 to MCP ServerAggrega un server MCP dietro un AgentCore Gateway

AgentCore Gateway to AgentCore GatewayAggrega un AgentCore Gateway dietro un altro AgentCore Gateway

TypeScript Agent to AgentCore GatewayCollega un TypeScript Agent a un AgentCore Gateway

Python Agent to AgentCore GatewayCollega un Python Agent a un AgentCore Gateway