La configurazione dell'autorizzatore Crea un gateway: esempio di base (autorizzazione JWT personalizzata)Creare un gateway: esempio di base (autorizzazione IAM)Crea un gateway: esempio di base (NONE authorizer)Crea un gateway: esempio di base (autorizzazione AUTHENTICATE_ONLY)Crea un gateway con ricerca semantica Crea un gateway con messaggi di debug Crea un gateway con configurazioni di intercettatori Crea un gateway con una configurazione del motore di policy

Crea un AgentCore gateway utilizzando l'API

Per creare un AgentCore gateway utilizzando l'API, effettua una CreateGateway richiesta con uno degli endpoint del piano di AgentCore controllo.

È necessario specificare almeno i seguenti campi:

name— Il nome del gateway.
roleArn— L'ARN del ruolo del servizio gateway. Per ulteriori informazioni, vedere Autorizzazioni del ruolo del servizio AgentCore Gateway.
authorizerType— Il tipo di autorizzatore da utilizzare per il gateway. Dipende dall'autorizzazione in entrata che hai impostato. Per ulteriori informazioni, consulta Configurare l'autorizzazione in entrata per il gateway.

I seguenti campi opzionali aggiungono metadati al gateway:

protocolType— Il tipo di protocollo per il gateway. Se questa impostazione è impostata suMCP, il gateway funziona in modalità aggregazione e può avere solo destinazioni MCP. Se si omette questo campo, il gateway può avere destinazioni sia MCP che HTTP.
description— Una descrizione del gateway.
tags— Un dizionario di coppie chiave-valore che specifica i tag che è possibile utilizzare per etichettare il gateway a fini di monitoraggio.

I campi rimanenti dipendono dalla configurazione del gateway e dall'eventuale attivazione o meno delle funzionalità personalizzate del gateway:

clientToken— Un valore di token client per garantire che una richiesta venga completata non più di una volta. Se non includi questo token, ne viene generato uno in modo casuale per te. Se non includi un valore, ne viene generato uno in modo casuale per te. Per ulteriori informazioni, consulta Garanzia di idempotenza.
authorizerConfiguration— Se il tipo di autorizzazione èCUSTOM_JWT, è necessario includere questo campo per specificare i parametri di autorizzazione e autenticazione del gateway. Per ulteriori informazioni, consulta La configurazione dell'autorizzatore.
kmsKeyArn— Per crittografare il gateway con una chiave KMS, includi l'ARN della chiave in questo campo. Per ulteriori informazioni, consulta Crittografa il AgentCore gateway con una chiave KMS gestita dal cliente.
exceptionLevel— Per attivare i messaggi di debug quando si richiama il gateway, imposta questo valore su. DEBUG Per ulteriori informazioni, consulta Attivare i messaggi di debug. Per esempi di creazione di un gateway con questa impostazione, consulta Creare un gateway con messaggi di debug.
interceptorConfigurations— Per attivare il codice personalizzato che viene eseguito quando si richiama il gateway, includi questo campo. Per ulteriori informazioni, vedere Utilizzo degli intercettori con Gateway. Per esempi di creazione di un gateway con intercettori, vedi Creare un gateway con configurazioni di intercettatori.
protocolConfiguration— Per includere personalizzazioni per il protocollo gateway, configura le impostazioni in questo campo. Per le opzioni di questa configurazione, vedere GatewayProtocolConfiguration.
- Un'opzione di esempio è l'aggiunta di uno strumento di ricerca degli strumenti nel gateway. Per ulteriori informazioni, consulta Cerca strumenti nel tuo AgentCore gateway con una query in linguaggio naturale. Per esempi di creazione di un gateway con questo strumento di ricerca, consulta Creare un gateway con ricerca semantica.

La configurazione dell'autorizzatore

Se il tuo tipo di autorizzatore èCUSTOM_JWT, devi includere anche una configurazione di autorizzazione nel campo. authorizerConfiguration La struttura di base della configurazione dell'autorizzatore è la seguente:


