Ajouter une cible Lambda Ajouter une cible de stage API Gateway Ajouter une cible OpenAPI Ajouter une cible Smithy Ajouter une cible d'exécution HTTP Ajouter une cible de serveur MCP Ajouter une cible Connector avec les bases de connaissances gérées par Amazon Bedrock Ajouter une cible Connector avec l'outil de recherche Web

Définition de 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 la section 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 :

Rubriques

Ajouter une cible Lambda
Ajouter une cible de stage API Gateway
Ajouter une cible OpenAPI
Ajouter une cible Smithy
Ajouter une cible d'exécution HTTP
Ajouter une cible de serveur MCP
Ajouter une cible Connector avec les bases de connaissances gérées par Amazon Bedrock
Ajouter une cible Connector avec l'outil de recherche Web

Ajouter une cible Lambda

Vous pouvez ajouter une cible Lambda à votre passerelle à l'aide de la AgentCore CLI 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 :

LambdArn — L'ARN de la fonction Lambda à utiliser comme cible.
ToolSchema — Schéma d'outil pour la cible de la passerelle.

Pour plus d'informations sur les cibles Lambda, consultez la section Cibles des fonctions 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 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

AgentCore Python SDK

Avec la AgentCore CLI, vous pouvez facilement créer une cible Lambda avec des 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 l'target_payloadargument, 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 de stage API Gateway

Pour ajouter une étape d'une API REST API Gateway en tant que cible, spécifiez l'ARN de l'API et du stage et définissez les paramètres pour filtrer les outils dans la passerelle API ou pour remplacer les noms et descriptions des outils de la passerelle :

Les exemples suivants montrent comment ajouter une cible API Gateway. Les configurations suivantes sont également appliquées :

Les outils filtrés sont les méthodes GET et POST pour le /products chemin.
GET /products est renommé enget_items.

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

Le code suivant montre l'utilisation du 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 CLIagentcore, exécutez, sélectionnez Ajouter, choisissez Gateway Target, puis sélectionnez API Gateway REST API :

L'assistant vous invite ensuite à saisir 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 l'--type open-api-schemaoption et agentcore add gateway-target 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é chargé vers un emplacement S3 dont l'URI est référencé dans letarget_payload. L'autorisation sortante pour la cible se fait par le biais d'une clé d'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écification 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 CLIagentcore, exécutez, 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 Amazon Bedrock AgentCore Runtime targets.

Sélectionnez l'une des méthodes suivantes :

Exemple

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'autorisation sortante.

Serveur MCP avec autorisation IAM (SigV4)

L'exemple suivant crée une cible de serveur MCP avec autorisation IAM. La passerelle signe les demandes 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. Le region est facultatif et la valeur par défaut est la région de la passerelle.

La valeur de service dépend de l'endroit où votre serveur MCP est hébergé. Les valeurs les plus 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 dotés d'URL de fonctions 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 l'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 l'--type mcp-serveroption et spécifiez agentcore add gateway-target 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é d'API

L'exemple suivant crée une cible de serveur MCP avec une autorisation par clé d'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 Connector avec les bases de connaissances gérées par Amazon Bedrock

Vous pouvez ajouter le connecteur Amazon Bedrock Managed Knowledge Bases comme cible à 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 expose deux outils, chacun nommé d'après son fonctionnement principal : AgenticRetrieveStream (récupération agentique en plusieurs étapes) et Retrieve (une recherche hybride unique). Vous ajoutez une entrée de configuration par outil.

PourAgenticRetrieveStream, définir retrievers (les bases de connaissances gérées à interroger) et agenticRetrieveConfiguration entrerparameterValues. Les deux sont obligatoires : l'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 le service, 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 l'entrée parameterValues ; c'est obligatoire.

Le connecteur prend uniquement en charge les bases de connaissances gérées. Les cibles du 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 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

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 du terminal interactif CLI, exécutezagentcore add gateway-target, puis sélectionnez Amazon Bedrock Knowledge Bases dans le sélecteur de type de cible :

