Añadir un objetivo Lambda Añadir un objetivo de etapa de API Gateway Añadir un objetivo de OpenAPI Agregue un objetivo de Smithy Agregue un destino de tiempo de ejecución HTTP Agregue un destino de servidor MCP Añada un objetivo de Connector con las bases de conocimiento gestionadas de Amazon Bedrock Agregue un objetivo de Connector con la herramienta de búsqueda web

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.

Seleccione un tema para ver ejemplos de cómo añadir un tipo de objetivo:

Temas

Añadir un objetivo Lambda
Añadir un objetivo de etapa de API Gateway
Añadir un objetivo de OpenAPI
Agregue un objetivo de Smithy
Agregue un destino de tiempo de ejecución HTTP
Agregue un destino de servidor MCP
Añada un objetivo de Connector con las bases de conocimiento gestionadas de Amazon Bedrock
Agregue un objetivo de Connector con la herramienta de búsqueda web

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.

Seleccione uno de los siguientes métodos:

ejemplo

AgentCore CLI

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

AgentCore Python SDK

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

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

Interactive

En la interfaz de usuario del terminal interactivo AgentCore CLI, ejecuteagentcore, 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 comoget_items.

Seleccione uno de los métodos siguientes:

ejemplo

AgentCore CLI

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

AWS CLI

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

Boto3

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

Interactive

En la interfaz de usuario del terminal interactivo AgentCore CLIagentcore, 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:

ejemplo

AgentCore CLI

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

Boto3

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

Interactive

En la interfaz de usuario del terminal interactivo AgentCore CLI, ejecuteagentcore, 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:

ejemplo

AgentCore CLI

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

Boto3

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

Interactive

En la interfaz de usuario del terminal interactivo AgentCore CLI, ejecuteagentcore, 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.

Seleccione uno de los siguientes métodos:

ejemplo

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

ejemplo

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

En la interfaz de usuario del terminal interactivo AgentCore CLI, ejecuteagentcore, 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.

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

ejemplo

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

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

ejemplo

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

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.

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.

ParaAgenticRetrieveStream, defina retrievers (las bases de conocimiento gestionadas que desee consultar) y agenticRetrieveConfiguration dentroparameterValues. 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ónrerankingModelType. El agente no proporciona los ID de la base de conocimientos en el momento de la llamada. Para elloRetrieve, 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.

ejemplo

Boto3

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

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 "<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 añadir un destino de conector a una base de conocimientos gestionada, ejecute lo siguienteagentcore add gateway-target: --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

En la interfaz de usuario del terminal interactivo AgentCore CLI, ejecute yagentcore 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 llamadaCreateGatewayTarget, 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.


{
  "name": "AgenticRetrieveStream",
  "parameterValues": {
    "retrievers": [
      { "configuration": { "knowledgeBase": { "knowledgeBaseId": "<KB_ID>" } } }
    ],
    "agenticRetrieveConfiguration": {
      "maxAgentIteration": 5,
      "policyConfiguration": {
        "guardrailConfiguration": {
          "guardrailId": "<GUARDRAIL_ID>",
          "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.

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

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

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

Configure la herramienta de búsqueda web

ejemplo

Boto3

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

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

Interactive

En la interfaz de usuario del terminal interactivo AgentCore CLI, ejecute yagentcore 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

ejemplo

Boto3

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

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

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

Interactive

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

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:<region>: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:<REGION>:<ACCOUNT_ID>:gateway/*"
    },
    {
      "Sid": "InvokeWebSearch",
      "Effect": "Allow",
      "Action": "bedrock-agentcore:InvokeWebSearch",
      "Resource": "arn:aws:bedrock-agentcore:<REGION>:aws:tool/web-search.v1"
    }
  ]
}

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Especifique el tipo de autorización y las credenciales

Utilice una puerta de enlace