Adicionar um alvo Lambda Adicionar um alvo de estágio do API Gateway Adicionar um alvo OpenAPI Adicionar um alvo Smithy Adicionar um destino de tempo de execução HTTP Adicionar um destino de servidor MCP Adicione um destino de conector com as bases de conhecimento gerenciadas do Amazon Bedrock Adicione 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 alvo OpenAPI
Adicionar um alvo Smithy
Adicionar um destino de tempo de execução HTTP
Adicionar um destino de servidor MCP
Adicione um destino de conector com as bases de conhecimento gerenciadas do Amazon Bedrock
Adicione 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 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.

Selecione um dos seguintes métodos:

exemplo

AgentCore CLI

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

AgentCore Python SDK

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

Interactive

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:

exemplo

AgentCore CLI

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

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, 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:

exemplo

AgentCore CLI

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

Boto3

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

Interactive

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:

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, 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.

Selecione um dos seguintes métodos:

exemplo

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) 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:

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 destino, 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 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

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 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 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.

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 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. ParaRetrieve, 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.

exemplo

Boto3

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="<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 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 <KB_ID> \
  --gateway MyGateway
agentcore deploy

Interactive

Na interface de 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, uma descrição e permite que você selecione um ou mais tipos e fontes de origem.

Depois de ligarCreateGatewayTarget, 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 sejaREADY; 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.


{
  "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ê 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": "<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 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ê passaCreateGateway, 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: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 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": "<ACCOUNT_ID>"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:<REGION>:<ACCOUNT_ID>: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.

Configurar a ferramenta de pesquisa na Web

exemplo

Boto3

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="<REGION>")

gateway_client.create_gateway_target(
    name="web-search-tool",
    gatewayIdentifier="<GATEWAY_ID>",
    targetConfiguration={
        "mcp": {
            "connector": {
                "source": {"connectorId": "web-search"},
                "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"
        },
        "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 de 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 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

exemplo

Boto3

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="<REGION>")

gateway_client.create_gateway_target(
    name="web-search-tool",
    gatewayIdentifier="<GATEWAY_ID>",
    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"}
    ],
)

AWS CLI

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 "<GATEWAY_ID>" \
  --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 "<REGION>"

AgentCore CLI

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

Interactive

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 usandoUpdateGatewayTarget.

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:<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