Adicionar um alvo Lambda Adicionar um alvo de estágio do API Gateway Adicionar um destino OpenAPI Adicione um alvo de Smithy Adicionar um alvo de tempo de execução HTTP Adicionar um alvo de servidor MCP Adicione um destino de conector com as bases de conhecimento gerenciadas da Amazon Bedrock Adicionar um destino de conector com a ferramenta de pesquisa na Web

Defina a configuração de destino do gateway

A configuração de destino depende do tipo de destino que você está adicionando ao gateway. Para obter mais informações sobre os tipos de destino de gateway compatíveis, consulte Destinos compatíveis para AgentCore gateways Amazon Bedrock.

Selecione um tópico para ver exemplos de adição de um tipo de alvo:

Tópicos

Adicionar um alvo Lambda
Adicionar um alvo de estágio do API Gateway
Adicionar um destino OpenAPI
Adicione um alvo de Smithy
Adicionar um alvo de tempo de execução HTTP
Adicionar um alvo de servidor MCP
Adicione um destino de conector com as bases de conhecimento gerenciadas da Amazon Bedrock
Adicionar um destino de conector com a ferramenta de pesquisa na Web

Adicionar um alvo Lambda

Você pode adicionar um destino Lambda ao seu gateway usando a AgentCore CLI especificando o --type as lambda-function-arn e fornecendo o ARN do Lambda e um arquivo de esquema de ferramentas.

Configuração de destino

A configuração de destino (ou carga útil) de uma função do Lambda contém os seguintes campos:

LambdEarn — O ARN da função Lambda a ser usada como seu alvo.
ToolSchema — O esquema da ferramenta para o destino do gateway.

Para obter mais informações sobre alvos do Lambda, consulte Metas AWS da função do Lambda.

Selecione um dos seguintes métodos:

exemplo

AgentCore CLI

Para adicionar uma função do Lambda como destino, execute agentcore add gateway-target com a --type lambda-function-arn opção. Forneça o ARN do Lambda e um arquivo JSON contendo o esquema da ferramenta:
```
agentcore add gateway-target \
  --name MyLambdaTarget \
  --type lambda-function-arn \
  --lambda-arn arn:aws:lambda:us-east-1:123456789012:function:MyFunction \
  --tool-schema-file tools.json \
  --gateway MyGateway
agentcore deploy
```
Para lambda-function-arn destinos, forneça o esquema da ferramenta para a AgentCore CLI com. --tool-schema-file Para o SDK do AgentCore Python e o Boto3, forneça o esquema da ferramenta com. inlinePayload

AgentCore Python SDK

Com o SDK do AgentCore Python, você pode criar um destino AWS Lambda com configurações padrão.


# Import dependencies
from bedrock_agentcore_starter_toolkit.operations.gateway.client import GatewayClient

# Initialize the client
client = GatewayClient(region_name="us-east-1")

# Create a lambda target.
lambda_target = client.create_mcp_gateway_target(
    gateway=gateway,
    name=None, # If you don't set one, one will be generated.
    target_type="lambda",
    target_payload=None, # Define your own lambda if you pre-created one. Otherwise leave this as None and one will be created for you.
    credentials=None, # If you leave this as None, one will be created for you
)

Veja a seguir um exemplo de argumento que você pode fornecer para target_payload o. Se você omitir o target_payload argumento, essa carga útil será usada:


{
    "lambdaArn": "<insert your lambda arn>",
    "toolSchema": {
        "inlinePayload": [
            {
                "name": "get_weather",
                "description": "Get weather for a location",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "the location e.g. seattle, wa"
                        }
                    },
                    "required": [
                        "location"
                    ]
                }
            },
            {
                "name": "get_time",
                "description": "Get time for a timezone",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "timezone": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "timezone"
                    ]
                }
            }
        ]
    }
}

Boto3

O código Python a seguir mostra como adicionar um destino Lambda usando o SDK do AWS Python (Boto3):


import boto3

# Create the agentcore client
agentcore_client = boto3.client('bedrock-agentcore-control')

# Create a Lambda target
target = agentcore_client.create_gateway_target(
    gatewayIdentifier="your-gateway-id",
    name="LambdaTarget",
    targetConfiguration={
        "mcp": {
            "lambda": {
                "lambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:YourLambdaFunction",
                "toolSchema": {
                    "inlinePayload": [
                        {
                            "name": "get_weather",
                            "description": "Get weather for a location",
                            "inputSchema": {
                                "type": "object",
                                "properties": {"location": {"type": "string"}},
                                "required": ["location"],
                            },
                        },
                        {
                            "name": "get_time",
                            "description": "Get time for a timezone",
                            "inputSchema": {
                                "type": "object",
                                "properties": {"timezone": {"type": "string"}},
                                "required": ["timezone"],
                            },
                        },
                    ]
                }
            }
        }
    },
    credentialProviderConfigurations=[
        {
            "credentialProviderType": "GATEWAY_IAM_ROLE"
        }
    ]
)

