A configuração do autorizador Crie um gateway: exemplo básico (autorização JWT personalizada)Crie um gateway: exemplo básico (autorização do IAM)Crie um gateway: exemplo básico (NENHUM autorizador)Crie um gateway: exemplo básico (autorização AUTHENTICATE_ONLY)Crie um gateway com pesquisa semântica Crie um gateway com mensagens de depuração Crie um gateway com configurações de interceptor Crie um gateway com uma configuração de mecanismo de políticas

Crie um AgentCore gateway usando a API

Para criar um AgentCore gateway usando a API, faça uma CreateGatewaysolicitação com um dos endpoints do plano de AgentCore controle.

No mínimo, você deve especificar os seguintes campos:

name— O nome do gateway.
roleArn— O ARN da função do serviço de gateway. Para obter mais informações, consulte Permissões de função de serviço do AgentCore Gateway.
authorizerType— O tipo de autorizador a ser usado para o gateway. Depende da autorização de entrada que você configurou. Para obter mais informações, consulte Configurar a autorização de entrada para seu gateway.

Os campos opcionais a seguir adicionam metadados ao seu gateway:

protocolType— O tipo de protocolo para o gateway. Se você definir isso comoMCP, o gateway opera no modo de agregação e só pode ter alvos MCP. Se você omitir esse campo, o gateway poderá ter destinos MCP e HTTP.
description— Uma descrição do gateway.
tags— Um dicionário de pares de valores-chave especificando tags que você pode usar para rotular seu gateway para fins de monitoramento.

Os campos restantes dependem da configuração do gateway e se você deseja alternar os recursos personalizados do gateway:

clientToken— Um valor de token do cliente para garantir que uma solicitação seja concluída no máximo uma vez. Se você não incluir esse token, um será gerado aleatoriamente para você. Se você não incluir um valor, um será gerado aleatoriamente para você. Para obter mais informações, consulte Ensuring idempotency.
authorizerConfiguration— Se o seu tipo de autorizador forCUSTOM_JWT, você deverá incluir esse campo para especificar os parâmetros de autorização e autenticação do gateway. Para obter mais informações, consulte A configuração do autorizador.
kmsKeyArn— Para criptografar seu gateway com uma chave KMS, inclua o ARN da chave nesse campo. Para obter mais informações, consulte Criptografar seu AgentCore gateway com uma chave KMS gerenciada pelo cliente.
exceptionLevel— Para ativar as mensagens de depuração ao invocar o gateway, defina esse valor como. DEBUG Para obter mais informações, consulte Ativar mensagens de depuração. Para exemplos de criação de um gateway com essa configuração, consulte Criar um gateway com mensagens de depuração.
interceptorConfigurations— Para ativar o código personalizado que é executado ao invocar seu gateway, inclua esse campo. Para obter mais informações, consulte Usando interceptores com o Gateway. Para exemplos de criação de um gateway com interceptores, consulte Criar um gateway com configurações de interceptores.
protocolConfiguration— Para incluir personalizações para o protocolo de gateway, defina as configurações nesse campo. Para obter opções nessa configuração, consulte GatewayProtocolConfiguration.
- Um exemplo de opção é a adição de uma ferramenta de busca de ferramentas em seu gateway. Para obter mais informações, consulte Pesquisar ferramentas em seu AgentCore gateway com uma consulta de linguagem natural. Para exemplos de criação de um gateway com essa ferramenta de pesquisa, consulte Criar um gateway com pesquisa semântica.

A configuração do autorizador

Se o seu tipo de autorizador forCUSTOM_JWT, você também deverá incluir uma configuração de autorizador no authorizerConfiguration campo. A estrutura básica da configuração do autorizador é a seguinte:


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

Você deve fornecer o URL de descoberta para o token de autenticação. Os campos restantes definem restrições para as declarações de autenticação:

allowedAudience— Os públicos ou serviços que podem lidar com o JWT.
allowedClients— Os clientes que têm permissão para criar um JWT.
allowedScopes— Os escopos disso limitam o conjunto de reivindicações.
customClaims— Uma matriz de objetos que permite definir campos e valores personalizados que limitam as declarações a serem autenticadas. Cada objeto é um CustomClaimValidationsType objeto que contém os seguintes campos:
- inboundTokenClaimName— O nome do campo de declaração personalizado a ser verificado.
- inboundTokenClaimValueType— O tipo de dados do valor da reclamação a ser verificado.
- authorizingClaimMatchValue— Define o valor ao qual corresponder ao valor da reclamação. Contém os seguintes campos:
  - claimMatchOperator— Define a relação a ser procurada entre o valor da correspondência e o valor da reclamação.
  - claimMatchValue— Um objeto que contém somente um dos seguintes campos:
    
    match ValueString — Usado nas seguintes situações:
    
    Se for STRING e inboundTokenClaimValueType claimMatchOperator forEQUALS, especifique uma string com a qual você deseja que o valor da declaração corresponda para autenticação.
    
    Se for STRING_ARRAY e inboundTokenClaimValueType claimMatchOperator forCONTAINS, especifique uma string que você deseja que a matriz de valores da declaração contenha para autenticação.
    
    matchValueArray— Se inboundTokenClaimValueType for STRING_ARRAY e claimMatchOperator forCONTAINS_ANY, especifique uma matriz de valores que você deseja verificar para autenticação. Se algum dos valores na matriz de valores da declaração corresponder a qualquer um dos valores nomatchValueArray, a declaração poderá ser autenticada.

Os exemplos a seguir mostram a estrutura dos CustomClaimValidationsType objetos que você pode especificar:

exemplo

Para ver exemplos de como criar um gateway, expanda a seção que corresponde ao seu caso de uso:

Tópicos

Crie um gateway: exemplo básico (autorização JWT personalizada)

Esta seção fornece exemplos básicos da criação de um gateway.

nota

Observe o seguinte: * Os valores para a configuração de autorização são de quando você configura a autorização de entrada. * Se você escolher uma opção que envolva a especificação de um ARN de função de serviço de gateway aberto, certifique-se de especificar um ARN existente que você tenha configurado. Para obter mais informações, consulte Permissões de função de serviço do AgentCore Gateway.

Selecione um dos seguintes métodos:

exemplo

AgentCore CLI

A AgentCore CLI fornece uma maneira simples de criar um gateway em uma interface de linha de comando.

Para criar o gateway, você usa o agentcore add gateway comando. A função do serviço de gateway e a autorização do Amazon Cognito são configuradas automaticamente para você durante a implantação.

Usando argumentos padrão

Execute o comando a seguir em um terminal para criar um gateway sem autorização (o padrão). Para adicionar a autorização personalizada do JWT, especifique os sinalizadores do autorizador conforme mostrado no próximo exemplo:
```
agentcore add gateway --name my-gateway
```
Especificando argumentos

O comando a seguir mostra como criar um gateway com autorização JWT personalizada e configuração explícita:
```
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
```
Após a implantação, o status gatewayUrl mostrado pelo agentcore é o endpoint a ser usado quando você invoca o gateway.

Interactive

Execute agentcore para abrir a TUI, selecione adicionar e escolha Gateway:
Insira o nome do gateway:
Selecione Custom JWT como o tipo de autorizador e pressione Enter:
Configure as opções avançadas:
Revise o resumo da configuração e pressione Enter para confirmar:

AWS CLI

Execute o código a seguir em um terminal para criar um gateway básico com a 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"]
    }
  }'

O gatewayUrl na resposta é o endpoint a ser usado quando você invoca o gateway.

AWS Python SDK (Boto3)

