# Defina la configuración de destino de la puerta de enlace
La configuración del destino depende del tipo de destino que vaya a agregar a la puerta de enlace. Para obtener más información sobre los tipos de destinos de puerta de enlace compatibles, consulte [Destinos compatibles para las AgentCore puertas de enlace de Amazon Bedrock](gateway-supported-targets.md).
Seleccione un tema para ver ejemplos de cómo añadir un tipo de objetivo:
**Topics**
+ [Añadir un objetivo Lambda](#gateway-add-target-api-lambda)
+ [Añadir un objetivo de etapa de API Gateway](#gateway-add-target-api-gateway)
+ [Añadir un objetivo de OpenAPI](#gateway-add-target-api-openapi)
+ [Agregue un objetivo de Smithy](#gateway-add-target-api-smithy)
+ [Agregue un destino de tiempo de ejecución HTTP](#gateway-add-target-api-http-runtime)
+ [Agregue un destino de servidor MCP](#gateway-add-target-api-MCPserver)
+ [Añada un objetivo de Connector con las bases de conocimiento gestionadas de Amazon Bedrock](#gateway-add-target-api-connector-managed-kb)
+ [Agregue un objetivo de Connector con la herramienta de búsqueda web](#gateway-add-target-api-connector-web-search)
## Añadir un objetivo Lambda
Puede añadir un destino Lambda a la puerta de enlace mediante la AgentCore CLI especificando el `--type` as `lambda-function-arn` y proporcionando el ARN de Lambda y un archivo de esquema de la herramienta.
**Configuración de destino**
La configuración de destino (o carga útil) de una función Lambda contiene los siguientes campos:
+ **LambdaARN:** el ARN de la función Lambda que se utilizará como objetivo.
+ **toolSchema: el esquema de herramientas para el** destino de la puerta de enlace.
Para obtener más información sobre los objetivos de Lambda, consulte Objetivos de funciones de [AWS Lambda](gateway-add-target-lambda.md).
Seleccione uno de los siguientes métodos:
**Example**
1. Para añadir una función Lambda como destino, ejecute la `agentcore add gateway-target` `--type lambda-function-arn` opción. Proporcione el ARN de Lambda y un archivo JSON que contenga el esquema de la herramienta:
```
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. Con la AgentCore CLI, puede crear fácilmente un destino Lambda con las configuraciones predeterminadas.
```
# 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
)
```
El siguiente es un ejemplo de argumento que puede proporcionar para. `target_payload` Si omite el `target_payload` argumento, se utilizará esta carga útil:
```
{
"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. El siguiente código de Python muestra cómo añadir un destino Lambda mediante el SDK de 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. En la interfaz de usuario del terminal interactivo AgentCore CLI, ejecute`agentcore`, seleccione **agregar**, elija **Gateway Target** y, a continuación, seleccione la **función Lambda**:
A continuación, el asistente le solicitará el nombre del destino, el ARN de la función Lambda, el archivo de esquema de la herramienta y la configuración de autorización de salida.
## Añadir un objetivo de etapa de API Gateway
Para añadir una etapa de una API REST de API Gateway como destino, especifique el ARN de la API y la etapa y defina los ajustes para filtrar las herramientas de la puerta de enlace de API o para anular los nombres y descripciones de las herramientas de la puerta de enlace:
En los siguientes ejemplos, se muestra cómo añadir un destino de API Gateway. También se aplican las siguientes configuraciones:
+ Las herramientas por las que se filtra son los métodos GET y POST de la `/products` ruta.
+ GET /products se renombra como`get_items`.
Seleccione uno de los métodos siguientes:
**Example**
1. Para añadir una etapa de API REST de API Gateway como destino, ejecute `agentcore add gateway-target` con la `--type api-gateway` opción:
```
agentcore add gateway-target \
--name MyAPIGatewayTarget \
--type api-gateway \
--rest-api-id your-rest-api-id \
--stage your-stage \
--gateway MyGateway
agentcore deploy
```
1. El siguiente comando usa la 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. El siguiente código muestra los usos del SDK de 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. En la interfaz de usuario del terminal interactivo AgentCore CLI`agentcore`, ejecute, seleccione **agregar**, elija **Gateway Target** y, a continuación, seleccione **API REST API**:
A continuación, el asistente le solicitará el nombre del destino, el ID de la API REST, la fase y la configuración de autorización de salida.
## Añadir un objetivo de OpenAPI
Seleccione uno de los siguientes métodos:
**Example**
1. Para añadir un objetivo de esquema de OpenAPI, ejecute la `--type open-api-schema` opción y `agentcore add gateway-target` proporcione la ruta a su archivo de especificaciones de 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. El siguiente código de Python muestra cómo añadir un objetivo de OpenAPI mediante el SDK de AWS Python (Boto3). El esquema se ha cargado en una ubicación de S3 cuyo URI está referenciado en. `target_payload` La autorización de salida para el objetivo se realiza mediante una clave 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. En la interfaz de usuario del terminal interactivo AgentCore CLI, ejecute`agentcore`, seleccione **agregar**, elija **Gateway Target** y, a continuación, seleccione **OpenAPI Schema**:
A continuación, el asistente le solicitará el nombre del destino, la ruta al archivo de especificaciones de OpenAPI y la configuración de autorización de salida.
## Agregue un objetivo de Smithy
Seleccione uno de los siguientes métodos:
**Example**
1. Para añadir un objetivo de modelo de Smithy, ejecute `agentcore add gateway-target` la `--type smithy-model` opción y proporcione la ruta al archivo de modelo de Smithy:
```
agentcore add gateway-target \
--name MySmithyTarget \
--type smithy-model \
--schema path/to/smithy-model.json \
--gateway MyGateway
agentcore deploy
```
1. El siguiente código de Python muestra cómo añadir un objetivo del modelo Smithy mediante el SDK de 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. En la interfaz de usuario del terminal interactivo AgentCore CLI, ejecute`agentcore`, seleccione **agregar**, elija **Gateway Target** y, a continuación, seleccione **Smithy Model:**
A continuación, el asistente le solicitará el nombre del destino, la ruta al archivo del modelo de Smithy y la configuración de la autorización de salida.
## Agregue un destino de tiempo de ejecución HTTP
Puede añadir un agente de Amazon Bedrock AgentCore Runtime como destino HTTP a su puerta de enlace. La puerta de enlace envía el tráfico directamente al agente de tiempo de ejecución sin agregación ni traducción de protocolos.
Para obtener más información sobre los destinos HTTP, consulte los [destinos de Amazon Bedrock AgentCore Runtime](gateway-target-http-runtime.md).
Seleccione uno de los siguientes métodos:
**Example**
1. El siguiente comando crea un destino de tiempo de ejecución HTTP con autorización de 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. El siguiente código de Python muestra cómo añadir un destino de tiempo de ejecución HTTP mediante el SDK de 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"
}
]
)
```
## Agregue un destino de servidor MCP
Puede agregar un destino de servidor MCP mediante la AgentCore CLI o el SDK de AWS Python (Boto3). Los siguientes ejemplos muestran cómo crear un destino de servidor MCP con diferentes tipos de autorización de salida.
**Servidor MCP con autorización de IAM (SiGv4)**
El siguiente ejemplo crea un destino de servidor MCP con autorización de IAM. La puerta de enlace firma las solicitudes al servidor MCP mediante SigV4 con las credenciales del rol de servicio de puerta de enlace. Debe especificar el `service` nombre para la firma. `region`Es opcional y el valor predeterminado es la región de la puerta de enlace.
El valor de `service` depende de dónde esté alojado el servidor MCP. Los siguientes son valores comunes:
+ `bedrock-agentcore`— Para los servidores MCP alojados en Amazon Bedrock AgentCore, como el motor de ejecución (consulte [Implementación de servidores MCP en tiempo de AgentCore ejecución](runtime-mcp.md)) u otra puerta de enlace.
+ `execute-api`— Para servidores MCP detrás de Amazon API Gateway.
+ `lambda`— Para servidores MCP detrás de direcciones URL de funciones Lambda.
Seleccione uno de los siguientes 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. En la interfaz de usuario del terminal interactivo AgentCore CLI, ejecute`agentcore`, seleccione **agregar**, elija **Gateway Target** y, a continuación, seleccione el **punto final del servidor MCP**:
A continuación, el asistente le solicitará el nombre del destino, la URL del punto final del servidor MCP y la configuración de autorización de salida.
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 con autorización de OAuth**
El siguiente ejemplo crea un servidor MCP de destino con autorización OAuth (credenciales de cliente).
Seleccione uno de los siguientes 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 añadir un destino de servidor MCP con autorización de OAuth, ejecute `agentcore add gateway-target` la `--type mcp-server` opción y especifique las credenciales de 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 con autorización de clave API**
El siguiente ejemplo crea un destino de servidor MCP con autorización de clave API.
Seleccione uno de los siguientes 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": ""
}
}
}
]
)
```
## Añada un objetivo de Connector con las bases de conocimiento gestionadas de Amazon Bedrock
Puede añadir el conector de bases de conocimiento gestionadas de Amazon Bedrock como destino a su puerta de enlace.
Para obtener más información sobre el conector de bases de conocimiento gestionadas de Amazon Bedrock, consulte Bases de [conocimiento gestionadas de Amazon Bedrock](gateway-target-connector-managed-kb.md).
### Configure una base de conocimientos gestionada
El conector presenta dos herramientas, cada una con el nombre de su operación de backend: `AgenticRetrieveStream` (recuperación de agentes de streaming en varios pasos) y `Retrieve` (búsqueda híbrida única). Añada una entrada de configuración por herramienta.
Para`AgenticRetrieveStream`, defina `retrievers` (las bases de conocimiento gestionadas que desee consultar) y `agenticRetrieveConfiguration` dentro`parameterValues`. Ambas son obligatorias; si se omiten, se `agenticRetrieveConfiguration` produce un error de tiempo de ejecución. Puede ser un objeto vacío (`{}`) para aceptar los valores predeterminados administrados por el servicio, pero especificar `foundationModelType` y hacer explícita la configuración`rerankingModelType`. El agente no proporciona los ID de la base de conocimientos en el momento de la llamada. Para ello`Retrieve`, configure `knowledgeBaseId` la `parameterValues` entrada; es obligatoria.
El conector solo admite bases de conocimiento gestionadas. Los destinos del conector solo admiten el tipo de proveedor de `GATEWAY_IAM_ROLE` credenciales.
**Example**
1. El siguiente código de Python muestra cómo crear un Gateway Target con la configuración del conector de bases de conocimiento gestionadas por Amazon Bedrock mediante el SDK de 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. El siguiente comando crea un Gateway Target con la configuración del conector de Amazon Bedrock Managed Knowledge Bases mediante la 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 añadir un destino de conector a una base de conocimientos gestionada, ejecute lo siguiente`agentcore add gateway-target`: `--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. En la interfaz de usuario del terminal interactivo AgentCore CLI, ejecute y`agentcore add gateway-target`, a continuación, seleccione **Amazon Bedrock Knowledge Bases** en el selector de tipos de destino:
El asistente le pide un nombre y una descripción y le permite seleccionar uno o más tipos y fuentes de fuentes.
Tras la llamada`CreateGatewayTarget`, el Gateway valida la configuración de forma asíncrona (normalmente en unos 30 segundos), lo que incluye una `GetKnowledgeBase` comprobación de cada base de conocimientos vinculada. Sondea `GetGatewayTarget` hasta que `status` esté`READY`; un `FAILED` estado incluye un motivo que describe el problema.
Para personalizar la recuperación de agentes (por ejemplo, para limitar las iteraciones de planificación o adjuntar una barrera de protección), añada los campos opcionales a. `agenticRetrieveConfiguration` Si los omite, se aplicarán los valores predeterminados gestionados por el servicio. [Para ver todos los valores aceptados, consulte la referencia de configuración.](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 los parámetros que puede configurar el agente
Cada entrada de configuración de la herramienta acepta dos controles de parámetros que determinan lo que ve el agente que realiza la llamada y lo que envía el Gateway a la base de conocimientos:
+ `parameterValues`— valores establecidos por el administrador que se envían a la base de conocimientos en cada llamada, como el límite `knowledgeBaseId` o el valor predeterminado. `numberOfResults` Se utilizan a menos que el agente anule un campo que usted haya expuesto.
+ `parameterOverrides`— una lista que controla los campos de solicitud que el agente puede ver y configurar en el momento de la llamada. Cada entrada tiene:
+ `path`— el campo de la `Retrieve` solicitud, por ejemplo, `$.retrievalQuery.text` o`$.retrievalConfiguration.managedSearchConfiguration.numberOfResults`.
+ `description`— texto opcional que se muestra al agente en el que se describe el campo.
+ `visible`— configurado `true` para mostrar el campo al agente o para ocultarlo sin `false` dejar de enviar cualquier valor predeterminado configurado por el administrador.
`knowledgeBaseId`Encállelo `parameterValues` y no lo exponga.
La siguiente entrada de configuración enlaza la base de conocimientos, establece un valor predeterminado de 10 resultados y expone el texto de la consulta y el recuento de resultados al 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
}
]
}
```
### Configure el rol del servicio de puerta de enlace
Este conector utiliza la **función de ejecución de puerta** de enlace, la función de IAM ARN `CreateGateway` a la que se transfiere y que AgentCore el servicio asume que llama al backend en su nombre. Esta es una función que usted crea, no una función vinculada a un servicio. Para el conector de bases de conocimiento gestionadas de Amazon Bedrock, necesita los siguientes permisos:
+ `bedrock:GetKnowledgeBase`— para validar la base de conocimientos vinculada al crear el objetivo. Con el alcance del recurso de la base de conocimientos gestionada.
+ `bedrock:Retrieve`— para la `Retrieve` herramienta. Con el alcance del recurso de la base de conocimientos gestionada.
+ `bedrock:AgenticRetrieveStream`— para la `AgenticRetrieveStream` herramienta. Esta acción no se limita a un recurso de base de conocimientos gestionado, así que actívala`*`.
El Gateway firma las llamadas de backend como servicio. `bedrock` Incluya `bedrock:GetKnowledgeBase` independientemente de las herramientas que agregue; si agrega solo una herramienta, incluya solo la acción de recuperación de esa herramienta.
**nota**
`bedrock-agentcore:InvokeGateway`no forma parte de la función de ejecución. Ese permiso pertenece a la **persona que llama** (el agente o la aplicación que invoca la puerta de enlace), no a la función que asume la puerta de enlace.
Agregue una política con el siguiente contenido a la función de ejecución asociada a la puerta de enlace:
```
{
"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": "*"
}
]
}
```
El rol de servicio también debe confiar en el AgentCore servicio para que pueda asumir el rol. Adjunta la siguiente política de confianza y ajústala a tu cuenta y a Gateway con las `aws:SourceArn` condiciones `aws:SourceAccount` y condiciones siguientes:
```
{
"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/*"
}
}
}
]
}
```
## Agregue un objetivo de Connector con la herramienta de búsqueda web
Puede añadir un conector integrado como destino a su puerta de enlace. El conector de la herramienta de búsqueda web proporciona funciones de búsqueda web gestionadas sin necesidad de infraestructuras personalizadas ni claves de API.
Para obtener más información sobre el conector de la herramienta de búsqueda en la web, consulte la [herramienta de búsqueda en la web](gateway-target-connector-web-search-tool.md).
### Configure la herramienta de búsqueda web
**Example**
1. El siguiente código de Python muestra cómo crear un destino de puerta de enlace con la configuración del conector de la herramienta de búsqueda web mediante el SDK de 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. El siguiente comando crea un destino de puerta de enlace con la configuración del conector de la herramienta de búsqueda web mediante la 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 añadir un destino a una herramienta de búsqueda web, ejecute `agentcore add gateway-target` con`--type connector --connector web-search`:
```
agentcore add gateway-target \
--name MyWebSearchTarget \
--type connector \
--connector web-search \
--gateway MyGateway
agentcore deploy
```
1. En la interfaz de usuario del terminal interactivo AgentCore CLI, ejecute y`agentcore add gateway-target`, a continuación, seleccione **Amazon Web Search** en el selector de tipos de destino:
El asistente le pide un nombre de destino, la puerta de enlace a la que desea adjuntarlo y una lista opcional de dominios para excluirlos de los resultados de búsqueda.
### Configure el filtrado de dominios
Puede restringir los dominios que la herramienta de búsqueda web puede consultar configurando una lista de dominios denegados. Esto resulta útil para los administradores que desean evitar que los agentes devuelvan resultados de sitios web específicos.
El filtrado de dominios se configura a nivel de herramienta mediante el `parameterValues.domainFilter.exclude` campo al crear o actualizar un Gateway Target. La lista de denegación se aplica en el servidor y está oculta para el LLM; el agente desconoce la restricción y, simplemente, no recibe ningún resultado de los dominios excluidos.
Los siguientes ejemplos crean un objetivo de la herramienta de búsqueda web con un filtrado de dominios que excluye los resultados de y: `blocked-website-1.com` `blocked-website-2.com`
**Example**
1. El siguiente código de Python muestra cómo crear un objetivo de la herramienta de búsqueda web con filtrado de dominios mediante el SDK de 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. El siguiente comando crea un objetivo de la herramienta de búsqueda web con filtrado de dominios mediante la 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. Transfiera una lista de dominios separados por comas a través 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. En la interfaz de usuario del terminal interactivo AgentCore CLI, el asistente Add Gateway Target solicita una lista opcional de dominios separados por comas para excluirlos de los resultados de búsqueda después de seleccionar **Amazon Web Search** y elegir una puerta de enlace. Si se deja el mensaje vacío, se crea el destino sin filtrar el dominio.
También puede actualizar un objetivo existente para agregar o modificar el filtrado de dominios mediante`UpdateGatewayTarget`.
### Configure el rol del servicio de puerta de enlace
La puerta de enlace necesita una función de servicio que permita al AgentCore servicio realizar acciones en su nombre. Para la herramienta de búsqueda web, el rol necesita los siguientes permisos:
+ `bedrock-agentcore:InvokeGateway`— para invocar la puerta de enlace
+ `bedrock-agentcore:InvokeWebSearch`— para autorizar las invocaciones de búsquedas en la web, comprobadas por solicitud con el ARN propiedad del servicio `arn:aws:bedrock-agentcore::aws:tool/web-search.v1`
Agregue una política con el siguiente contenido a la función de servicio asociada a la puerta de enlace:
```
{
"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"
}
]
}
```