Interactive

Na interface do usuário do terminal interativo AgentCore CLI, executeagentcore, selecione Adicionar, escolha Gateway Target e selecione a função Lambda:

Em seguida, o assistente solicita o nome do destino, o ARN da função Lambda, o arquivo do esquema da ferramenta e a configuração de autorização de saída.

Adicionar um alvo de estágio do API Gateway

Para adicionar um estágio de uma API REST API Gateway como destino, especifique o ARN da API e do estágio e defina as configurações para filtrar as ferramentas no gateway da API ou para substituir os nomes e as descrições das ferramentas no gateway:

Os exemplos a seguir mostram como adicionar um alvo do API Gateway. As seguintes configurações também são aplicadas:

As ferramentas filtradas são os métodos GET e POST para o /products caminho.
GET /products é renomeado como. get_items

Selecione um dos seguintes métodos:

exemplo

AgentCore CLI

Para adicionar um estágio da API API Gateway REST API como destino, execute agentcore add gateway-target com a --type api-gateway opção:


agentcore add gateway-target \
  --name MyAPIGatewayTarget \
  --type api-gateway \
  --rest-api-id your-rest-api-id \
  --stage your-stage \
  --gateway MyGateway
agentcore deploy

AWS CLI

O comando a seguir usa a AWS CLI:


aws bedrock-agentcore-control create-gateway-target \
    --gateway-identifier "your-gateway-id" \
    --name "SearchAPITarget" \
    --target-configuration '{
        "mcp": {
            "apiGateway": {
                "restApiId": "your-rest-api-id",
                "stage": "your-stage",
                "apiGatewayToolConfiguration": {
                    "toolFilters": [
                        {
                            "filterPath": "/products",
                            "methods": [
                                "GET",
                                "POST"
                            ]
                        }
                    ],
                    "toolOverrides": [
                        {
                            "path": "/products",
                            "method": "GET",
                            "name": "get_items",
                            "description": "Gets information for items in the list of products."
                        }
                    ]
                }
            }
        }
    }'
    --credential-provider-configurations '[
        {
            "credentialProviderType": "GATEWAY_IAM_ROLE"
        }
    ]'

Boto3

O código a seguir mostra os usos do SDK do AWS Python (Boto3):


import boto3

# Create the client
agentcore_client = boto3.client('bedrock-agentcore-control')

# Create an API gateway REST API target with gateway service role authentication
target = agentcore_client.create_gateway_target(
    gatewayIdentifier="your-gateway-id",
    name="SearchAPITarget",
    targetConfiguration={
        "mcp": {
            "apiGateway": {
                "restApiId": "your-rest-api-id",
                "stage": "your-stage",
                "apiGatewayToolConfiguration": {
                    "toolFilters": [
                        {
                            "filterPath": "/products",
                            "methods": [
                                "GET",
                                "POST"
                            ]
                        }
                    ],
                    "toolOverrides": [
                        {
                            "path": "/products",
                            "method": "GET",
                            "name": "get_item",
                            "description": "Gets information for a specific item in the product list."
                        }
                    ]
                }
            }
        }
    },
    credentialProviderConfigurations=[
        {
            "credentialProviderType": "GATEWAY_IAM_ROLE"
        }
    ]
)

Interactive

Na interface do usuário do terminal interativo AgentCore CLI, executeagentcore, selecione Adicionar, escolha Gateway Target e selecione API Gateway REST API:

Em seguida, o assistente solicita o nome do destino, o ID da API REST, o estágio e a configuração da autorização de saída.

Adicionar um destino OpenAPI

Selecione um dos seguintes métodos:

exemplo

AgentCore CLI

Para adicionar um destino do esquema OpenAPI, execute agentcore add gateway-target com a --type open-api-schema opção e forneça o caminho para seu arquivo de especificação OpenAPI:


agentcore add gateway-target \
  --name MyOpenAPITarget \
  --type open-api-schema \
  --schema path/to/openapi-spec.json \
  --outbound-auth none|api-key|oauth \
  --gateway MyGateway
agentcore deploy

Boto3

O código Python a seguir mostra como adicionar um destino OpenAPI usando o SDK do AWS Python (Boto3). O esquema foi enviado para um local do S3 cujo URI é referenciado no. target_payload A autorização de saída para o alvo é feita por meio de uma chave de API.


import boto3

