Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Defina la configuración del destino de la puerta de enlace
La configuración de destino depende del tipo de destino que añada a la puerta de enlace. Para obtener más información sobre los tipos de destino de puerta de enlace compatibles, consulte Objetivos 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:
Agregue un objetivo Lambda
Puede agregar un objetivo Lambda a su 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 de Lambda contiene los siguientes campos:
Para obtener más información sobre los objetivos de Lambda, consulte los objetivos de las funciones de AWS Lambda.
Seleccione uno de los siguientes métodos:
ejemplo
- AgentCore CLI
-
-
Para agregar una función Lambda como objetivo, ejecute agentcore add gateway-target la --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
En el lambda-function-arn caso de los objetivos, proporcione el esquema de la herramienta a la AgentCore CLI. --tool-schema-file Para el SDK de AgentCore Python y Boto3, proporcione el esquema de la herramienta con. inlinePayload
- AgentCore Python SDK
-
-
Con el SDK de AgentCore Python, puede crear un objetivo AWS 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 argumento de ejemplo que puede proporcionar para. target_payload Si omites el target_payload argumento, se usa 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 agregar un objetivo 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 de la AgentCore CLI, ejecute, seleccione Agregaragentcore, elija Gateway Target y, a continuación, seleccione la función Lambda:
A continuación, el asistente le solicita el nombre del objetivo, el ARN de la función de Lambda, el archivo de esquema de la herramienta y la configuración de la autorización de salida.
Agregue un objetivo de etapa de API Gateway
Para agregar una fase de una API REST de API Gateway como objetivo, especifique el ARN de la API y de la etapa y defina la configuración para filtrar las herramientas de la puerta de enlace de API o anular los nombres y las descripciones de las herramientas de la puerta de enlace:
Los siguientes ejemplos muestran cómo agregar un objetivo de API Gateway. También se aplican las siguientes configuraciones:
Seleccione uno de los métodos siguientes:
ejemplo
- AgentCore CLI
-
-
Para agregar una etapa de API REST de API Gateway como objetivo, ejecute agentcore add gateway-target 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
-
-
En el siguiente código se muestra el uso 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 de la AgentCore CLI, ejecuteagentcore, seleccione Agregar, elija Gateway Target y, a continuación, seleccione API Gateway REST API:
A continuación, el asistente le solicita el nombre del objetivo, el ID de la API de REST, la etapa y la configuración de autorización de salida.
Agregue un objetivo de OpenAPI
Seleccione uno de los métodos siguientes:
ejemplo
- AgentCore CLI
-
-
Para añadir un objetivo de esquema de OpenAPI, ejecute agentcore add gateway-target la --type open-api-schema opción y proporcione la ruta al 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 agregar un objetivo de OpenAPI mediante el SDK de AWS Python (Boto3). El esquema se ha subido a una ubicación de S3 a cuya URI se hace referencia 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 de la AgentCore CLI, ejecuteagentcore, seleccione Agregar, elija Gateway Target y, a continuación, seleccione OpenAPI Schema:
A continuación, el asistente le solicita el nombre del objetivo, la ruta al archivo de especificaciones de OpenAPI y la configuración de la autorización de salida.
Añada un objetivo de Smithy
Seleccione uno de los métodos siguientes:
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 agregar un objetivo de modelo de 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 de la AgentCore CLI, ejecute, seleccione Agregaragentcore, elija Gateway Target y, a continuación, seleccione Smithy Model:
A continuación, el asistente le solicita el nombre del objetivo, la ruta al archivo del modelo de Smithy y la configuración de la autorización de salida.
Agregue un objetivo 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 necesidad de agregación ni traducción de protocolos.
Para obtener más información sobre los objetivos HTTP, consulte los objetivos de Amazon Bedrock AgentCore Runtime.
Seleccione uno de los siguientes métodos:
ejemplo
- AWS CLI
-
-
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"
}]'
- Boto3
-
-
El siguiente código de Python muestra cómo agregar 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. regionEs opcional y el valor predeterminado es la región de la puerta de enlace.
El valor de service depende de dónde esté hospedado el servidor MCP. Los siguientes son valores comunes:
-
bedrock-agentcore— Para los servidores MCP alojados en Amazon Bedrock AgentCore, como los servidores MCP en tiempo de ejecución (consulte Implementación de servidores MCP en AgentCore tiempo de ejecución) u otra puerta de enlace.
-
execute-api— Para servidores MCP detrás de Amazon API Gateway.
-
lambda— Para servidores MCP con URL de funciones de 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 de la 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 solicita 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 destino de servidor MCP con autorización OAuth (credenciales de cliente).
Seleccione uno de los métodos siguientes:
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 agregar 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
En el siguiente ejemplo, se crea un destino de servidor MCP con una autorización de clave de API.
Seleccione uno de los métodos siguientes:
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": ""
}
}
}
]
)
Agregue un objetivo de conector con las bases de conocimiento administradas de Amazon Bedrock
Puede añadir el conector de Amazon Bedrock Managed Knowledge Bases como destino a su puerta de enlace.
Para obtener más información sobre el conector Amazon Bedrock Managed Knowledge Bases, consulte Amazon Bedrock Managed Knowledge Bases.
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 mediante agente de streaming en varios pasos) y Retrieve (una búsqueda híbrida única). Añades una entrada de configuración por herramienta.
ParaAgenticRetrieveStream, configure retrievers (las bases de conocimiento administradas que desea consultar) y agenticRetrieveConfiguration enparameterValues. 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 gestionados por el servicio, pero especificando foundationModelType y haciendo explícita la configuraciónrerankingModelType. El agente no proporciona los ID de la base de conocimientos en el momento de la llamada. ParaRetrieve, knowledgeBaseId configúreloparameterValues; es obligatorio.
El conector solo admite bases de conocimiento administradas. 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 destino de puerta de enlace con la configuración del conector de Amazon Bedrock Managed Knowledge Bases 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 destino de puerta de enlace con la configuración del conector de Amazon Bedrock Managed Knowledge Bases mediante la CLI: AWS
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 agregar un objetivo de conector de base de conocimientos gestionado, 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 de la AgentCore CLI, ejecute agentcore add gateway-target y, a continuación, seleccione Amazon Bedrock Knowledge Bases en el selector de tipos de destino:
El asistente le pedirá un nombre y una descripción y le permitirá seleccionar uno o más tipos de fuentes y tipos de fuentes.
Tras la llamadaCreateGatewayTarget, la puerta de enlace 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; el FAILED estado incluye un motivo que describe el problema.
Para personalizar la recuperación por parte de la agencia (por ejemplo, para limitar las iteraciones de planificación o adjuntar una barrera), 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. Referencia de la configuración
{
"name": "AgenticRetrieveStream",
"parameterValues": {
"retrievers": [
{ "configuration": { "knowledgeBase": { "knowledgeBaseId": "<KB_ID>" } } }
],
"agenticRetrieveConfiguration": {
"maxAgentIteration": 5,
"policyConfiguration": {
"guardrailConfiguration": {
"guardrailId": "<GUARDRAIL_ID>",
"guardrailVersion": "1"
}
}
}
}
}
Controle qué parámetros puede establecer el agente
Cada entrada de configuración de la herramienta acepta dos controles de parámetros que determinan lo que ve el agente que llama y lo que el Gateway envía a la base de conocimientos:
-
parameterValues— los 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 describiendo el campo.
-
visible— se configura true para mostrar el campo al agente o para false ocultarlo mientras se sigue enviando cualquier valor predeterminado configurado por el administrador.
Enlaza knowledgeBaseId parameterValues y no lo expongas.
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 la función de servicio de puerta de enlace
Este conector utiliza la función de ejecución de la puerta de enlace, es decir, el ARN del rol de IAM al que se CreateGateway transfiere, y el AgentCore servicio asume que llama al backend en su nombre. Se trata de un rol que usted crea, no un rol vinculado a un servicio. Para el conector de bases de conocimiento administradas de Amazon Bedrock, necesita los siguientes permisos:
-
bedrock:GetKnowledgeBase— para validar la base de conocimientos enlazada cuando se crea el objetivo. Abarcado al recurso de la base de conocimientos gestionado.
-
bedrock:Retrieve— para la Retrieve herramienta. Se refiere al recurso gestionado de la base de conocimientos.
-
bedrock:AgenticRetrieveStream— para la AgenticRetrieveStream herramienta. Esta acción no se refiere a un recurso de base de conocimientos gestionado, así que acéptela. *
El Gateway firma las llamadas al backend como el bedrock servicio. Incluya bedrock:GetKnowledgeBase independientemente de las herramientas que añada; si agrega solo una herramienta, incluya solo la acción de recuperación de esa herramienta.
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 a la puerta de enlace), no a la función que asume la puerta de enlace.
Agregue una política con el siguiente contenido al rol de ejecución adjunto al 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": "*"
}
]
}
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, exponiéndola a tu cuenta y a Gateway con las aws:SourceAccount siguientes aws:SourceArn condiciones:
{
"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/*"
}
}
}
]
}
Añade un objetivo de conector con la herramienta de búsqueda web
Puede agregar un conector integrado como destino a su puerta de enlace. El conector de la herramienta de búsqueda web proporciona capacidades de búsqueda web administradas sin necesidad de claves de API o infraestructura personalizadas.
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 en la web
Si lo desea, puede anclar el objetivo a una versión específica del conector incluyéndolo version en el source campo. Si lo omiteversion, el destino utilizará la versión predeterminada actual del conector. Para obtener más información sobre las versiones de los conectores, consulte Versiones de conectores.
ejemplo
- Boto3
-
-
El siguiente código de Python muestra cómo crear un destino de puerta de enlace con la configuración de conectores 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", "version": "1.1.0"},
"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 CLI: AWS
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "<GATEWAY_ID>" \
--name "web-search-tool" \
--target-configuration '{
"mcp": {
"connector": {
"source": {
"connectorId": "web-search",
"version": "1.1.0"
},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {}
}
]
}
}
}' \
--credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
--region "<REGION>"
- AgentCore CLI
-
-
Para agregar un objetivo a la herramienta de búsqueda web, ejecute agentcore add gateway-target lo --type connector --connector web-search siguiente:
agentcore add gateway-target \
--name MyWebSearchTarget \
--type connector \
--connector web-search \
--gateway MyGateway
agentcore deploy
- Interactive
-
-
En la interfaz de usuario del terminal interactivo de la AgentCore CLIagentcore add gateway-target, ejecute y, a continuación, seleccione Amazon Web Search en el selector de tipos de destino:
El asistente le pedirá que introduzca el nombre del destino, la puerta de enlace a la que desea adjuntarlo y una lista opcional de los dominios que desea excluir de los resultados de la 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 de inclusión o exclusión. Esto resulta útil para los administradores que desean evitar que los agentes devuelvan resultados de sitios web específicos.
-
Target-level lista de dominios excluidos: lista de dominios excluidos de todas las búsquedas en un destino, establecida en el momento de la creación del destino medianteparameterValues.domainFilter.exclude. La lista de exclusiones se aplica en el servidor y está oculta para el agente que realiza la llamada.
-
Target-level Lista de inclusión de dominios (versión del conector 1.2.0 y posteriores): además de la lista de exclusiones, puede configurarla parameterValues.domainFilter.include para restringir las búsquedas a un conjunto específico de dominios.
Request-level los filtros (dominio include/exclude e intervalo de fechas de publicación) están disponibles para el agente que realiza la llamada en la versión del conector 1.2.0 y posteriores. Request-level los filtros se crean con las listas de exclusiones e inclusiones del nivel de destino: las exclusiones e inclusiones del nivel de destino siempre se aplican y el agente no puede relajarlas.
Los siguientes ejemplos crean un objetivo de la herramienta de búsqueda web anclado a la versión 1.2.0 con listas de inclusión y exclusión de dominios:
ejemplo
- Boto3
-
-
El siguiente código de Python muestra cómo crear un objetivo para una 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", "version": "1.2.0"},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {
"domainFilter": {
"include": ["allowed-website-1.com", "allowed-website-2.com"],
"exclude": ["blocked-website-1.com", "blocked-website-2.com"]
}
},
}
],
}
}
},
credentialProviderConfigurations=[
{"credentialProviderType": "GATEWAY_IAM_ROLE"}
],
)
- AWS CLI
-
-
El siguiente comando crea un objetivo de la herramienta de búsqueda web con filtrado de dominios mediante la CLI: AWS
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "<GATEWAY_ID>" \
--name "web-search-tool" \
--target-configuration '{
"mcp": {
"connector": {
"source": {
"connectorId": "web-search",
"version": "1.2.0"
},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {
"domainFilter": {
"include": ["allowed-website-1.com", "allowed-website-2.com"],
"exclude": ["blocked-website-1.com", "blocked-website-2.com"]
}
}
}
]
}
}
}' \
--credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
--region "<REGION>"
- AgentCore CLI
-
-
Pase 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 de la 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 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 la función de 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 el Gateway
-
bedrock-agentcore:InvokeWebSearch— para autorizar las invocaciones de búsquedas en la web, cotejándolas 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 al rol de servicio adjunto al 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"
}
]
}