L'assistant vous invite à saisir un nom, une description et vous permet de sélectionner un ou plusieurs types de sources et sources.

Après l'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 qu'statusil soit READY ; un FAILED statut inclut une raison décrivant le problème.

Pour personnaliser la récupération agentique, par exemple, pour plafonner les itérations de planification ou fixer un garde-corps, ajoutez les champs facultatifs à. agenticRetrieveConfiguration Si vous les omettez, les valeurs par défaut gérées par le service s'appliquent. Pour toutes les valeurs acceptées, consultez la section 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, telles que la borne knowledgeBaseId ou une valeur par défaut. numberOfResults Ils sont utilisés sauf si l'agent 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 contient :
- 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— défini sur true pour exposer le champ à l'agent ou pour le masquer tout en false continuant à envoyer une valeur par défaut configurée par l'administrateur.

knowledgeBaseIdAttachez-le 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
    }
  ]
}

Configuration du rôle de service de passerelle

Ce connecteur utilise le rôle d'exécution de passerelle, c'est-à-dire l'ARN du rôle IAM auquel vous passezCreateGateway, 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 nécessite les autorisations suivantes :

bedrock:GetKnowledgeBase— pour valider la base de connaissances associé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. Incluez bedrock:GetKnowledgeBase quels que soient les outils que vous ajoutez ; si vous n'ajoutez qu'un seul outil, incluez uniquement l'action de récupération de cet outil.

Note

bedrock-agentcore:InvokeGatewayne fait pas partie du rôle d'exécution. Cette autorisation appartient à l'appelant (l'agent ou l'application invoquant la passerelle) et non au rôle assumé par la passerelle.

Ajoutez une politique avec le contenu suivant au rôle d'exécution attaché à 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 la délimitant à 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 Connector avec l'outil de recherche Web

Vous pouvez ajouter un connecteur intégré comme 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 ou 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 Web

Exemple

Boto3

Le code Python suivant montre comment créer une cible de passerelle avec la configuration du connecteur Web Search Tool à 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"},
                "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 Web Search Tool à l'aide de 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

Pour ajouter une cible dans 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 du terminal interactif 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 rattacher et une liste facultative de domaines à exclure des résultats de recherche.

Configurer le filtrage des domaines

Vous pouvez restreindre les domaines que l'outil de recherche Web est autorisé à interroger en configurant une liste de domaines refusés. Cela est utile pour les administrateurs qui souhaitent empêcher les agents de renvoyer des résultats provenant de sites Web spécifiques.

Le filtrage de domaine est configuré au niveau de l'outil à l'aide du parameterValues.domainFilter.exclude champ lors de la création ou de la mise à jour d'une cible de passerelle. La liste de refus est appliquée côté serveur et est masquée au LLM. L'agent n'est pas au courant de la restriction et ne reçoit tout simplement aucun résultat des domaines exclus.

Les exemples suivants créent une cible d'outil de recherche Web avec un filtrage de domaine qui exclut les résultats de blocked-website-1.com et blocked-website-2.com :

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"},
                "configurations": [
                    {
                        "name": "WebSearch",
                        "parameterValues": {
                            "domainFilter": {
                                "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 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

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 du terminal interactif CLI, l'assistant Add Gateway Target vous invite à saisir 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. Le fait de laisser l'invite vide crée la cible sans filtrage de domaine.

Vous pouvez également mettre à jour une cible existante pour ajouter ou modifier un filtrage de domaine à l'aide deUpdateGatewayTarget.

Configuration du 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 Web, le rôle nécessite les autorisations suivantes :

bedrock-agentcore:InvokeGateway— pour invoquer le Gateway
bedrock-agentcore:InvokeWebSearch— pour autoriser les invocations de recherche sur le Web, vérifiées 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 attaché à 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"
    }
  ]
}

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Spécifiez le type d'autorisation et les informations d'identification

Utiliser une passerelle