# Create the client
agentcore_client = boto3.client('bedrock-agentcore-control')

# Create an OpenAPI target with API Key authentication
target = agentcore_client.create_gateway_target(
    gatewayIdentifier="your-gateway-id",
    name="SearchAPITarget",
    targetConfiguration={
        "mcp": {
            "openApiSchema": {
                "s3": {
                    "uri": "s3://your-bucket/path/to/open-api-spec.json",
                    "bucketOwnerAccountId": "123456789012"
                }
            }
        }
    },
    credentialProviderConfigurations=[
        {
            "credentialProviderType": "API_KEY",
            "credentialProvider": {
                "apiKeyCredentialProvider": {
                    "providerArn": "arn:aws:agent-credential-provider:us-east-1:123456789012:token-vault/default/apikeycredentialprovider/abcdefghijk",
                    "credentialLocation": "HEADER",
                    "credentialParameterName": "X-API-Key"
                }
            }
        }
    ]
)

Interactive

Na interface do usuário do terminal interativo AgentCore CLI, executeagentcore, selecione Adicionar, escolha Gateway Target e selecione OpenAPI Schema:

Em seguida, o assistente solicita o nome do destino, o caminho para o arquivo de especificação do OpenAPI e a configuração da autorização de saída.

Adicione um alvo de Smithy

Selecione um dos seguintes métodos:

exemplo

AgentCore CLI

Para adicionar um destino de modelo Smithy, execute agentcore add gateway-target com a --type smithy-model opção e forneça o caminho para seu arquivo de modelo Smithy:
```
agentcore add gateway-target \
  --name MySmithyTarget \
  --type smithy-model \
  --schema path/to/smithy-model.json \
  --gateway MyGateway
agentcore deploy
```

Boto3

O código Python a seguir mostra como adicionar um destino de modelo Smithy usando o SDK do AWS Python (Boto3):


import boto3

# Create the agentcore client
agentcore_client = boto3.client('bedrock-agentcore-control')

# Create a Smithy model target
target = agentcore_client.create_gateway_target(
    gatewayIdentifier="your-gateway-id",
    name="DynamoDBTarget",
    targetConfiguration={
        "mcp": {
            "smithyModel": {
                "s3": {
                    "uri": "s3://your-bucket/path/to/smithy-model.json",
                    "bucketOwnerAccountId": "123456789012"
                }
            }
        }
    },
    credentialProviderConfigurations=[
        {
            "credentialProviderType": "GATEWAY_IAM_ROLE"
        }
    ]
)

Interactive

Na interface do usuário do terminal interativo AgentCore CLI, executeagentcore, selecione Adicionar, escolha Gateway Target e selecione Smithy Model:

Em seguida, o assistente solicita o nome do destino, o caminho para o arquivo de modelo Smithy e a configuração de autorização de saída.

Adicionar um alvo de tempo de execução HTTP

Você pode adicionar um agente Amazon Bedrock AgentCore Runtime como destino HTTP ao seu gateway. O gateway envia tráfego diretamente para o agente de tempo de execução sem agregação ou tradução de protocolo.

Para obter mais informações sobre destinos HTTP, consulte Metas do Amazon Bedrock AgentCore Runtime.

Selecione um dos seguintes métodos:

exemplo

Adicionar um alvo de servidor MCP

Você pode adicionar um destino de servidor MCP usando a AgentCore CLI ou o SDK do AWS Python (Boto3). Os exemplos a seguir mostram como criar um destino de servidor MCP com diferentes tipos de autorização de saída.

Servidor MCP com autorização IAM (SigV4)

O exemplo a seguir cria um destino de servidor MCP com autorização do IAM. O gateway assina solicitações para o servidor MCP usando SigV4 com as credenciais da função de serviço de gateway. Você deve especificar o service nome para assinatura. regionÉ opcional e o padrão é a região do gateway.

O valor de service depende de onde seu servidor MCP está hospedado. A seguir estão os valores comuns:

bedrock-agentcore— Para servidores MCP hospedados no Amazon Bedrock AgentCore, como o tempo de execução (consulte Implantar servidores MCP em AgentCore tempo de execução) ou outro gateway.
execute-api— Para servidores MCP por trás do Amazon API Gateway.
lambda— Para servidores MCP por trás de URLs da função Lambda.

Selecione um dos seguintes métodos:

exemplo

AWS CLI


aws bedrock-agentcore-control create-gateway-target \
    --gateway-identifier "your-gateway-id" \
    --name "MyMCPTarget" \
    --target-configuration '{
        "mcp": {
            "mcpServer": {
                "endpoint": "https://my-server.bedrock-agentcore.us-west-2.api.aws"
            }
        }
    }' \
    --credential-provider-configurations '[{
        "credentialProviderType": "GATEWAY_IAM_ROLE",
        "credentialProvider": {
            "iamCredentialProvider": {
                "service": "bedrock-agentcore",
                "region": "us-west-2"
            }
        }
    }]'

