# 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](gateway-supported-targets.md).
Selecione um tópico para ver exemplos de adição de um tipo de alvo:
**Topics**
+ [Adicionar um alvo Lambda](#gateway-add-target-api-lambda)
+ [Adicionar um alvo de estágio do API Gateway](#gateway-add-target-api-gateway)
+ [Adicionar um alvo OpenAPI](#gateway-add-target-api-openapi)
+ [Adicionar um alvo Smithy](#gateway-add-target-api-smithy)
+ [Adicionar um destino de tempo de execução HTTP](#gateway-add-target-api-http-runtime)
+ [Adicionar um destino de servidor MCP](#gateway-add-target-api-MCPserver)
+ [Adicione um destino de conector com as bases de conhecimento gerenciadas do Amazon Bedrock](#gateway-add-target-api-connector-managed-kb)
+ [Adicione um destino de conector com a ferramenta de pesquisa na Web](#gateway-add-target-api-connector-web-search)
## Adicionar um alvo Lambda
Você pode adicionar um destino Lambda ao seu gateway usando a AgentCore CLI especificando o as e fornecendo o ARN do `lambda-function-arn` Lambda `--type` e um arquivo de esquema da ferramenta.
**Configuração de destino**
A configuração de destino (ou carga útil) de uma função Lambda contém os seguintes campos:
+ **LambdaArn** — O ARN da função Lambda a ser usada como alvo.
+ **ToolSchema** — O esquema da ferramenta para o destino do gateway.
Para obter mais informações sobre alvos do Lambda, consulte Alvos da função do [AWS Lambda](gateway-add-target-lambda.md).
Selecione um dos seguintes métodos:
**Example**
1. Para adicionar uma função 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
```
1. Com a AgentCore CLI, você pode criar facilmente um destino 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
)
```
A seguir está um exemplo de argumento que você pode fornecer para `target_payload` o. Se você omitir o `target_payload` argumento, essa carga será usada:
```
{
"lambdaArn": "",
"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"
]
}
}
]
}
}
```
1. O código Python a seguir mostra como adicionar um alvo 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"
}
]
)
```
1. **Na interface de usuário do terminal interativo AgentCore CLI, execute, selecione **adicionar `agentcore`**, escolha **Gateway Target** e, em seguida, 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 da autorização de saída.
## Adicionar um alvo de estágio do API Gateway
Para adicionar um estágio de uma API REST do API Gateway como destino, especifique o ARN da API e crie e defina configurações para filtrar ferramentas no gateway de API ou para substituir nomes e descrições de 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 do `/products` caminho.
+ GET /products é renomeado como. `get_items`
Selecione um dos seguintes métodos:
**Example**
1. Para adicionar um estágio da API REST API Gateway 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
```
1. 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"
}
]'
```
1. 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"
}
]
)
```
1. Na interface do usuário do terminal interativo AgentCore CLI, execute, selecione **adicionar `agentcore`**, escolha **Gateway Target** e, em seguida, 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 alvo OpenAPI
Selecione um dos seguintes métodos:
**Example**
1. Para adicionar um destino de 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
```
1. O código Python a seguir mostra como adicionar um destino OpenAPI usando o SDK do AWS Python (Boto3). O esquema foi carregado em um local do S3 cujo URI é referenciado no. `target_payload` A autorização de saída para o destino é 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"
}
}
}
]
)
```
1. **Na interface de usuário do terminal interativo AgentCore CLI, execute, selecione **adicionar `agentcore`**, escolha **Gateway Target** e, em seguida, selecione OpenAPI Schema:**
Em seguida, o assistente solicita o nome do destino, o caminho para o arquivo de especificação da OpenAPI e a configuração da autorização de saída.
## Adicionar um alvo Smithy
Selecione um dos seguintes métodos:
**Example**
1. 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
```
1. 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"
}
]
)
```
1. Na interface do usuário do terminal interativo AgentCore CLI, execute, selecione **adicionar `agentcore`**, escolha **Gateway Target** e selecione **Smithy** Model:
Em seguida, o assistente solicita o nome do destino, o caminho para o arquivo de modelo do Smithy e a configuração da autorização de saída.
## Adicionar um destino de tempo de execução HTTP
Você pode adicionar um agente Amazon Bedrock AgentCore Runtime como um 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 Destinos do [Amazon Bedrock AgentCore Runtime](gateway-target-http-runtime.md).
Selecione um dos seguintes métodos:
**Example**
1. O comando a seguir cria um destino de tempo de execução HTTP com autorização do IAM:
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "MyRuntimeTarget" \
--description "Runtime gateway target" \
--target-configuration '{
"http": {
"agentcoreRuntime": {
"arn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID"
}
}
}' \
--credential-provider-configurations '[{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}]'
```
1. O código Python a seguir mostra como adicionar um destino de tempo de execução HTTP usando o SDK do AWS Python (Boto3):
```
import boto3
agentcore_client = boto3.client('bedrock-agentcore-control')
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="MyRuntimeTarget",
description="Runtime gateway target",
targetConfiguration={
"http": {
"agentcoreRuntime": {
"arn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID"
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]
)
```
## Adicionar um destino de servidor MCP
Você pode adicionar um destino de servidor MCP usando o AgentCore CLI ou o AWS Python SDK (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. O `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 runtime (consulte [Implantar servidores MCP no AgentCore Runtime](runtime-mcp.md)) ou outro gateway.
+ `execute-api`— Para servidores MCP por trás do Amazon API Gateway.
+ `lambda`— Para servidores MCP por trás dos URLs da Função Lambda.
Selecione um dos seguintes métodos:
**Example**
1.
```
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"
}
}
}]'
```
1. Na interface do usuário do terminal interativo AgentCore CLI, execute`agentcore`, selecione **adicionar**, escolha **Gateway Target** e selecione **MCP** Server endpoint:
Em seguida, o assistente solicita o nome do destino, a URL do endpoint do servidor MCP e a configuração da autorização de saída.
1.
```
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:
**Example**
1.
```
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": []
}
}
}]'
```
1. Para adicionar um destino de servidor MCP com autorização do 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
```
1.
```
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:
**Example**
1.
```
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": ""
}
}
}]'
```
1.
```
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 do 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](gateway-target-connector-managed-kb.md) 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 do agente de streaming em várias etapas) e `Retrieve` (uma única pesquisa híbrida). Você adiciona uma entrada de configuração por ferramenta.
Para`AgenticRetrieveStream`, defina `retrievers` (as bases de conhecimento gerenciadas a serem `agenticRetrieveConfiguration` consultadas) e entre`parameterValues`. 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 por serviços, 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. Para`Retrieve`, defina `knowledgeBaseId` a `parameterValues` entrada; é obrigatório.
O conector suporta somente bases de conhecimento gerenciadas. Os alvos do conector oferecem suporte somente ao tipo de provedor de `GATEWAY_IAM_ROLE` credenciais.
**Example**
1. O código Python a seguir mostra como criar um destino de gateway 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="")
gateway_client.create_gateway_target(
name="managed-kb",
gatewayIdentifier="",
targetConfiguration={
"mcp": {
"connector": {
"source": {"connectorId": "bedrock-knowledge-bases"},
"configurations": [
{
"name": "AgenticRetrieveStream",
"parameterValues": {
"retrievers": [
{
"description": "Product documentation",
"configuration": {"knowledgeBase": {"knowledgeBaseId": ""}},
},
{
"description": "Engineering runbooks",
"configuration": {"knowledgeBase": {"knowledgeBaseId": ""}},
},
],
"agenticRetrieveConfiguration": {
"foundationModelType": "MANAGED",
"rerankingModelType": "MANAGED",
},
},
},
{
"name": "Retrieve",
"parameterValues": {"knowledgeBaseId": ""},
},
],
}
}
},
credentialProviderConfigurations=[
{"credentialProviderType": "GATEWAY_IAM_ROLE"}
],
)
```
1. 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 "" \
--name "managed-kb" \
--target-configuration '{
"mcp": {
"connector": {
"source": {
"connectorId": "bedrock-knowledge-bases"
},
"configurations": [
{
"name": "AgenticRetrieveStream",
"parameterValues": {
"retrievers": [
{
"description": "Product documentation",
"configuration": {"knowledgeBase": {"knowledgeBaseId": ""}}
},
{
"description": "Engineering runbooks",
"configuration": {"knowledgeBase": {"knowledgeBaseId": ""}}
}
],
"agenticRetrieveConfiguration": {
"foundationModelType": "MANAGED",
"rerankingModelType": "MANAGED"
}
}
},
{
"name": "Retrieve",
"parameterValues": {
"knowledgeBaseId": ""
}
}
]
}
}
}' \
--credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
--region ""
```
1. Para adicionar um destino de conector gerenciado da base de conhecimento, 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 \
--gateway MyGateway
agentcore deploy
```
1. Na interface de usuário do terminal interativo AgentCore CLI`agentcore add gateway-target`, execute e selecione **Amazon Bedrock Knowledge Bases no seletor** de tipo de destino:
O assistente solicita um nome, uma descrição e permite que você selecione um ou mais tipos e fontes de origem.
Depois de ligar`CreateGatewayTarget`, 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. A pesquisa `GetGatewayTarget` até que `status` seja`READY`; um `FAILED` status inclui um motivo que descreve o problema.
Para personalizar a recuperação do 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 por serviços serão aplicados. Para todos os valores aceitos, consulte [Referência de configuração](gateway-target-connector-managed-kb.md#gateway-target-connector-managed-kb-config-reference).
```
{
"name": "AgenticRetrieveStream",
"parameterValues": {
"retrievers": [
{ "configuration": { "knowledgeBase": { "knowledgeBaseId": "" } } }
],
"agenticRetrieveConfiguration": {
"maxAgentIteration": 5,
"policyConfiguration": {
"guardrailConfiguration": {
"guardrailId": "",
"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ê tenha exposto.
+ `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 como `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": "",
"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 do serviço de gateway
Esse conector usa a **função de execução do gateway** — o ARN da função do IAM para o qual você passa`CreateGateway`, que o AgentCore serviço supõe que chame o back-end em seu nome. Essa é uma função que você cria, não uma função vinculada ao serviço. 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. Escalado para o recurso gerenciado da base de conhecimento.
+ `bedrock:Retrieve`— para a `Retrieve` ferramenta. Escalado 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, portanto, conceda-a`*`.
O Gateway assina as chamadas de back-end como `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:InvokeGateway`nã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:::knowledge-base/"
},
{
"Sid": "RetrieveFromKnowledgeBase",
"Effect": "Allow",
"Action": "bedrock:Retrieve",
"Resource": "arn:aws:bedrock:::knowledge-base/"
},
{
"Sid": "AgenticRetrieveStream",
"Effect": "Allow",
"Action": "bedrock:AgenticRetrieveStream",
"Resource": "*"
}
]
}
```
A função de serviço também deve confiar no AgentCore serviço para que ele possa assumir a função. Anexe a seguinte política de confiança, definindo-a à sua conta e ao 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": ""
},
"ArnLike": {
"aws:SourceArn": "arn:aws:bedrock-agentcore:::gateway/*"
}
}
}
]
}
```
## Adicione 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](gateway-target-connector-web-search-tool.md).
### Configurar a ferramenta de pesquisa na Web
**Example**
1. O código Python a seguir mostra como criar um Gateway Target com a configuração do conector da Web Search Tool usando o SDK do AWS Python (Boto3):
```
import boto3
gateway_client = boto3.client("bedrock-agentcore-control", region_name="")
gateway_client.create_gateway_target(
name="web-search-tool",
gatewayIdentifier="",
targetConfiguration={
"mcp": {
"connector": {
"source": {"connectorId": "web-search"},
"configurations": [{"name": "WebSearch", "parameterValues": {}}],
}
}
},
credentialProviderConfigurations=[
{"credentialProviderType": "GATEWAY_IAM_ROLE"}
],
)
```
1. 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 "" \
--name "web-search-tool" \
--target-configuration '{
"mcp": {
"connector": {
"source": {
"connectorId": "web-search"
},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {}
}
]
}
}
}' \
--credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
--region ""
```
1. 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
```
1. Na interface de usuário do terminal interativo AgentCore CLI`agentcore add gateway-target`, execute e selecione **Amazon Web Search no seletor** de tipo de destino:
O assistente solicita que você forneça um nome de destino, o gateway ao qual se conectar 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 negação de domínio. Isso é útil para administradores que desejam impedir que agentes retornem resultados de sites específicos.
A filtragem de domínio é configurada no nível da ferramenta usando o `parameterValues.domainFilter.exclude` campo ao criar ou atualizar um Gateway Target. A lista de negação é aplicada no lado do servidor e está oculta do LLM — o agente não tem conhecimento da restrição e simplesmente não recebe resultados dos domínios excluídos.
Os exemplos a seguir criam um destino da Ferramenta de Pesquisa na Web com filtragem de domínio que exclui resultados de `blocked-website-1.com` e: `blocked-website-2.com`
**Example**
1. O código Python a seguir mostra como criar um destino 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="")
gateway_client.create_gateway_target(
name="web-search-tool",
gatewayIdentifier="",
targetConfiguration={
"mcp": {
"connector": {
"source": {"connectorId": "web-search"},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {
"domainFilter": {
"exclude": ["blocked-website-1.com", "blocked-website-2.com"]
}
},
}
],
}
}
},
credentialProviderConfigurations=[
{"credentialProviderType": "GATEWAY_IAM_ROLE"}
],
)
```
1. O comando a seguir cria um destino da Ferramenta de Pesquisa na Web com filtragem de domínio usando a AWS CLI:
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "" \
--name "web-search-tool" \
--target-configuration '{
"mcp": {
"connector": {
"source": {
"connectorId": "web-search"
},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {
"domainFilter": {
"exclude": ["blocked-website-1.com", "blocked-website-2.com"]
}
}
}
]
}
}
}' \
--credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
--region ""
```
1. Passe uma lista de domínios separados por vírgulas por meio de: `--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
```
1. Na interface de usuário do terminal interativo da AgentCore CLI, o assistente Add Gateway Target solicita uma lista opcional de domínios separados por vírgula a serem excluídos dos resultados da pesquisa após você selecionar **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 destino existente para adicionar ou modificar a filtragem de domínio usando`UpdateGatewayTarget`.
### Configurar a função do 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::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:::gateway/*"
},
{
"Sid": "InvokeWebSearch",
"Effect": "Allow",
"Action": "bedrock-agentcore:InvokeWebSearch",
"Resource": "arn:aws:bedrock-agentcore::aws:tool/web-search.v1"
}
]
}
```