{
  "customJWTAuthorizer": {
    "discoveryUrl": "string",
    "allowedAudience": ["string"],
    "allowedClients": ["string"],
    "allowedScopes": ["string"],
    "customClaims": see below
  }
}

È necessario fornire l'URL di scoperta per il token di autenticazione. I campi rimanenti definiscono le restrizioni per le dichiarazioni di autenticazione:

allowedAudience— I destinatari o i servizi in grado di gestire il JWT.
allowedClients— I client autorizzati a creare un JWT.
allowedScopes— Gli scopi di ciò limitano l'insieme dei reclami.
customClaims— Una serie di oggetti che consente di definire campi e valori personalizzati che limitano le attestazioni da autenticare. Ogni oggetto è un CustomClaimValidationsType oggetto contiene i seguenti campi:
- inboundTokenClaimName— Il nome del campo di attestazione personalizzato da controllare.
- inboundTokenClaimValueType— Il tipo di dati del valore del reclamo da verificare.
- authorizingClaimMatchValue— Definisce il valore a cui far corrispondere il valore del reclamo. Contiene i seguenti campi:
  - claimMatchOperator— Definisce la relazione da cercare tra il valore di corrispondenza e il valore del reclamo.
  - claimMatchValue— Un oggetto che contiene solo uno dei seguenti campi:
    
    match ValueString — Utilizzato nelle seguenti situazioni:
    
    Se inboundTokenClaimValueType è STRING e claimMatchOperator èEQUALS, specifica una stringa a cui far corrispondere il valore dell'attestazione per l'autenticazione.
    
    Se inboundTokenClaimValueType è STRING_ARRAY e claimMatchOperator èCONTAINS, specificate una stringa che volete che la matrice dei valori dell'attestazione contenga per l'autenticazione.
    
    matchValueArray— Se l'inboundTokenClaimValueTypeis STRING_ARRAY e l'claimMatchOperatorisCONTAINS_ANY, specificate una matrice di valori di cui volete controllare l'autenticazione. Se uno qualsiasi dei valori nella matrice dei valori dell'attestazione corrisponde a uno qualsiasi dei valori inmatchValueArray, l'attestazione può essere autenticata.

Gli esempi seguenti mostrano la struttura degli CustomClaimValidationsType oggetti che è possibile specificare:

Esempio

Per vedere esempi di come creare un gateway, espandi la sezione corrispondente al tuo caso d'uso:

Argomenti

Crea un gateway: esempio di base (autorizzazione JWT personalizzata)

Questa sezione fornisce esempi di base sulla creazione di un gateway.

Nota

Nota quanto segue: * I valori per la configurazione dell'autorizzazione provengono da quando si imposta l'autorizzazione Configura l'autorizzazione in entrata per il tuo gateway in entrata. * Se scegli un'opzione che prevede la specificazione di un ruolo di servizio gateway palese (ARN), assicurati di specificarne uno esistente che hai impostato. Per ulteriori informazioni, consulta Autorizzazioni del ruolo del servizio AgentCore Gateway.

Seleziona uno dei seguenti metodi:

Esempio

AgentCore CLI

La AgentCore CLI fornisce un modo semplice per creare un gateway in un'interfaccia a riga di comando.

Per creare il gateway, si utilizza il agentcore add gateway comando. Il ruolo del servizio gateway e l'autorizzazione di Amazon Cognito vengono configurati automaticamente durante la distribuzione.

Utilizzo di argomenti predefiniti

Esegui il seguente comando in un terminale per creare un gateway senza autorizzazione (impostazione predefinita). Per aggiungere l'autorizzazione JWT personalizzata, specifica i flag di autorizzazione come mostrato nell'esempio seguente:
```
agentcore add gateway --name my-gateway
```
Specificare gli argomenti