Interactive

Na interface do usuário do terminal interativo AgentCore CLI, executeagentcore, selecione Adicionar, escolha Gateway Target e selecione MCP Server endpoint:

Em seguida, o assistente solicita o nome do alvo, a URL do endpoint do servidor MCP e a configuração da autorização de saída.

Boto3


import boto3

agentcore_client = boto3.client('bedrock-agentcore-control')

target = agentcore_client.create_gateway_target(
    gatewayIdentifier="your-gateway-id",
    name="MyMCPTarget",
    targetConfiguration={
        "mcp": {
            "mcpServer": {
                "endpoint": "https://my-server.bedrock-agentcore.us-west-2.api.aws"
            }
        }
    },
    credentialProviderConfigurations=[
        {
            "credentialProviderType": "GATEWAY_IAM_ROLE",
            "credentialProvider": {
                "iamCredentialProvider": {
                    "service": "bedrock-agentcore",
                    "region": "us-west-2"
                }
            }
        }
    ]
)

Servidor MCP com autorização OAuth

O exemplo a seguir cria um destino de servidor MCP com autorização OAuth (credenciais do cliente).

Selecione um dos seguintes métodos:

exemplo

AWS CLI


aws bedrock-agentcore-control create-gateway-target \
    --gateway-identifier "your-gateway-id" \
    --name "MyMCPTarget" \
    --target-configuration '{
        "mcp": {
            "mcpServer": {
                "endpoint": "https://my-mcp-server.example.com"
            }
        }
    }' \
    --credential-provider-configurations '[{
        "credentialProviderType": "OAUTH",
        "credentialProvider": {
            "oauthCredentialProvider": {
                "providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/oauth2credentialprovider/my-oauth-provider",
                "scopes": []
            }
        }
    }]'

AgentCore CLI

Para adicionar um alvo de servidor MCP com autorização OAuth, execute agentcore add gateway-target com a --type mcp-server opção e especifique as credenciais do OAuth:


agentcore add gateway-target \
  --type mcp-server \
  --name MyMCPTarget \
  --endpoint https://my-mcp-server.example.com \
  --gateway MyGateway \
  --outbound-auth oauth \
  --oauth-client-id my-client \
  --oauth-client-secret my-secret \
  --oauth-discovery-url https://auth.example.com/.well-known/openid-configuration
agentcore deploy

Boto3


import boto3

agentcore_client = boto3.client('bedrock-agentcore-control')

target = agentcore_client.create_gateway_target(
    gatewayIdentifier="your-gateway-id",
    name="MyMCPTarget",
    targetConfiguration={
        "mcp": {
            "mcpServer": {
                "endpoint": "https://my-mcp-server.example.com"
            }
        }
    },
    credentialProviderConfigurations=[
        {
            "credentialProviderType": "OAUTH",
            "credentialProvider": {
                "oauthCredentialProvider": {
                    "providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/oauth2credentialprovider/my-oauth-provider",
                    "scopes": []
                }
            }
        }
    ]
)

Servidor MCP com autorização de chave de API

O exemplo a seguir cria um destino de servidor MCP com autorização de chave de API.

Selecione um dos seguintes métodos:

exemplo

AWS CLI


aws bedrock-agentcore-control create-gateway-target \
    --gateway-identifier "your-gateway-id" \
    --name "MyMCPTarget" \
    --target-configuration '{
        "mcp": {
            "mcpServer": {
                "endpoint": "https://my-mcp-server.example.com"
            }
        }
    }' \
    --credential-provider-configurations '[{
        "credentialProviderType": "API_KEY",
        "credentialProvider": {
            "apiKeyCredentialProvider": {
                "providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-api-key",
                "credentialLocation": "HEADER",
                "credentialParameterName": "x-api-key",
                "credentialPrefix": ""
            }
        }
    }]'

Boto3


import boto3

agentcore_client = boto3.client('bedrock-agentcore-control')

target = agentcore_client.create_gateway_target(
    gatewayIdentifier="your-gateway-id",
    name="MyMCPTarget",
    targetConfiguration={
        "mcp": {
            "mcpServer": {
                "endpoint": "https://my-mcp-server.example.com"
            }
        }
    },
    credentialProviderConfigurations=[
        {
            "credentialProviderType": "API_KEY",
            "credentialProvider": {
                "apiKeyCredentialProvider": {
                    "providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-api-key",
                    "credentialLocation": "HEADER",
                    "credentialParameterName": "x-api-key",
                    "credentialPrefix": ""
                }
            }
        }
    ]
)

