Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
Définir la configuration cible de la passerelle
La configuration de la cible dépend du type de cible que vous ajoutez à la passerelle. Pour plus d'informations sur les types de cibles de passerelle pris en charge, consultez Cibles prises en charge pour les AgentCore passerelles Amazon Bedrock.
Sélectionnez une rubrique pour voir des exemples d'ajout d'un type de cible :
Ajouter une cible Lambda
Vous pouvez ajouter une cible Lambda à votre passerelle à l'aide de l' AgentCore interface de ligne de commande en spécifiant le --type as lambda-function-arn et en fournissant l'ARN Lambda et un fichier de schéma d'outil.
Configuration de la cible
La configuration cible (ou charge utile) d'une fonction Lambda contient les champs suivants :
Pour plus d'informations sur les cibles Lambda, consultez la section Cibles de fonction AWS Lambda.
Sélectionnez l'une des méthodes suivantes :
Exemple
- AgentCore CLI
-
-
Pour ajouter une fonction Lambda en tant que cible, exécutez agentcore add gateway-target avec l'--type lambda-function-arnoption. Fournissez l'ARN Lambda et un fichier JSON contenant le schéma de l'outil :
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
Pour les lambda-function-arn cibles, fournissez le schéma de l'outil à la AgentCore CLI avec--tool-schema-file. Pour le SDK AgentCore Python et Boto3, fournissez le schéma de l'outil avec. inlinePayload
- AgentCore Python SDK
-
-
Le SDK AgentCore Python vous permet de créer une cible AWS Lambda avec les configurations par défaut.
# 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
)
Voici un exemple d'argument que vous pouvez fournir pourtarget_payload. Si vous omettez target_payload cet argument, cette charge utile est utilisée :
{
"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
-
-
Le code Python suivant montre comment ajouter une cible Lambda à l'aide du SDK 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
-
-
Dans l' AgentCore interface utilisateur du terminal interactif CLI, exécutezagentcore, sélectionnez Ajouter, choisissez Gateway Target, puis sélectionnez la fonction Lambda :
L'assistant vous demande ensuite le nom de la cible, l'ARN de la fonction Lambda, le fichier de schéma de l'outil et la configuration des autorisations sortantes.
Ajouter une cible d'étape API Gateway
Pour ajouter une étape d'une API REST API Gateway en tant que cible, spécifiez l'ARN de l'API et de la phase et définissez les paramètres pour filtrer les outils de la passerelle API ou pour remplacer les noms et les descriptions des outils de la passerelle :
Les exemples suivants montrent comment ajouter une cible API Gateway. Les configurations suivantes sont également appliquées :
Sélectionnez l'une des méthodes suivantes :
Exemple
- AgentCore CLI
-
-
Pour ajouter un stage d'API REST API Gateway en tant que cible, exécutez agentcore add gateway-target avec l'--type api-gatewayoption suivante :
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
-
-
La commande suivante utilise l' AWS interface de ligne de commande :
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
-
-
Le code suivant utilise le SDK 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
-
-
Dans l' AgentCore interface utilisateur du terminal interactif CLI, exécutezagentcore, sélectionnez Ajouter, choisissez Gateway Target, puis sélectionnez API Gateway REST API :
L'assistant vous demande ensuite le nom de la cible, l'ID de l'API REST, l'étape et la configuration des autorisations sortantes.
Ajouter une cible OpenAPI
Sélectionnez l'une des méthodes suivantes :
Exemple
- AgentCore CLI
-
-
Pour ajouter une cible de schéma OpenAPI, exécutez agentcore add gateway-target l'--type open-api-schemaoption et indiquez le chemin d'accès à votre fichier de spécification 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
-
-
Le code Python suivant montre comment ajouter une cible OpenAPI à l'aide du SDK AWS Python (Boto3). Le schéma a été téléchargé vers un emplacement S3 dont l'URI est référencé dans letarget_payload. L'autorisation sortante pour la cible s'effectue via une clé 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
-
-
Dans l' AgentCore interface utilisateur du terminal interactif CLI, exécutezagentcore, sélectionnez Ajouter, choisissez Gateway Target, puis sélectionnez OpenAPI Schema :
L'assistant vous demande ensuite le nom de la cible, le chemin d'accès au fichier de spécifications OpenAPI et la configuration des autorisations sortantes.
Ajouter une cible Smithy
Sélectionnez l'une des méthodes suivantes :
Exemple
- AgentCore CLI
-
-
Pour ajouter une cible de modèle Smithy, exécutez agentcore add gateway-target l'--type smithy-modeloption et indiquez le chemin d'accès à votre fichier de modèle Smithy :
agentcore add gateway-target \
--name MySmithyTarget \
--type smithy-model \
--schema path/to/smithy-model.json \
--gateway MyGateway
agentcore deploy
- Boto3
-
-
Le code Python suivant montre comment ajouter une cible de modèle Smithy à l'aide du SDK 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
-
-
Dans l' AgentCore interface utilisateur du terminal interactif CLI, exécutezagentcore, sélectionnez Ajouter, choisissez Gateway Target, puis sélectionnez Smithy Model :
L'assistant vous demande ensuite le nom de la cible, le chemin d'accès au fichier modèle Smithy et la configuration des autorisations sortantes.
Ajouter une cible d'exécution HTTP
Vous pouvez ajouter un agent Amazon Bedrock AgentCore Runtime en tant que cible HTTP à votre passerelle. La passerelle envoie le trafic directement à l'agent d'exécution sans agrégation ni traduction de protocole.
Pour plus d'informations sur les cibles HTTP, consultez la section Cibles Objectifs Amazon Bedrock AgentCore Runtime Amazon Bedrock AgentCore Runtime.
Sélectionnez l'une des méthodes suivantes :
Exemple
- AWS CLI
-
-
La commande suivante crée une cible d'exécution HTTP avec l'autorisation 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
-
-
Le code Python suivant montre comment ajouter une cible d'exécution HTTP à l'aide du SDK 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"
}
]
)
Ajouter une cible de serveur MCP
Vous pouvez ajouter une cible de serveur MCP à l'aide de la AgentCore CLI ou du SDK AWS Python (Boto3). Les exemples suivants montrent comment créer une cible de serveur MCP avec différents types d'autorisations sortantes.
Serveur MCP avec autorisation IAM (Sigv4)
L'exemple suivant crée une cible de serveur MCP avec une autorisation IAM. La passerelle signe les demandes adressées au serveur MCP à l'aide de SIGv4 avec les informations d'identification du rôle de service de passerelle. Vous devez spécifier le service nom pour la signature. La valeur region est facultative et correspond par défaut à la région de la passerelle.
La valeur de service dépend de l'endroit où votre serveur MCP est hébergé. Les valeurs courantes sont les suivantes :
-
bedrock-agentcore— Pour les serveurs MCP hébergés sur Amazon Bedrock AgentCore, tels que le runtime (voir Déployer des serveurs MCP dans AgentCore Runtime) ou une autre passerelle.
-
execute-api— Pour les serveurs MCP situés derrière Amazon API Gateway.
-
lambda— Pour les serveurs MCP situés derrière des URL de fonction Lambda.
Sélectionnez l'une des méthodes suivantes :
Exemple
- 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
-
-
Dans l' AgentCore interface utilisateur du terminal interactif CLI, exécutezagentcore, sélectionnez Ajouter, choisissez Gateway Target, puis sélectionnez le point de terminaison du serveur MCP :
L'assistant vous demande ensuite le nom de la cible, l'URL du point de terminaison du serveur MCP et la configuration des autorisations sortantes.
- 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"
}
}
}
]
)
Serveur MCP avec autorisation OAuth
L'exemple suivant crée une cible de serveur MCP avec une autorisation OAuth (informations d'identification du client).
Sélectionnez l'une des méthodes suivantes :
Exemple
- 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
-
-
Pour ajouter une cible de serveur MCP avec autorisation OAuth, exécutez agentcore add gateway-target avec l'--type mcp-serveroption et spécifiez les informations d'identification 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": []
}
}
}
]
)
Serveur MCP avec autorisation par clé API
L'exemple suivant crée une cible de serveur MCP avec une autorisation par clé API.
Sélectionnez l'une des méthodes suivantes :
Exemple
- 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": ""
}
}
}
]
)
Ajouter une cible de connecteur avec les bases de connaissances gérées par Amazon Bedrock
Vous pouvez ajouter le connecteur Amazon Bedrock Managed Knowledge Bases en tant que cible de votre passerelle.
Pour plus d'informations sur le connecteur Amazon Bedrock Managed Knowledge Bases, consultez Amazon Bedrock Managed Knowledge Bases.
Mettre en place une base de connaissances gérée
Le connecteur propose deux outils, chacun nommé d'après son opération principale : AgenticRetrieveStream (extraction agentique en plusieurs étapes, en streaming) et Retrieve (une seule recherche hybride). Vous ajoutez une entrée de configuration par outil.
PourAgenticRetrieveStream, définissez retrievers (les bases de connaissances gérées à interroger) et agenticRetrieveConfiguration dansparameterValues. Les deux sont obligatoires, car leur omission agenticRetrieveConfiguration entraîne une erreur d'exécution. Il peut s'agir d'un objet vide ({}) pour accepter les valeurs par défaut gérées par les services, mais en spécifiant foundationModelType et en rerankingModelType rendant la configuration explicite. L'agent ne fournit pas d'ID de base de connaissances au moment de l'appel. PourRetrieve, réglez knowledgeBaseId le champ parameterValues ; c'est obligatoire.
Le connecteur prend uniquement en charge les bases de connaissances gérées. Les cibles de connecteur ne prennent en charge que le type de fournisseur GATEWAY_IAM_ROLE d'informations d'identification.
Exemple
- Boto3
-
-
Le code Python suivant montre comment créer une cible de passerelle avec la configuration du connecteur Amazon Bedrock Managed Knowledge Bases à l'aide du SDK 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
-
-
La commande suivante crée une cible de passerelle avec la configuration du connecteur Amazon Bedrock Managed Knowledge Bases à l'aide de l' AWS interface de ligne de commande :
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
-
-
Pour ajouter une cible de connecteur de base de connaissances gérée, exécutez agentcore add gateway-target avec --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
-
-
Dans l' AgentCore interface utilisateur interactive du terminal CLI, exécutezagentcore add gateway-target, puis sélectionnez Amazon Bedrock Knowledge Bases dans le sélecteur de type de cible :
L'assistant vous demande un nom, une description et vous permet de sélectionner un ou plusieurs types de sources et sources.
Après votre appelCreateGatewayTarget, la passerelle valide la configuration de manière asynchrone (généralement dans un délai d'environ 30 secondes), ce qui inclut une GetKnowledgeBase vérification de chaque base de connaissances liée. GetGatewayTargetInterrogez jusqu'à ce que cela status soit READY ; un FAILED statut inclut une raison décrivant le problème.
Pour personnaliser la récupération des agents, par exemple, pour limiter les itérations de planification ou ajouter un garde-fou, ajoutez les champs facultatifs à. agenticRetrieveConfiguration Si vous les omettez, les paramètres par défaut gérés par les services s'appliquent. Pour toutes les valeurs acceptées, voir Référence de configuration.
{
"name": "AgenticRetrieveStream",
"parameterValues": {
"retrievers": [
{ "configuration": { "knowledgeBase": { "knowledgeBaseId": "<KB_ID>" } } }
],
"agenticRetrieveConfiguration": {
"maxAgentIteration": 5,
"policyConfiguration": {
"guardrailConfiguration": {
"guardrailId": "<GUARDRAIL_ID>",
"guardrailVersion": "1"
}
}
}
}
}
Contrôlez les paramètres que l'agent peut définir
Chaque entrée de configuration d'outil accepte deux contrôles de paramètres qui déterminent ce que voit l'agent appelant et ce que la passerelle envoie à la base de connaissances :
-
parameterValues— valeurs définies par l'administrateur envoyées à la base de connaissances à chaque appel, comme une limite knowledgeBaseId ou un appel par défaut. numberOfResults Ils sont utilisés à moins que l'agent ne remplace un champ que vous avez exposé.
-
parameterOverrides— une liste qui contrôle les champs de demande que l'agent peut voir et définir au moment de l'appel. Chaque entrée comporte :
-
path— le champ de la Retrieve demande, par exemple $.retrievalQuery.text ou$.retrievalConfiguration.managedSearchConfiguration.numberOfResults.
-
description— texte facultatif présenté à l'agent décrivant le champ.
-
visible— paramétré true pour exposer le champ à l'agent, ou pour le masquer tout en continuant false à envoyer une valeur par défaut configurée par l'administrateur.
knowledgeBaseIdAttachez-vous parameterValues et ne l'exposez pas.
L'entrée de configuration suivante lie la base de connaissances, définit une valeur par défaut de 10 résultats et expose le texte de la requête et le nombre de résultats à l'agent :
{
"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
}
]
}
Configurer le rôle de service de passerelle
Ce connecteur utilise le rôle d'exécution de la passerelle, c'est-à-dire l'ARN du rôle IAM que vous transmettezCreateGateway, que le AgentCore service suppose d'appeler le backend en votre nom. Il s'agit d'un rôle que vous créez, et non d'un rôle lié à un service. Le connecteur Amazon Bedrock Managed Knowledge Bases a besoin des autorisations suivantes :
-
bedrock:GetKnowledgeBase— pour valider la base de connaissances limitée lors de la création de la cible. Limité à la ressource de base de connaissances gérée.
-
bedrock:Retrieve— pour l'Retrieveoutil. Limité à la ressource de base de connaissances gérée.
-
bedrock:AgenticRetrieveStream— pour l'AgenticRetrieveStreamoutil. Cette action n'est pas limitée à une ressource de base de connaissances gérée, alors accordez-la. *
La passerelle signe les appels du backend en tant que bedrock service. bedrock:GetKnowledgeBaseIncluez quels que soient les outils que vous ajoutez ; si vous n'ajoutez qu'un seul outil, n'incluez que l'action de récupération de cet outil.
bedrock-agentcore:InvokeGatewayne fait pas partie du rôle d'exécution. Cette autorisation appartient à l'appelant, c'est-à-dire à l'agent ou à l'application qui invoque la passerelle, et non au rôle assumé par la passerelle.
Ajoutez une politique avec le contenu suivant au rôle d'exécution associé à la passerelle :
{
"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": "*"
}
]
}
Le rôle de service doit également faire confiance au AgentCore service afin qu'il puisse assumer le rôle. Joignez la politique de confiance suivante, en l'étendant à votre compte et à Gateway avec les aws:SourceArn conditions aws:SourceAccount et :
{
"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/*"
}
}
}
]
}
Ajouter une cible de connecteur à l'aide de l'outil de recherche Web
Vous pouvez ajouter un connecteur intégré en tant que cible à votre passerelle. Le connecteur Web Search Tool fournit des fonctionnalités de recherche Web gérées sans nécessiter d'infrastructure personnalisée ni de clés d'API.
Pour plus d'informations sur le connecteur de l'outil de recherche Web, consultez la section Outil de recherche Web.
Configurer l'outil de recherche sur le Web
Vous pouvez éventuellement épingler la cible à une version de connecteur spécifique en l'incluant version dans le source champ. Si vous omettezversion, la cible utilise la version par défaut actuelle du connecteur. Pour plus d'informations sur les versions des connecteurs, consultez la section Versions des connecteurs.
Exemple
- Boto3
-
-
Le code Python suivant montre comment créer une cible de passerelle avec la configuration du connecteur de l'outil de recherche Web à l'aide du SDK 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
-
-
La commande suivante crée une cible de passerelle avec la configuration du connecteur de l'outil de recherche Web à l'aide de l' AWS interface de ligne de commande :
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
-
-
Pour ajouter une cible à l'outil de recherche Web, exécutez agentcore add gateway-target avec --type connector --connector web-search :
agentcore add gateway-target \
--name MyWebSearchTarget \
--type connector \
--connector web-search \
--gateway MyGateway
agentcore deploy
- Interactive
-
-
Dans l' AgentCore interface utilisateur interactive du terminal CLI, exécutezagentcore add gateway-target, puis sélectionnez Amazon Web Search dans le sélecteur de type de cible :
L'assistant vous invite à saisir le nom de la cible, la passerelle à laquelle vous souhaitez vous connecter et une liste facultative de domaines à exclure des résultats de recherche.
Configurer le filtrage des domaines
Vous pouvez limiter les domaines que l'outil de recherche Web est autorisé à interroger en configurant une liste d'inclusion ou d'exclusion de domaines. Cela est utile pour les administrateurs qui souhaitent empêcher les agents de renvoyer des résultats provenant de sites Web spécifiques.
-
Target-level liste d'exclusion de domaines : liste des domaines exclus de toutes les recherches sur une cible, définie lors de la création de la cible à l'aide deparameterValues.domainFilter.exclude. La liste d'exclusion est appliquée côté serveur et masquée à l'agent appelant.
-
Target-level liste d'inclusion de domaines (version du connecteur 1.2.0 et versions ultérieures) : outre la liste d'exclusion, vous pouvez configurer parameterValues.domainFilter.include pour limiter les recherches à un ensemble spécifique de domaines.
Request-level les filtres (domaine include/exclude et plage de dates de publication) sont disponibles pour l'agent appelant dans la version 1.2.0 Connector et les versions ultérieures. Request-level les filtres sont composés à partir des listes d'exclusions et d'inclusions au niveau cible : les exclusions et inclusions au niveau cible s'appliquent toujours et l'agent ne peut pas les assouplir.
Les exemples suivants créent une cible d'outil de recherche Web épinglée à la version 1.2.0 avec à la fois des listes d'inclusion et d'exclusion de domaines :
Exemple
- Boto3
-
-
Le code Python suivant montre comment créer une cible d'outil de recherche Web avec filtrage de domaine à l'aide du SDK 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
-
-
La commande suivante crée une cible de l'outil de recherche Web avec filtrage de domaine à l'aide de l' AWS interface de ligne de commande :
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
-
-
Transmettez une liste de domaines séparés par des virgules via : --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
-
-
Dans l' AgentCore interface utilisateur interactive du terminal CLI, l'assistant Ajouter une cible de passerelle vous invite à fournir une liste facultative de domaines séparés par des virgules à exclure des résultats de recherche une fois que vous avez sélectionné Amazon Web Search et choisi une passerelle. Si l'invite est vide, la cible ne sera pas filtrée par domaine.
Vous pouvez également mettre à jour une cible existante pour ajouter ou modifier le filtrage de domaine à l'aide deUpdateGatewayTarget.
Configurer le rôle de service de passerelle
La passerelle a besoin d'un rôle de service qui permet au AgentCore service d'effectuer des actions en votre nom. Pour l'outil de recherche sur le Web, le rôle nécessite les autorisations suivantes :
-
bedrock-agentcore:InvokeGateway— pour invoquer la passerelle
-
bedrock-agentcore:InvokeWebSearch— pour autoriser les appels de recherche sur le Web, vérifiés par demande par rapport à l'ARN appartenant au service arn:aws:bedrock-agentcore:<region>:aws:tool/web-search.v1
Ajoutez une politique avec le contenu suivant au rôle de service associé à la passerelle :
{
"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"
}
]
}