Il comando seguente mostra come creare un gateway con autorizzazione JWT personalizzata e configurazione esplicita:
```
agentcore add gateway \
  --name my-gateway \
  --authorizer-type CUSTOM_JWT \
  --discovery-url "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration" \
  --allowed-audience "api.example.com"
agentcore deploy
```
Dopo la distribuzione, lo stato gatewayUrl mostrato da agentcore è l'endpoint da utilizzare quando si richiama il gateway.

Interactive

Esegui agentcore per aprire il TUI, quindi seleziona aggiungi e scegli Gateway:
Inserisci il nome del gateway:
Seleziona Custom JWT come tipo di autorizzazione e premi Invio:
Configura le opzioni avanzate:
Rivedi il riepilogo della configurazione e premi Invio per confermare:

AWS CLI

Esegui il codice seguente in un terminale per creare un gateway di base con la AWS CLI:


aws bedrock-agentcore-control create-gateway \
  --name my-gateway \
  --role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
  --protocol-type MCP \
  --authorizer-type CUSTOM_JWT \
  --authorizer-configuration '{
    "customJWTAuthorizer": {
      "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
      "allowedClients": ["clientId"]
    }
  }'

gatewayUrlNella risposta è l'endpoint da utilizzare quando si richiama il gateway.

AWS Python SDK (Boto3)

Il seguente codice Python mostra come creare un gateway di base con AWS Python SDK (Boto3):


import boto3

# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')

# Create a gateway
gateway = client.create_gateway(
  name="my-gateway",
  roleArn="arn:aws:iam::123456789012:role/my-gateway-service-role",
  protocolType="MCP",
  authorizerType="CUSTOM_JWT",
  authorizerConfiguration={
      "customJWTAuthorizer": {
          "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
          "allowedClients": ["clientId"]
      }
  }
)

print(f"MCP Endpoint: {gateway['gatewayUrl']}")

Creare un gateway: esempio di base (autorizzazione IAM)

Questa sezione fornisce esempi di base sulla creazione di un gateway utilizzando l'autorizzazione IAM. Con l'autorizzazione IAM, non è necessaria una configurazione di autorizzazione.

Nota

La AgentCore CLI non supporta la creazione di gateway con autorizzazione IAM. Usa l'interfaccia a riga di AWS comando o AWS Python SDK (Boto3) per creare un gateway con autorizzazione IAM.

Seleziona uno dei seguenti metodi:

Esempio

Crea un gateway: esempio di base (NONE authorizer)

Questa sezione fornisce esempi di base sulla creazione di un gateway con un tipo di autorizzazione NONE. Questo rappresenta un gateway che non eseguirà l'autenticazione o l'autorizzazione per le richieste in arrivo.

Nota

* Il tipo di autorizzazione NONE rappresenta un gateway che non eseguirà l'autenticazione o l'autorizzazione per le richieste in arrivo. Consulta l'autorizzazione in entrata per problemi di sicurezza e dettagli sull'utilizzo di questa configurazione. * Se scegli un'opzione che prevede la specificazione di un ruolo di servizio gateway palese (ARN), assicurati di specificarne uno esistente che hai configurato. Per ulteriori informazioni, consulta Autorizzazioni del ruolo del servizio AgentCore Gateway.

Seleziona uno dei seguenti metodi:

Esempio

AgentCore CLI

La AgentCore CLI fornisce un modo semplice per creare un gateway con un tipo di autorizzazione NONE in un'interfaccia a riga di comando.

Il comando seguente mostra come creare un gateway con il tipo di autorizzazione NONE:
```
agentcore add gateway \
  --name my-gateway \
  --authorizer-type NONE
agentcore deploy
```
Dopo la distribuzione, lo stato gatewayUrl mostrato da agentcore è l'endpoint da utilizzare quando si richiama il gateway.

Interactive