Adicione um destino de conector com as bases de conhecimento gerenciadas da Amazon Bedrock

Você pode adicionar o conector Amazon Bedrock Managed Knowledge Bases como destino ao seu gateway.

Para obter mais informações sobre o conector Amazon Bedrock Managed Knowledge Bases, consulte Amazon Bedrock Managed Knowledge Bases.

Configurar uma base de conhecimento gerenciada

O conector expõe duas ferramentas, cada uma com o nome de sua operação de back-end: AgenticRetrieveStream (recuperação de agente de streaming em várias etapas) e Retrieve (uma única pesquisa híbrida). Você adiciona uma entrada de configuração por ferramenta.

ParaAgenticRetrieveStream, defina retrievers (as bases de conhecimento gerenciadas a serem agenticRetrieveConfiguration consultadas) e entreparameterValues. Ambos são obrigatórios — a omissão agenticRetrieveConfiguration causa um erro de tempo de execução. Pode ser um objeto vazio ({}) para aceitar padrões gerenciados pelo serviço, mas especificar foundationModelType e rerankingModelType tornar a configuração explícita. O agente não fornece IDs da base de conhecimento no momento da chamada. ParaRetrieve, defina knowledgeBaseId a parameterValues entrada; é necessário.

O conector oferece suporte somente a bases de conhecimento gerenciadas. Os destinos do conector suportam somente o tipo de provedor de GATEWAY_IAM_ROLE credenciais.

exemplo

Boto3

O código Python a seguir mostra como criar um Gateway Target com a configuração do conector Amazon Bedrock Managed Knowledge Bases usando o SDK do AWS Python (Boto3):


import boto3

gateway_client = boto3.client("bedrock-agentcore-control", region_name="<REGION>")

gateway_client.create_gateway_target(
    name="managed-kb",
    gatewayIdentifier="<GATEWAY_ID>",
    targetConfiguration={
        "mcp": {
            "connector": {
                "source": {"connectorId": "bedrock-knowledge-bases"},
                "configurations": [
                    {
                        "name": "AgenticRetrieveStream",
                        "parameterValues": {
                            "retrievers": [
                                {
                                    "description": "Product documentation",
                                    "configuration": {"knowledgeBase": {"knowledgeBaseId": "<KB_ID_1>"}},
                                },
                                {
                                    "description": "Engineering runbooks",
                                    "configuration": {"knowledgeBase": {"knowledgeBaseId": "<KB_ID_2>"}},
                                },
                            ],
                            "agenticRetrieveConfiguration": {
                                "foundationModelType": "MANAGED",
                                "rerankingModelType": "MANAGED",
                            },
                        },
                    },
                    {
                        "name": "Retrieve",
                        "parameterValues": {"knowledgeBaseId": "<KB_ID>"},
                    },
                ],
            }
        }
    },
    credentialProviderConfigurations=[
        {"credentialProviderType": "GATEWAY_IAM_ROLE"}
    ],
)

AWS CLI

O comando a seguir cria um Gateway Target com a configuração do conector Amazon Bedrock Managed Knowledge Bases usando a AWS CLI:


aws bedrock-agentcore-control create-gateway-target \
  --gateway-identifier "<GATEWAY_ID>" \
  --name "managed-kb" \
  --target-configuration '{
    "mcp": {
      "connector": {
        "source": {
          "connectorId": "bedrock-knowledge-bases"
        },
        "configurations": [
          {
            "name": "AgenticRetrieveStream",
            "parameterValues": {
              "retrievers": [
                {
                  "description": "Product documentation",
                  "configuration": {"knowledgeBase": {"knowledgeBaseId": "<KB_ID_1>"}}
                },
                {
                  "description": "Engineering runbooks",
                  "configuration": {"knowledgeBase": {"knowledgeBaseId": "<KB_ID_2>"}}
                }
              ],
              "agenticRetrieveConfiguration": {
                "foundationModelType": "MANAGED",
                "rerankingModelType": "MANAGED"
              }
            }
          },
          {
            "name": "Retrieve",
            "parameterValues": {
              "knowledgeBaseId": "<KB_ID>"
            }
          }
        ]
      }
    }
  }' \
  --credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
  --region "<REGION>"

AgentCore CLI

Para adicionar um destino de conector de base de conhecimento gerenciada, execute agentcore add gateway-target com--type connector --connector bedrock-knowledge-bases:


agentcore add gateway-target \
  --name MyKnowledgeBaseTarget \
  --type connector \
  --connector bedrock-knowledge-bases \
  --knowledge-base-id <KB_ID> \
  --gateway MyGateway
agentcore deploy

Interactive

Na interface do usuário do terminal interativo AgentCore CLIagentcore add gateway-target, execute e selecione Amazon Bedrock Knowledge Bases no seletor de tipo de destino:

O assistente solicita um nome e uma descrição e permite que você selecione um ou mais tipos e fontes de origem.

Depois da chamadaCreateGatewayTarget, o Gateway valida a configuração de forma assíncrona (normalmente em cerca de 30 segundos), o que inclui uma GetKnowledgeBase verificação em cada base de conhecimento vinculada. Faça uma pesquisa GetGatewayTarget até que status sejaREADY; um FAILED status inclui um motivo que descreve o problema.

Para personalizar a recuperação agente — por exemplo, para limitar as iterações de planejamento ou anexar uma grade de proteção — adicione os campos opcionais a. agenticRetrieveConfiguration Se você os omitir, os padrões gerenciados pelo serviço serão aplicados. Para todos os valores aceitos, consulte Referência de configuração.


{
  "name": "AgenticRetrieveStream",
  "parameterValues": {
    "retrievers": [
      { "configuration": { "knowledgeBase": { "knowledgeBaseId": "<KB_ID>" } } }
    ],
    "agenticRetrieveConfiguration": {
      "maxAgentIteration": 5,
      "policyConfiguration": {
        "guardrailConfiguration": {
          "guardrailId": "<GUARDRAIL_ID>",
          "guardrailVersion": "1"
        }
      }
    }
  }
}

Controle quais parâmetros o agente pode definir

Cada entrada de configuração da ferramenta aceita dois controles de parâmetros que determinam o que o agente chamador vê e o que o Gateway envia para a base de conhecimento:

parameterValues— valores definidos pelo administrador enviados à base de conhecimento em cada chamada, como o limite knowledgeBaseId ou o padrão. numberOfResults Eles são usados, a menos que o agente substitua um campo que você expôs.
parameterOverrides— uma lista que controla quais campos de solicitação o agente pode ver e definir no momento da chamada. Cada entrada tem:
- path— o campo na Retrieve solicitação, por exemplo $.retrievalQuery.text ou$.retrievalConfiguration.managedSearchConfiguration.numberOfResults.
- description— texto opcional mostrado ao agente descrevendo o campo.
- visible— defina true para expor o campo ao agente ou para false ocultá-lo enquanto ainda envia qualquer padrão configurado pelo administrador.

Vincule knowledgeBaseId parameterValues e não o exponha.

A entrada de configuração a seguir vincula a base de conhecimento, define um padrão de 10 resultados e expõe o texto da consulta e a contagem de resultados ao agente:


{
  "name": "Retrieve",
  "description": "Search the knowledge base for relevant documents.",
  "parameterValues": {
    "knowledgeBaseId": "<KB_ID>",
    "retrievalConfiguration": {
      "managedSearchConfiguration": {
        "numberOfResults": 10
      }
    }
  },
  "parameterOverrides": [
    {
      "path": "$.retrievalQuery.text",
      "description": "The search query. Use specific keywords for best results.",
      "visible": true
    },
    {
      "path": "$.retrievalConfiguration.managedSearchConfiguration.numberOfResults",
      "description": "Number of results to retrieve (1-100).",
      "visible": true
    }
  ]
}

Configurar a função de serviço de gateway

Esse conector usa a função de execução do gateway — o ARN da função IAM para o qual você passaCreateGateway, que o AgentCore serviço presume que chama o back-end em seu nome. Essa é uma função que você cria, não uma função vinculada a serviços. Para o conector Amazon Bedrock Managed Knowledge Bases, ele precisa das seguintes permissões:

bedrock:GetKnowledgeBase— para validar a base de conhecimento vinculada quando o alvo é criado. Escopo para o recurso gerenciado da base de conhecimento.
bedrock:Retrieve— para a Retrieve ferramenta. Escopo para o recurso gerenciado da base de conhecimento.
bedrock:AgenticRetrieveStream— para a AgenticRetrieveStream ferramenta. Essa ação não tem como escopo um recurso gerenciado da base de conhecimento, então conceda-a*.

O Gateway assina as chamadas de back-end como o bedrock serviço. Inclua bedrock:GetKnowledgeBase independentemente de quais ferramentas você adicionar; se você adicionar somente uma ferramenta, inclua somente a ação de recuperação dessa ferramenta.

nota

bedrock-agentcore:InvokeGatewaynão faz parte da função de execução. Essa permissão pertence ao chamador — o agente ou aplicativo que invoca o Gateway — não à função que o Gateway assume.