O código Python a seguir mostra como criar um gateway básico com o SDK do AWS Python (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']}")

Crie um gateway: exemplo básico (autorização do IAM)

Esta seção fornece exemplos básicos da criação de um gateway usando a autorização do IAM. Com a autorização do IAM, você não precisa de uma configuração de autorizador.

nota

A AgentCore CLI não oferece suporte à criação de gateways com autorização do IAM. Use a interface de linha de AWS comando ou o SDK do AWS Python (Boto3) para criar um gateway com autorização do IAM.

Selecione um dos seguintes métodos:

exemplo

Crie um gateway: exemplo básico (NENHUM autorizador)

Esta seção fornece exemplos básicos da criação de um gateway com um tipo de autorizador NONE. Isso representa um gateway que não executará autenticação ou autorização para nenhuma solicitação recebida.

nota

* O tipo de autorizador NONE representa um gateway que não executará autenticação ou autorização para nenhuma solicitação recebida. Consulte a autorização de entrada para obter informações sobre questões de segurança e detalhes sobre o uso dessa configuração. * Se você escolher uma opção que envolva a especificação de um ARN de função de serviço de gateway aberto, certifique-se de especificar um ARN existente que você tenha configurado. Para obter mais informações, consulte Permissões de função de serviço do AgentCore Gateway.

Selecione um dos seguintes métodos:

exemplo

AgentCore CLI

A AgentCore CLI fornece uma maneira simples de criar um gateway com o tipo de autorizador NONE em uma interface de linha de comando.

O comando a seguir mostra como criar um gateway com o tipo de autorizador NONE:
```
agentcore add gateway \
  --name my-gateway \
  --authorizer-type NONE
agentcore deploy
```
Após a implantação, o status gatewayUrl mostrado pelo agentcore é o endpoint a ser usado quando você invoca o gateway.

Interactive

Execute agentcore para abrir a TUI, selecione adicionar e escolha Gateway:
Insira o nome do gateway:
Selecione NENHUM como o tipo de autorizador e pressione Enter:
Configure as opções avançadas:
Revise o resumo da configuração e pressione Enter para confirmar:

AWS CLI

Execute o código a seguir em um terminal para criar um gateway com o tipo de autorizador NONE usando a AWS CLI:
```
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
```
O gatewayUrl na resposta é o endpoint a ser usado quando você invoca o gateway.

AWS Python SDK (Boto3)

O código Python a seguir mostra como criar um gateway com o tipo de autorizador NONE usando o SDK do AWS Python (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']}")

Crie um gateway: exemplo básico (autorização AUTHENTICATE_ONLY)

Esta seção fornece exemplos de criação de um gateway com AUTHENTICATE_ONLY autorização. Com esse tipo de autorizador, o gateway valida o token de entrada, mas não executa a autorização completa. A identidade ou token autenticado é então passado para o destino para autorização posterior. Isso é útil quando você deseja que o gateway verifique se o chamador está autenticado ao delegar decisões de autorização ao serviço de destino.

nota

O tipo de AUTHENTICATE_ONLY autorizador exige uma configuração de autorizador JWT. O gateway valida o token, mas não impõe restrições de escopo ou público para autorização. Se você escolher uma opção que envolva a especificação de um ARN de função de serviço de gateway aberto, certifique-se de especificar um ARN existente que você tenha configurado. Para obter mais informações, consulte Permissões de função de serviço do AgentCore Gateway.

Selecione um dos seguintes métodos:

exemplo

Crie um gateway com pesquisa semântica

Esta seção fornece exemplos básicos da criação de um gateway com uma ferramenta para permitir que você pesquise semanticamente por ferramentas relevantes. Para saber como usar essa ferramenta, consulte Pesquisar ferramentas em seu AgentCore gateway com uma consulta de linguagem natural.

Selecione um dos seguintes métodos:

exemplo

AgentCore CLI

Por padrão, a pesquisa semântica é habilitada quando você cria um gateway usando a AgentCore CLI. Para desativá-lo, use a --no-semantic-search bandeira. Para criar um gateway com a pesquisa semântica padrão ativada:
```
agentcore add gateway --name my-gateway
agentcore deploy
```

Interactive

Execute agentcore para abrir a TUI, selecione adicionar e escolha Gateway. A pesquisa semântica é ativada por padrão nas opções avançadas:
Insira o nome do gateway:
Selecione o tipo de autorizador e pressione Enter:
Nas opções avançadas, verifique se a pesquisa semântica está ativada (esse é o padrão):
Revise o resumo da configuração e pressione Enter para confirmar:

AWS CLI

Ative a pesquisa semântica ao criar um gateway na AWS CLI searchType especificando como no objeto, SEMANTIC como --protocol-configuration no exemplo a seguir:


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

O gatewayUrl na resposta é o endpoint a ser usado quando você invoca o gateway.

AWS Python SDK (Boto3)

Ative a pesquisa semântica ao criar um gateway usando o SDK do AWS Python (Boto3) searchType especificando como no objeto, SEMANTIC como no exemplo protocolConfiguration a seguir:


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']}")

Crie um gateway com mensagens de depuração

Você pode criar um gateway com mensagens de depuração especificando o valor como. exceptionLevel DEBUG Esta seção fornece exemplos de criação de um gateway com mensagens de depuração. Para saber mais, consulte Ativar mensagens de depuração.

nota

A AgentCore CLI não está definida como DEBUG por exceptionLevel padrão. Você deve passar a --exception-level DEBUG bandeira ao criar o gateway. Você pode desativar as mensagens de depuração enviando uma UpdateGatewaysolicitação e omitindo o argumento. exceptionLevel

Selecione um dos seguintes métodos:

exemplo

AgentCore CLI

Ao criar um gateway usando a AgentCore CLI, passe o --exception-level sinalizador para ativar as mensagens de depuração:
```
agentcore add gateway --name my-gateway --exception-level DEBUG
agentcore deploy
```

Interactive

Execute agentcore para abrir a TUI, selecione adicionar e escolha Gateway. Nas opções avançadas, você pode ativar as mensagens de depuração definindo o nível de exceção como: DEBUG
Insira o nome do gateway:
Selecione o tipo de autorizador e pressione Enter:
Nas opções avançadas, defina o nível de exceção comoDEBUG:
Revise o resumo da configuração e pressione Enter para confirmar:

AWS CLI

Execute o código a seguir em um terminal para criar um gateway com mensagens de depuração ativadas na 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

O gatewayUrl na resposta é o endpoint a ser usado quando você invoca o gateway.

AWS Python SDK (Boto3)

O código Python a seguir mostra como criar um gateway básico com o SDK do AWS Python (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']}")

Crie um gateway com configurações de interceptor

Esta seção fornece exemplos de criação de um gateway com interceptores configurados. Os interceptores serão invocados no tempo de execução do gateway para cada solicitação.

nota

* Os interceptores serão invocados no tempo de execução do gateway para cada solicitação. * Se você escolher uma opção que envolva a especificação de um ARN de função de serviço de gateway aberto, certifique-se de especificar um ARN existente que você tenha configurado. Para obter mais informações, consulte Permissões de função de serviço do AgentCore Gateway.

Selecione um dos seguintes métodos:

exemplo

AgentCore CLI

Com a AgentCore CLI, primeiro crie o gateway e depois configure os interceptores usando a CLI AWS ou o SDK do Python AWS (Boto3).

Crie o 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
```
Após a implantação, configure os interceptores no gateway usando o comando AWS update-gateway CLI ou o SDK do AWS Python (Boto3), conforme mostrado nas outras guias.

Interactive

Execute agentcore para abrir a TUI, selecione adicionar e escolha Gateway. Depois de criar o gateway, configure os interceptores usando a AWS CLI ou o SDK do AWS Python (Boto3):
Insira o nome do gateway:
Selecione Custom JWT como o tipo de autorizador e pressione Enter:
Configure as opções avançadas:
Revise o resumo da configuração e pressione Enter para confirmar:

Depois que o gateway for criado e implantado, configure os interceptores usando o comando AWS CLI update-gateway ou o SDK do AWS Python (Boto3), conforme mostrado nas outras guias.

AWS CLI

Execute o código a seguir em um terminal para criar um gateway com configurações de interceptor usando a 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"]
  }]'

O gatewayUrl na resposta é o endpoint a ser usado quando você invoca o gateway.

AWS Python SDK (Boto3)

O código Python a seguir mostra como criar um gateway com configurações de interceptor usando o SDK do AWS Python (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"]
      }
  },
  interceptorConfigurations=[{
      "interceptor": {
          "lambda": {
            "arn":"arn:aws:lambda:us-west-2:123456789012:function:my-interceptor-lambda"
          }
      },
      "interceptionPoints": ["REQUEST"]
  }]
)

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

Crie um gateway com uma configuração de mecanismo de políticas

Você pode criar um gateway com uma configuração de mecanismo de políticas. Um mecanismo de políticas é um conjunto de políticas que avalia e autoriza chamadas de ferramentas de agentes. Quando associado a um gateway, o mecanismo de políticas intercepta todas as solicitações do agente e determina se deve permitir ou negar cada ação com base nas políticas definidas. A fiscalização mode especifica se as políticas devem ser testadas (LOG_ONLY) ou aplicadas (ENFORCE).

exemplo

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Crie um gateway (CLI)

Adicionar alvos a um gateway