Esegui agentcore per aprire il TUI, quindi seleziona aggiungi e scegli Gateway:
Inserisci il nome del gateway:
Seleziona NESSUNO come tipo di autorizzazione e premi Invio:
Configura le opzioni avanzate:
Rivedi il riepilogo della configurazione e premi Invio per confermare:

AWS CLI

Esegui il codice seguente in un terminale per creare un gateway con il tipo di autorizzazione NONE utilizzando la CLI AWS :
```
aws bedrock-agentcore-control create-gateway \
  --name my-gateway \
  --role-arn arn:aws:iam::111122223333:role/my-gateway-service-role \
  --protocol-type MCP \
  --authorizer-type NONE
```
gatewayUrlNella risposta è l'endpoint da utilizzare quando si richiama il gateway.

AWS Python SDK (Boto3)

Il seguente codice Python mostra come creare un gateway con il tipo di autorizzazione NONE utilizzando AWS Python SDK (Boto3):


import boto3

# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')

# Create a gateway
gateway = client.create_gateway(
  name="my-gateway",
  roleArn="arn:aws:iam::111122223333:role/my-gateway-service-role",
  protocolType="MCP",
  authorizerType="NONE"
)

print(f"MCP Endpoint: {gateway['gatewayUrl']}")

Crea un gateway: esempio di base (autorizzazione AUTHENTICATE_ONLY)

Questa sezione fornisce esempi di creazione di un gateway con autorizzazione. AUTHENTICATE_ONLY Con questo tipo di autorizzazione, il gateway convalida il token in ingresso ma non esegue l'autorizzazione completa. L'identità o il token autenticato viene quindi passato alla destinazione per l'autorizzazione a valle. Ciò è utile quando si desidera che il gateway verifichi che il chiamante sia autenticato durante la delega delle decisioni di autorizzazione al servizio di destinazione.

Nota

Il tipo di AUTHENTICATE_ONLY autorizzazione richiede una configurazione di autorizzazione JWT. Il gateway convalida il token ma non impone restrizioni relative all'ambito o al pubblico per l'autorizzazione. Se scegli un'opzione che prevede la specificazione di un ruolo di servizio del gateway palese (ARN), assicurati di specificarne uno esistente che hai configurato. Per ulteriori informazioni, consulta Autorizzazioni del ruolo del servizio AgentCore Gateway.

Seleziona uno dei seguenti metodi:

Esempio

Crea un gateway con ricerca semantica

Questa sezione fornisce esempi di base sulla creazione di un gateway con uno strumento che consente di cercare semanticamente gli strumenti pertinenti. Per informazioni su come utilizzare questo strumento, consulta Cerca strumenti nel tuo AgentCore gateway con una query in linguaggio naturale.

Seleziona uno dei seguenti metodi:

Esempio

AgentCore CLI

Per impostazione predefinita, la ricerca semantica è abilitata quando si crea un gateway utilizzando la AgentCore CLI. Per disattivarlo, usa il flag. --no-semantic-search Per creare un gateway con la ricerca semantica predefinita abilitata:
```
agentcore add gateway --name my-gateway
agentcore deploy
```

Interactive

Esegui agentcore per aprire il TUI, quindi seleziona aggiungi e scegli Gateway. La ricerca semantica è abilitata per impostazione predefinita nelle opzioni avanzate:
Inserisci il nome del gateway:
Seleziona il tipo di autorizzazione e premi Invio:
Nelle opzioni avanzate, verifica che la ricerca semantica sia abilitata (questa è l'impostazione predefinita):
Rivedi il riepilogo della configurazione e premi Invio per confermare:

AWS CLI

Attiva la ricerca semantica quando crei un gateway nella AWS CLI specificando searchType as SEMANTIC nell'--protocol-configurationoggetto, come nell'esempio seguente:


aws bedrock-agentcore-control create-gateway \
  --name my-gateway \
  --role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
  --protocol-type MCP \
  --authorizer-type CUSTOM_JWT \
  --authorizer-configuration '{
    "customJWTAuthorizer": {
      "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
      "allowedClients": ["clientId"]
    }
  }' \
  --protocol-configuration '{
    "mcp": {
        "searchType": "SEMANTIC"
    }
  }'