Adicione uma política com o seguinte conteúdo à função de execução anexada ao Gateway:


{
  "Version": "2012-10-17", 
  "Statement": [
    {
      "Sid": "ValidateKnowledgeBase",
      "Effect": "Allow",
      "Action": "bedrock:GetKnowledgeBase",
      "Resource": "arn:aws:bedrock:<REGION>:<ACCOUNT_ID>:knowledge-base/<KB_ID>"
    },
    {
      "Sid": "RetrieveFromKnowledgeBase",
      "Effect": "Allow",
      "Action": "bedrock:Retrieve",
      "Resource": "arn:aws:bedrock:<REGION>:<ACCOUNT_ID>:knowledge-base/<KB_ID>"
    },
    {
      "Sid": "AgenticRetrieveStream",
      "Effect": "Allow",
      "Action": "bedrock:AgenticRetrieveStream",
      "Resource": "*"
    }
  ]
}

A função de serviço também deve confiar no AgentCore serviço para que possa assumir a função. Anexe a seguinte política de confiança, definindo-a em sua conta e no Gateway com as aws:SourceArn condições aws:SourceAccount e.


{
  "Version": "2012-10-17", 
  "Statement": [
    {
      "Sid": "AllowAgentCoreToAssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<ACCOUNT_ID>"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:<REGION>:<ACCOUNT_ID>:gateway/*"
        }
      }
    }
  ]
}

Adicionar um destino de conector com a ferramenta de pesquisa na Web

Você pode adicionar um conector embutido como destino ao seu gateway. O conector da Ferramenta de Pesquisa na Web fornece recursos gerenciados de pesquisa na Web sem exigir infraestrutura personalizada ou chaves de API.

Para obter mais informações sobre o conector da Ferramenta de Pesquisa na Web, consulte Ferramenta de Pesquisa na Web.

Configurar a ferramenta de pesquisa na Web

Opcionalmente, você pode fixar o alvo em uma versão específica do conector, version incluindo-o no source campo. Se você omitirversion, o destino usará a versão padrão atual do conector. Para obter mais informações sobre as versões do conector, consulte Versões do conector.

exemplo

Boto3

O código Python a seguir mostra como criar um destino de gateway com a configuração do conector da Ferramenta de Pesquisa na Web usando o SDK do AWS Python (Boto3):


import boto3

gateway_client = boto3.client("bedrock-agentcore-control", region_name="<REGION>")

gateway_client.create_gateway_target(
    name="web-search-tool",
    gatewayIdentifier="<GATEWAY_ID>",
    targetConfiguration={
        "mcp": {
            "connector": {
                "source": {"connectorId": "web-search", "version": "1.1.0"},
                "configurations": [{"name": "WebSearch", "parameterValues": {}}],
            }
        }
    },
    credentialProviderConfigurations=[
        {"credentialProviderType": "GATEWAY_IAM_ROLE"}
    ],
)

AWS CLI

O comando a seguir cria um Gateway Target com a configuração do conector da Web Search Tool usando a AWS CLI:


aws bedrock-agentcore-control create-gateway-target \
  --gateway-identifier "<GATEWAY_ID>" \
  --name "web-search-tool" \
  --target-configuration '{
    "mcp": {
      "connector": {
        "source": {
          "connectorId": "web-search",
          "version": "1.1.0"
        },
        "configurations": [
          {
            "name": "WebSearch",
            "parameterValues": {}
          }
        ]
      }
    }
  }' \
  --credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
  --region "<REGION>"

AgentCore CLI

Para adicionar um alvo da Ferramenta de Pesquisa na Web, execute agentcore add gateway-target com--type connector --connector web-search:


agentcore add gateway-target \
  --name MyWebSearchTarget \
  --type connector \
  --connector web-search \
  --gateway MyGateway
agentcore deploy

Interactive

Na interface do usuário do terminal interativo AgentCore CLIagentcore add gateway-target, execute e selecione Amazon Web Search no seletor de tipo de destino:

O assistente solicita um nome de destino, o gateway ao qual anexar e uma lista opcional de domínios a serem excluídos dos resultados da pesquisa.

Configurar a filtragem de domínio

Você pode restringir quais domínios a Ferramenta de Pesquisa na Web pode consultar configurando uma lista de inclusão ou exclusão de domínio. Isso é útil para administradores que desejam impedir que agentes retornem resultados de sites específicos.

Target-level lista de exclusão de domínios — Uma lista de domínios excluídos de todas as pesquisas em um alvo, definida na criação do alvo usandoparameterValues.domainFilter.exclude. A lista de exclusão é aplicada no lado do servidor e oculta do agente chamador.
Target-level lista de inclusão de domínio (versão do conector 1.2.0 e posterior) — Além da lista de exclusão, você pode configurar parameterValues.domainFilter.include para restringir as pesquisas a um conjunto específico de domínios.

Request-level filtros (domínio include/exclude e intervalo de datas publicadas) estão disponíveis para o agente chamador na versão do conector 1.2.0 e posterior. Request-level os filtros são compostos com as listas de exclusão e inclusão no nível do alvo: as exclusões e inclusões no nível do alvo sempre se aplicam, e o agente não pode relaxá-las.

Os exemplos a seguir criam um alvo da Ferramenta de Pesquisa na Web fixado em uma versão 1.2.0 com listas de inclusão e exclusão de domínio:

exemplo

Boto3

O código Python a seguir mostra como criar um alvo da Ferramenta de Pesquisa na Web com filtragem de domínio usando o SDK do AWS Python (Boto3):


import boto3

gateway_client = boto3.client("bedrock-agentcore-control", region_name="<REGION>")

gateway_client.create_gateway_target(
    name="web-search-tool",
    gatewayIdentifier="<GATEWAY_ID>",
    targetConfiguration={
        "mcp": {
            "connector": {
                "source": {"connectorId": "web-search", "version": "1.2.0"},
                "configurations": [
                    {
                        "name": "WebSearch",
                        "parameterValues": {
                            "domainFilter": {
                                "include": ["allowed-website-1.com", "allowed-website-2.com"],
                                "exclude": ["blocked-website-1.com", "blocked-website-2.com"]
                            }
                        },
                    }
                ],
            }
        }
    },
    credentialProviderConfigurations=[
        {"credentialProviderType": "GATEWAY_IAM_ROLE"}
    ],
)

AWS CLI

O comando a seguir cria um alvo da Ferramenta de Pesquisa na Web com filtragem de domínio usando a AWS CLI:


aws bedrock-agentcore-control create-gateway-target \
  --gateway-identifier "<GATEWAY_ID>" \
  --name "web-search-tool" \
  --target-configuration '{
    "mcp": {
      "connector": {
        "source": {
          "connectorId": "web-search",
          "version": "1.2.0"
        },
        "configurations": [
          {
            "name": "WebSearch",
            "parameterValues": {
              "domainFilter": {
                "include": ["allowed-website-1.com", "allowed-website-2.com"],
                "exclude": ["blocked-website-1.com", "blocked-website-2.com"]
              }
            }
          }
        ]
      }
    }
  }' \
  --credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
  --region "<REGION>"

AgentCore CLI

Passe uma lista de domínios separados por vírgula via: --exclude-domains


agentcore add gateway-target \
  --name MyWebSearchTarget \
  --type connector \
  --connector web-search \
  --exclude-domains blocked-website-1.com,blocked-website-2.com \
  --gateway MyGateway
agentcore deploy

Interactive

Na interface de usuário do terminal interativo AgentCore CLI, o assistente Add Gateway Target solicita uma lista opcional de domínios separados por vírgulas para excluir dos resultados da pesquisa depois de selecionar o Amazon Web Search e escolher um gateway. Deixar o prompt vazio cria o destino sem filtragem de domínio.

Você também pode atualizar um alvo existente para adicionar ou modificar a filtragem de domínio usandoUpdateGatewayTarget.

Configurar a função de serviço de gateway

O Gateway precisa de uma função de AgentCore serviço que permita que o serviço execute ações em seu nome. Para a Ferramenta de Pesquisa na Web, a função precisa das seguintes permissões:

bedrock-agentcore:InvokeGateway— para invocar o Gateway
bedrock-agentcore:InvokeWebSearch— para autorizar invocações de pesquisa na web, verificadas por solicitação em relação ao ARN de propriedade do serviço arn:aws:bedrock-agentcore:<region>:aws:tool/web-search.v1

Adicione uma política com o seguinte conteúdo à função de serviço anexada ao Gateway:


{
  "Version": "2012-10-17", 
  "Statement": [
    {
      "Sid": "InvokeGateway",
      "Effect": "Allow",
      "Action": "bedrock-agentcore:InvokeGateway",
      "Resource": "arn:aws:bedrock-agentcore:<REGION>:<ACCOUNT_ID>:gateway/*"
    },
    {
      "Sid": "InvokeWebSearch",
      "Effect": "Allow",
      "Action": "bedrock-agentcore:InvokeWebSearch",
      "Resource": "arn:aws:bedrock-agentcore:<REGION>:aws:tool/web-search.v1"
    }
  ]
}

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

Especifique o tipo de autorização e as credenciais

Use um gateway