gatewayUrlNella risposta è l'endpoint da utilizzare quando si richiama il gateway.

AWS Python SDK (Boto3)

Attiva la ricerca semantica quando crei un gateway utilizzando AWS Python SDK (Boto3) specificando as nell'oggetto, searchType come SEMANTIC nell'protocolConfigurationesempio seguente:


import boto3

# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')

# Create a gateway
gateway = client.create_gateway(
  name="my-gateway",
  roleArn="arn:aws:iam::123456789012:role/my-gateway-service-role",
  protocolType="MCP",
  authorizerType="CUSTOM_JWT",
  authorizerConfiguration={
      "customJWTAuthorizer": {
          "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
          "allowedClients": ["clientId"]
      }
  },
  protocolConfiguration={
    "mcp": {
        "searchType": "SEMANTIC"
    }
  }
)

print(f"MCP Endpoint: {gateway['gatewayUrl']}")

Crea un gateway con messaggi di debug

È possibile creare un gateway con messaggi di debug specificando il valore as. exceptionLevel DEBUG Questa sezione fornisce esempi di creazione di un gateway con messaggi di debug. Per ulteriori informazioni, consulta Attivare i messaggi di debug.

Nota

L'interfaccia della AgentCore riga di comando non è impostata exceptionLevel per impostazione predefinita. DEBUG È necessario passare il --exception-level DEBUG flag durante la creazione del gateway. È possibile disattivare i messaggi di debug inviando una UpdateGateway richiesta e omettendo l'argomento. exceptionLevel

Seleziona uno dei seguenti metodi:

Esempio

AgentCore CLI

Quando crei un gateway utilizzando la AgentCore CLI, passa il --exception-level flag per abilitare i messaggi di debug:
```
agentcore add gateway --name my-gateway --exception-level DEBUG
agentcore deploy
```

Interactive

Esegui agentcore per aprire il TUI, quindi seleziona aggiungi e scegli Gateway. Nelle opzioni avanzate, puoi abilitare il debug dei messaggi impostando il livello di eccezione su: DEBUG
Inserisci il nome del gateway:
Seleziona il tipo di autorizzazione e premi Invio:
Nelle opzioni avanzate, imposta il livello di eccezione su: DEBUG
Rivedi il riepilogo della configurazione e premi Invio per confermare:

AWS CLI

Esegui il codice seguente in un terminale per creare un gateway con i messaggi di debug attivati nella CLI: AWS


aws bedrock-agentcore-control create-gateway \
  --name my-gateway \
  --role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
  --protocol-type MCP \
  --authorizer-type CUSTOM_JWT \
  --authorizer-configuration '{
    "customJWTAuthorizer": {
      "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
      "allowedClients": ["clientId"]
    }
  }' \
  --exception-level DEBUG

gatewayUrlNella risposta è l'endpoint da utilizzare quando si richiama il gateway.

AWS Python SDK (Boto3)

Il seguente codice Python mostra come creare un gateway di base con AWS Python SDK (Boto3):


import boto3

# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')

# Create a gateway
gateway = client.create_gateway(
  name="my-gateway",
  roleArn="arn:aws:iam::123456789012:role/my-gateway-service-role",
  protocolType="MCP",
  authorizerType="CUSTOM_JWT",
  authorizerConfiguration={
      "customJWTAuthorizer": {
          "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
          "allowedClients": ["clientId"]
      }
  },
  exceptionLevel="DEBUG"
)

print(f"MCP Endpoint: {gateway['gatewayUrl']}")

Crea un gateway con configurazioni di intercettatori

Questa sezione fornisce esempi di creazione di un gateway con intercettori configurati. Gli interceptor verranno richiamati in fase di esecuzione del gateway per ogni richiesta.

Nota

* Gli intercettori verranno richiamati in fase di esecuzione del gateway per ogni richiesta. * Se scegli un'opzione che prevede la specificazione di un ruolo di servizio gateway palese (ARN), assicurati di specificarne uno esistente che hai configurato. Per ulteriori informazioni, consulta Autorizzazioni del ruolo del servizio AgentCore Gateway.

Seleziona uno dei seguenti metodi:

Esempio

AgentCore CLI

Con la AgentCore CLI, create prima il gateway e poi configurate gli intercettori utilizzando la AWS CLI o AWS Python SDK (Boto3).

Crea il gateway:
```
agentcore add gateway \
  --name my-gateway \
  --authorizer-type CUSTOM_JWT \
  --discovery-url "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration" \
  --allowed-audience "api.example.com"
agentcore deploy
```
Dopo la distribuzione, configura gli intercettori sul gateway utilizzando il update-gateway comando AWS CLI o AWS Python SDK (Boto3) come mostrato nelle altre schede.

Interactive

Esegui agentcore per aprire il TUI, quindi seleziona aggiungi e scegli Gateway. Dopo aver creato il gateway, configura gli intercettori usando la AWS CLI o AWS Python SDK (Boto3):
Inserisci il nome del gateway:
Seleziona Custom JWT come tipo di autorizzazione e premi Invio:
Configura le opzioni avanzate:
Rivedi il riepilogo della configurazione e premi Invio per confermare:

Dopo aver creato e distribuito il gateway, configura gli interceptor utilizzando il update-gateway comando AWS CLI o AWS Python SDK (Boto3) come mostrato nelle altre schede.

AWS CLI

Esegui il codice seguente in un terminale per creare un gateway con configurazioni di intercettatori utilizzando la CLI: AWS


aws bedrock-agentcore-control create-gateway \
  --name my-gateway \
  --role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
  --protocol-type MCP \
  --authorizer-type CUSTOM_JWT \
  --authorizer-configuration '{
    "customJWTAuthorizer": {
      "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
      "allowedClients": ["clientId"]
    }
  }' \
  --interceptor-configurations '[{
      "interceptor": {
          "lambda": {
            "arn":"arn:aws:lambda:us-west-2:123456789012:function:my-interceptor-lambda"
          }
      },
      "interceptionPoints": ["REQUEST"]
  }]'

gatewayUrlNella risposta c'è l'endpoint da utilizzare quando si richiama il gateway.

AWS Python SDK (Boto3)

Il seguente codice Python mostra come creare un gateway con configurazioni di intercettatori utilizzando Python SDK (Boto3): AWS


import boto3

# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')

# Create a gateway
gateway = client.create_gateway(
  name="my-gateway",
  roleArn="arn:aws:iam::123456789012:role/my-gateway-service-role",
  protocolType="MCP",
  authorizerType="CUSTOM_JWT",
  authorizerConfiguration={
      "customJWTAuthorizer": {
          "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
          "allowedClients": ["clientId"]
      }
  },
  interceptorConfigurations=[{
      "interceptor": {
          "lambda": {
            "arn":"arn:aws:lambda:us-west-2:123456789012:function:my-interceptor-lambda"
          }
      },
      "interceptionPoints": ["REQUEST"]
  }]
)

print(f"MCP Endpoint: {gateway['gatewayUrl']}")

Crea un gateway con una configurazione del motore di policy

È possibile creare un gateway con una configurazione del policy engine. Un policy engine è un insieme di policy che valuta e autorizza le chiamate agli strumenti degli agenti. Se associato a un gateway, il policy engine intercetta tutte le richieste degli agenti e determina se consentire o negare ogni azione in base alle politiche definite. L'applicazione mode specifica se testare le politiche (LOG_ONLY) o applicarle (). ENFORCE

Esempio

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Crea un gateway (CLI)

Aggiungere obiettivi a un gateway