# 定义网关目标配置
目标配置取决于您要添加到网关的目标类型。有关支持的网关目标类型的更多信息，请参阅 [Amazon Bedrock AgentCore 网关支持的目标](gateway-supported-targets.md)。
选择一个主题以查看添加目标类型的示例：
**Topics**
+ [添加 Lambda 目标](#gateway-add-target-api-lambda)
+ [添加 API Gateway 阶段目标](#gateway-add-target-api-gateway)
+ [添加 OpenAPI 目标](#gateway-add-target-api-openapi)
+ [添加一个 Smithy 目标](#gateway-add-target-api-smithy)
+ [添加 HTTP 运行时目标](#gateway-add-target-api-http-runtime)
+ [添加 MCP 服务器目标](#gateway-add-target-api-MCPserver)
+ [使用 Amazon Bedrock 托管知识库添加连接器目标](#gateway-add-target-api-connector-managed-kb)
+ [使用 Web 搜索工具添加连接器目标](#gateway-add-target-api-connector-web-search)
## 添加 Lambda 目标
您可以使用 CL AgentCore I 向网关添加 Lambda 目标，方法是指定`--type`为`lambda-function-arn`并提供 Lambda ARN 和工具架构文件。
**目标配置**
Lambda 函数的目标配置（或有效负载）包含以下字段：
+ **Lambdaarn** — 用作目标的 Lambda 函数的 ARN。
+ **工具架构**-网关目标的工具架构。
[有关 Lambda 目标的更多信息，请参阅 Lambda 函数AWS 目标。](gateway-add-target-lambda.md)
选择以下方法之一：
**Example**
1. 要将 Lambda 函数添加为目标，请`agentcore add gateway-target`使用选项运行。`--type lambda-function-arn`提供 Lambda ARN 和一个包含工具架构的 JSON 文件：
```
agentcore add gateway-target \
--name MyLambdaTarget \
--type lambda-function-arn \
--lambda-arn arn:aws:lambda:us-east-1:123456789012:function:MyFunction \
--tool-schema-file tools.json \
--gateway MyGateway
agentcore deploy
```
1. AgentCore 使用 CLI，您可以轻松创建具有默认配置的 Lambda 目标。
```
# 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
)
```
以下是您可以为提供的示例参数`target_payload`。如果省略`target_payload`参数，则使用以下有效负载：
```
{
"lambdaArn": "",
"toolSchema": {
"inlinePayload": [
{
"name": "get_weather",
"description": "Get weather for a location",
"inputSchema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "the location e.g. seattle, wa"
}
},
"required": [
"location"
]
}
},
{
"name": "get_time",
"description": "Get time for a timezone",
"inputSchema": {
"type": "object",
"properties": {
"timezone": {
"type": "string"
}
},
"required": [
"timezone"
]
}
}
]
}
}
```
1. 以下 Python 代码演示了如何使用 Pyth AWS on 软件开发工具包 (Boto3) 添加 Lambda 目标：
```
import boto3
# Create the agentcore client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create a Lambda target
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="LambdaTarget",
targetConfiguration={
"mcp": {
"lambda": {
"lambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:YourLambdaFunction",
"toolSchema": {
"inlinePayload": [
{
"name": "get_weather",
"description": "Get weather for a location",
"inputSchema": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
},
{
"name": "get_time",
"description": "Get time for a timezone",
"inputSchema": {
"type": "object",
"properties": {"timezone": {"type": "string"}},
"required": ["timezone"],
},
},
]
}
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]
)
```
1. 在 AgentCore CLI 交互式终端用户界面中`agentcore`，运行，选择**添加**，选择**网关目标**，然后选择 **Lambda 函数**：
然后，向导会提示您输入目标名称、Lambda 函数 ARN、工具架构文件和出站授权配置。
## 添加 API Gateway 阶段目标
要将 API Gateway REST API 的某个阶段添加为目标，请指定 API 和阶段的 ARN 并定义设置以筛选 API 网关中的工具或覆盖网关中工具的名称和描述：
以下示例说明如何添加 API Gateway 目标。还应用了以下配置：
+ 筛选的工具是`/products`路径的 GET 和 POST 方法。
+ GET /products 更名为。`get_items`
选择以下方法之一：
**Example**
1. 要将 API Gateway REST API 阶段添加为目标，请`agentcore add gateway-target`使用以下`--type api-gateway`选项运行：
```
agentcore add gateway-target \
--name MyAPIGatewayTarget \
--type api-gateway \
--rest-api-id your-rest-api-id \
--stage your-stage \
--gateway MyGateway
agentcore deploy
```
1. 以下命令使用 AWS CLI：
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "SearchAPITarget" \
--target-configuration '{
"mcp": {
"apiGateway": {
"restApiId": "your-rest-api-id",
"stage": "your-stage",
"apiGatewayToolConfiguration": {
"toolFilters": [
{
"filterPath": "/products",
"methods": [
"GET",
"POST"
]
}
],
"toolOverrides": [
{
"path": "/products",
"method": "GET",
"name": "get_items",
"description": "Gets information for items in the list of products."
}
]
}
}
}
}'
--credential-provider-configurations '[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]'
```
1. 以下代码显示了使用 AWS Python 软件开发工具包 (Boto3)：
```
import boto3
# Create the client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create an API gateway REST API target with gateway service role authentication
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="SearchAPITarget",
targetConfiguration={
"mcp": {
"apiGateway": {
"restApiId": "your-rest-api-id",
"stage": "your-stage",
"apiGatewayToolConfiguration": {
"toolFilters": [
{
"filterPath": "/products",
"methods": [
"GET",
"POST"
]
}
],
"toolOverrides": [
{
"path": "/products",
"method": "GET",
"name": "get_item",
"description": "Gets information for a specific item in the product list."
}
]
}
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]
)
```
1. 在 AgentCore CLI 交互式终端用户界面中，运行`agentcore`，选择**添加**，选择**网关目标**，然后选择 **API Gateway REST API**：
然后，向导会提示您输入目标名称、REST API ID、阶段和出站授权配置。
## 添加 OpenAPI 目标
选择以下方法之一：
**Example**
1. 要添加 OpenAPI 架构目标，请`agentcore add gateway-target`使用`--type open-api-schema`选项运行并提供 OpenAPI 规范文件的路径：
```
agentcore add gateway-target \
--name MyOpenAPITarget \
--type open-api-schema \
--schema path/to/openapi-spec.json \
--outbound-auth none|api-key|oauth \
--gateway MyGateway
agentcore deploy
```
1. 以下 Python 代码展示了如何使用 Pyth AWS on SDK (Boto3) 添加 OpenAPI 目标。架构已上传到一个 S3 位置，其中引用了其 URI `target_payload`。目标的出站授权是通过 API 密钥进行的。
```
import boto3
# Create the client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create an OpenAPI target with API Key authentication
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="SearchAPITarget",
targetConfiguration={
"mcp": {
"openApiSchema": {
"s3": {
"uri": "s3://your-bucket/path/to/open-api-spec.json",
"bucketOwnerAccountId": "123456789012"
}
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "API_KEY",
"credentialProvider": {
"apiKeyCredentialProvider": {
"providerArn": "arn:aws:agent-credential-provider:us-east-1:123456789012:token-vault/default/apikeycredentialprovider/abcdefghijk",
"credentialLocation": "HEADER",
"credentialParameterName": "X-API-Key"
}
}
}
]
)
```
1. 在 AgentCore CLI 交互式终端用户界面中`agentcore`，运行，选择**添加**，选择**网关目标**，然后选择 **OpenAPI 架构**：
然后，向导会提示您输入目标名称、OpenAPI 规范文件的路径和出站授权配置。
## 添加一个 Smithy 目标
选择以下方法之一：
**Example**
1. 要添加 Smithy 模型目标，请`agentcore add gateway-target`使用`--type smithy-model`选项运行并提供 Smithy 模型文件的路径：
```
agentcore add gateway-target \
--name MySmithyTarget \
--type smithy-model \
--schema path/to/smithy-model.json \
--gateway MyGateway
agentcore deploy
```
1. 以下 Python 代码演示了如何使用 Pyth AWS on SDK (Boto3) 添加 Smithy 模型目标：
```
import boto3
# Create the agentcore client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create a Smithy model target
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="DynamoDBTarget",
targetConfiguration={
"mcp": {
"smithyModel": {
"s3": {
"uri": "s3://your-bucket/path/to/smithy-model.json",
"bucketOwnerAccountId": "123456789012"
}
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]
)
```
1. 在 AgentCore CLI 交互式终端用户界面中`agentcore`，运行，选择**添加**，选择**网关目标**，然后选择 **Smithy 模型**：
然后，向导会提示您输入目标名称、Smithy 模型文件的路径和出站授权配置。
## 添加 HTTP 运行时目标
您可以将 Amazon Bedrock AgentCore 运行时代理作为 HTTP 目标添加到您的网关。网关将流量直接发送到运行时代理，无需聚合或协议转换。
有关 HTTP 目标的更多信息，请参阅 [Amazon Bedrock AgentCore 运行时目标](gateway-target-http-runtime.md)。
选择以下方法之一：
**Example**
1. 以下命令创建具有 IAM 授权的 HTTP 运行时目标：
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "MyRuntimeTarget" \
--description "Runtime gateway target" \
--target-configuration '{
"http": {
"agentcoreRuntime": {
"arn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID"
}
}
}' \
--credential-provider-configurations '[{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}]'
```
1. 以下 Python 代码展示了如何使用 Pyt AWS hon SDK (Boto3) 添加 HTTP 运行时目标：
```
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"
}
]
)
```
## 添加 MCP 服务器目标
你可以使用 C AgentCore LI 或 P AWS ython SDK (Boto3) 添加 MCP 服务器目标。以下示例说明如何创建具有不同出站授权类型的 MCP 服务器目标。
**具有 IAM (Sigv4) 授权的 MCP 服务器**
以下示例创建了一个具有 IAM 授权的 MCP 服务器目标。网关使用带有网关服务角色凭据的 Sigv4 对 MCP 服务器的请求进行签名。必须指定签`service`名的名称。`region`是可选的，默认为网关的区域。
的值`service`取决于您的 MCP 服务器的托管位置。以下是常用值：
+ `bedrock-agentcore`— 适用于托管在 Amazon Bedrock 上的 MCP 服务器 AgentCore，例如运行时（参见[在 AgentCore 运行时部署 MCP 服务器](runtime-mcp.md)）或其他网关。
+ `execute-api`— 适用于亚马逊 API Gateway 后面的 MCP 服务器。
+ `lambda`— 适用于 Lambda 函数网址后面的 MCP 服务器。
选择以下方法之一：
**Example**
1.
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "MyMCPTarget" \
--target-configuration '{
"mcp": {
"mcpServer": {
"endpoint": "https://my-server.bedrock-agentcore.us-west-2.api.aws"
}
}
}' \
--credential-provider-configurations '[{
"credentialProviderType": "GATEWAY_IAM_ROLE",
"credentialProvider": {
"iamCredentialProvider": {
"service": "bedrock-agentcore",
"region": "us-west-2"
}
}
}]'
```
1. 在 AgentCore CLI 交互式终端用户界面中`agentcore`，运行，选择**添加**，选择**网关目标**，然后选择 **MCP 服务器端点**：
然后，向导会提示您输入目标名称、MCP 服务器端点 URL 和出站授权配置。
1.
```
import boto3
agentcore_client = boto3.client('bedrock-agentcore-control')
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="MyMCPTarget",
targetConfiguration={
"mcp": {
"mcpServer": {
"endpoint": "https://my-server.bedrock-agentcore.us-west-2.api.aws"
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE",
"credentialProvider": {
"iamCredentialProvider": {
"service": "bedrock-agentcore",
"region": "us-west-2"
}
}
}
]
)
```
**具有 OAuth 授权的 MCP 服务器**
以下示例创建了一个具有 OAuth（客户端凭证）授权的 MCP 服务器目标。
选择以下方法之一：
**Example**
1.
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "MyMCPTarget" \
--target-configuration '{
"mcp": {
"mcpServer": {
"endpoint": "https://my-mcp-server.example.com"
}
}
}' \
--credential-provider-configurations '[{
"credentialProviderType": "OAUTH",
"credentialProvider": {
"oauthCredentialProvider": {
"providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/oauth2credentialprovider/my-oauth-provider",
"scopes": []
}
}
}]'
```
1. 要添加具有 OAuth 授权的 MCP 服务器目标，请使用`--type mcp-server`选项运行并指定 OAuth `agentcore add gateway-target` 凭据：
```
agentcore add gateway-target \
--type mcp-server \
--name MyMCPTarget \
--endpoint https://my-mcp-server.example.com \
--gateway MyGateway \
--outbound-auth oauth \
--oauth-client-id my-client \
--oauth-client-secret my-secret \
--oauth-discovery-url https://auth.example.com/.well-known/openid-configuration
agentcore deploy
```
1.
```
import boto3
agentcore_client = boto3.client('bedrock-agentcore-control')
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="MyMCPTarget",
targetConfiguration={
"mcp": {
"mcpServer": {
"endpoint": "https://my-mcp-server.example.com"
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "OAUTH",
"credentialProvider": {
"oauthCredentialProvider": {
"providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/oauth2credentialprovider/my-oauth-provider",
"scopes": []
}
}
}
]
)
```
**具有 API 密钥授权的 MCP 服务器**
以下示例创建了一个具有 API 密钥授权的 MCP 服务器目标。
选择以下方法之一：
**Example**
1.
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "MyMCPTarget" \
--target-configuration '{
"mcp": {
"mcpServer": {
"endpoint": "https://my-mcp-server.example.com"
}
}
}' \
--credential-provider-configurations '[{
"credentialProviderType": "API_KEY",
"credentialProvider": {
"apiKeyCredentialProvider": {
"providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-api-key",
"credentialLocation": "HEADER",
"credentialParameterName": "x-api-key",
"credentialPrefix": ""
}
}
}]'
```
1.
```
import boto3
agentcore_client = boto3.client('bedrock-agentcore-control')
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="MyMCPTarget",
targetConfiguration={
"mcp": {
"mcpServer": {
"endpoint": "https://my-mcp-server.example.com"
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "API_KEY",
"credentialProvider": {
"apiKeyCredentialProvider": {
"providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-api-key",
"credentialLocation": "HEADER",
"credentialParameterName": "x-api-key",
"credentialPrefix": ""
}
}
}
]
)
```
## 使用 Amazon Bedrock 托管知识库添加连接器目标
您可以将 Amazon Bedrock 托管知识库连接器作为目标添加到您的网关。
有关 Amazon Bedrock 托管知识库连接器的更多信息，请参阅[亚马逊 Bedrock 托管知识库](gateway-target-connector-managed-kb.md)。
### 设置托管知识库
连接器公开了两个工具，每个工具都以其后端操作命名：`AgenticRetrieveStream`（多步骤，流式代理检索）和`Retrieve`（单个混合搜索）。您可以为每个工具添加一个配置条目。
对于`AgenticRetrieveStream`，设置`retrievers`（要查询的托管知识库），然后`agenticRetrieveConfiguration`在`parameterValues`。两者都是必需的，省略`agenticRetrieveConfiguration`会导致运行时错误。它可以是一个空对象 (`{}`) 来接受服务管理的默认值，但要指定`foundationModelType`并`rerankingModelType`明确配置。代理在呼叫时不提供知识库 ID。对于`Retrieve`，请设置`knowledgeBaseId`输入`parameterValues`；这是必需的。
该连接器仅支持托管知识库。连接器目标仅支持`GATEWAY_IAM_ROLE`凭据提供程序类型。
**Example**
1. 以下 Python 代码展示了如何使用 Pyth AWS on SDK (Boto3) 使用亚马逊 Bedrock 托管知识库连接器配置创建网关目标：
```
import boto3
gateway_client = boto3.client("bedrock-agentcore-control", region_name="")
gateway_client.create_gateway_target(
name="managed-kb",
gatewayIdentifier="",
targetConfiguration={
"mcp": {
"connector": {
"source": {"connectorId": "bedrock-knowledge-bases"},
"configurations": [
{
"name": "AgenticRetrieveStream",
"parameterValues": {
"retrievers": [
{
"description": "Product documentation",
"configuration": {"knowledgeBase": {"knowledgeBaseId": ""}},
},
{
"description": "Engineering runbooks",
"configuration": {"knowledgeBase": {"knowledgeBaseId": ""}},
},
],
"agenticRetrieveConfiguration": {
"foundationModelType": "MANAGED",
"rerankingModelType": "MANAGED",
},
},
},
{
"name": "Retrieve",
"parameterValues": {"knowledgeBaseId": ""},
},
],
}
}
},
credentialProviderConfigurations=[
{"credentialProviderType": "GATEWAY_IAM_ROLE"}
],
)
```
1. 以下命令使用 AWS CLI 创建具有 Amazon Bedrock 托管知识库连接器配置的网关目标：
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "" \
--name "managed-kb" \
--target-configuration '{
"mcp": {
"connector": {
"source": {
"connectorId": "bedrock-knowledge-bases"
},
"configurations": [
{
"name": "AgenticRetrieveStream",
"parameterValues": {
"retrievers": [
{
"description": "Product documentation",
"configuration": {"knowledgeBase": {"knowledgeBaseId": ""}}
},
{
"description": "Engineering runbooks",
"configuration": {"knowledgeBase": {"knowledgeBaseId": ""}}
}
],
"agenticRetrieveConfiguration": {
"foundationModelType": "MANAGED",
"rerankingModelType": "MANAGED"
}
}
},
{
"name": "Retrieve",
"parameterValues": {
"knowledgeBaseId": ""
}
}
]
}
}
}' \
--credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
--region ""
```
1. 要添加托管知识库连接器目标，请`agentcore add gateway-target`使用`--type connector --connector bedrock-knowledge-bases`以下命令运行：
```
agentcore add gateway-target \
--name MyKnowledgeBaseTarget \
--type connector \
--connector bedrock-knowledge-bases \
--knowledge-base-id \
--gateway MyGateway
agentcore deploy
```
1. 在 AgentCore CLI 交互式终端用户界面中，运行`agentcore add gateway-target`，然后从目标类型选择器中选择 **Amazon Bedrock 知识库**：
向导会提示您输入名称和描述，并允许您选择一个或多个源类型和源。
在您调用后`CreateGatewayTarget`，Gateway 会异步验证配置（通常在大约 30 秒内），其中包括`GetKnowledgeBase`检查每个绑定的知识库。轮询`GetGatewayTarget`直到`status`是`READY`；`FAILED`状态包括描述问题的原因。
要自定义代理检索（例如，限制规划迭代次数或安装护栏），请将可选字段添加到。`agenticRetrieveConfiguration`如果省略它们，则应用服务管理的默认值。有关所有可接受的值，请参阅[配置参考](gateway-target-connector-managed-kb.md#gateway-target-connector-managed-kb-config-reference)。
```
{
"name": "AgenticRetrieveStream",
"parameterValues": {
"retrievers": [
{ "configuration": { "knowledgeBase": { "knowledgeBaseId": "" } } }
],
"agenticRetrieveConfiguration": {
"maxAgentIteration": 5,
"policyConfiguration": {
"guardrailConfiguration": {
"guardrailId": "",
"guardrailVersion": "1"
}
}
}
}
}
```
### 控制代理可以设置哪些参数
每个工具配置条目都接受两个参数控件，用于确定调用代理所看到的内容以及网关向知识库发送的内容：
+ `parameterValues`— 管理员设置的每次呼叫时发送到知识库的值，例如绑定值`knowledgeBaseId`或默认值。`numberOfResults`除非代理覆盖您已公开的字段，否则将使用这些字段。
+ `parameterOverrides`— 控制代理在呼叫时可以查看和设置哪些请求字段的列表。每个参赛作品都有：
+ `path`— `Retrieve` 请求中的字段，例如`$.retrievalQuery.text`或`$.retrievalConfiguration.managedSearchConfiguration.numberOfResults`。
+ `description`— 向代理显示的可选文本，描述该字段。
+ `visible`— 设置为`true`可向代理显示该字段，或者`false`在发送任何管理员配置的默认值时将其隐藏。
绑定 `knowledgeBaseId``parameterValues`，不要暴露它。
以下配置条目绑定知识库，将默认结果设置为 10 个，并将查询文本和结果计数显示给代理：
```
{
"name": "Retrieve",
"description": "Search the knowledge base for relevant documents.",
"parameterValues": {
"knowledgeBaseId": "",
"retrievalConfiguration": {
"managedSearchConfiguration": {
"numberOfResults": 10
}
}
},
"parameterOverrides": [
{
"path": "$.retrievalQuery.text",
"description": "The search query. Use specific keywords for best results.",
"visible": true
},
{
"path": "$.retrievalConfiguration.managedSearchConfiguration.numberOfResults",
"description": "Number of results to retrieve (1-100).",
"visible": true
}
]
}
```
### 配置网关服务角色
此连接器使用**网关执行角色**，即您传递给的 IAM 角色 ARN`CreateGateway`， AgentCore 服务假定该角色代表您调用后端。这是您创建的角色，而不是与服务相关的角色。对于 Amazon Bedrock 托管知识库连接器，它需要以下权限：
+ `bedrock:GetKnowledgeBase`— 在创建目标时验证绑定的知识库。范围限于托管知识库资源。
+ `bedrock:Retrieve`— 用于`Retrieve`工具。范围限于托管知识库资源。
+ `bedrock:AgenticRetrieveStream`— 用于`AgenticRetrieveStream`工具。此操作的范围不限于托管知识库资源，因此请将其授予。`*`
网关将后端调用作为`bedrock`服务进行签名。`bedrock:GetKnowledgeBase`无论添加哪种工具，都要包含；如果您只添加一个工具，则仅包含该工具的检索操作。
**注意**
`bedrock-agentcore:InvokeGateway`不是执行角色的一部分。该权限属于**调用方（调用**网关的代理或应用程序），而不属于网关所扮演的角色。
向附加到网关的执行角色添加包含以下内容的策略：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ValidateKnowledgeBase",
"Effect": "Allow",
"Action": "bedrock:GetKnowledgeBase",
"Resource": "arn:aws:bedrock:::knowledge-base/"
},
{
"Sid": "RetrieveFromKnowledgeBase",
"Effect": "Allow",
"Action": "bedrock:Retrieve",
"Resource": "arn:aws:bedrock:::knowledge-base/"
},
{
"Sid": "AgenticRetrieveStream",
"Effect": "Allow",
"Action": "bedrock:AgenticRetrieveStream",
"Resource": "*"
}
]
}
```
服务角色还必须信任该 AgentCore 服务，这样它才能代入该角色。附上以下信任策略，使用和`aws:SourceArn`条件将其范围限定到您的账户和 Gateway：`aws:SourceAccount`
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowAgentCoreToAssumeRole",
"Effect": "Allow",
"Principal": {
"Service": "bedrock-agentcore.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": ""
},
"ArnLike": {
"aws:SourceArn": "arn:aws:bedrock-agentcore:::gateway/*"
}
}
}
]
}
```
## 使用 Web 搜索工具添加连接器目标
您可以将内置连接器添加为网关的目标。Web Search Tool 连接器无需自定义基础架构或 API 密钥即可提供托管网络搜索功能。
有关 Web 搜索工具连接器的更多信息，请参阅 [Web 搜索工具](gateway-target-connector-web-search-tool.md)。
### 设置 Web 搜索工具
**Example**
1. 以下 Python 代码演示了如何使用 Pyth AWS on SDK (Boto3) 使用网络搜索工具连接器配置创建网关目标：
```
import boto3
gateway_client = boto3.client("bedrock-agentcore-control", region_name="")
gateway_client.create_gateway_target(
name="web-search-tool",
gatewayIdentifier="",
targetConfiguration={
"mcp": {
"connector": {
"source": {"connectorId": "web-search"},
"configurations": [{"name": "WebSearch", "parameterValues": {}}],
}
}
},
credentialProviderConfigurations=[
{"credentialProviderType": "GATEWAY_IAM_ROLE"}
],
)
```
1. 以下命令使用 AWS CLI 创建具有 Web 搜索工具连接器配置的网关目标：
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "" \
--name "web-search-tool" \
--target-configuration '{
"mcp": {
"connector": {
"source": {
"connectorId": "web-search"
},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {}
}
]
}
}
}' \
--credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
--region ""
```
1. 要添加 Web 搜索工具目标，请`agentcore add gateway-target`使用`--type connector --connector web-search`以下命令运行：
```
agentcore add gateway-target \
--name MyWebSearchTarget \
--type connector \
--connector web-search \
--gateway MyGateway
agentcore deploy
```
1. 在 AgentCore CLI 交互式终端用户界面中，运行`agentcore add gateway-target`，然后从目标类型选择器中选择 **Amazon Web Search**：
向导会提示您输入目标名称、要连接的网关以及要从搜索结果中排除的可选域名列表。
### 配置域筛选
您可以通过配置域名拒绝列表来限制允许网络搜索工具查询哪些域。这对于想要阻止代理返回来自特定网站的结果的管理员很有用。
创建或更新 Gateway Target 时，使用`parameterValues.domainFilter.exclude`字段在工具级别配置域过滤。拒绝列表在服务器端强制执行，并且对 LLM 是隐藏的 — 代理不知道限制，也不会收到来自排除域的结果。
以下示例创建了一个带有域筛选功能的 Web 搜索工具目标，该目标不包括`blocked-website-1.com`和中的结果`blocked-website-2.com`：
**Example**
1. 以下 Python 代码展示了如何使用 Pyth AWS on SDK (Boto3) 创建带有域过滤功能的网络搜索工具目标：
```
import boto3
gateway_client = boto3.client("bedrock-agentcore-control", region_name="")
gateway_client.create_gateway_target(
name="web-search-tool",
gatewayIdentifier="",
targetConfiguration={
"mcp": {
"connector": {
"source": {"connectorId": "web-search"},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {
"domainFilter": {
"exclude": ["blocked-website-1.com", "blocked-website-2.com"]
}
},
}
],
}
}
},
credentialProviderConfigurations=[
{"credentialProviderType": "GATEWAY_IAM_ROLE"}
],
)
```
1. 以下命令使用 AWS CLI 创建具有域过滤功能的 Web 搜索工具目标：
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "" \
--name "web-search-tool" \
--target-configuration '{
"mcp": {
"connector": {
"source": {
"connectorId": "web-search"
},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {
"domainFilter": {
"exclude": ["blocked-website-1.com", "blocked-website-2.com"]
}
}
}
]
}
}
}' \
--credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
--region ""
```
1. 通过以下方式传递以逗号分隔的域名列表：`--exclude-domains`
```
agentcore add gateway-target \
--name MyWebSearchTarget \
--type connector \
--connector web-search \
--exclude-domains blocked-website-1.com,blocked-website-2.com \
--gateway MyGateway
agentcore deploy
```
1. 在 AgentCore CLI 交互式终端用户界面中，在您选择 A **mazon Web Search 并选择网关后，“添加网关目标” 向导会提示您输入一个以逗号分隔的可选域名列表，以便从搜索**结果中排除。将提示留空会创建不进行域筛选的目标。
您也可以使用更新现有目标以添加或修改域筛选`UpdateGatewayTarget`。
### 配置网关服务角色
Gateway 需要一个允许 AgentCore 服务代表您执行操作的服务角色。对于 Web 搜索工具，该角色需要以下权限：
+ `bedrock-agentcore:InvokeGateway`— 调用网关
+ `bedrock-agentcore:InvokeWebSearch`— 要授权网络搜索调用，请根据服务拥有的 ARN 对每个请求进行检查 `arn:aws:bedrock-agentcore::aws:tool/web-search.v1`
向附加到网关的服务角色添加包含以下内容的策略：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "InvokeGateway",
"Effect": "Allow",
"Action": "bedrock-agentcore:InvokeGateway",
"Resource": "arn:aws:bedrock-agentcore:::gateway/*"
},
{
"Sid": "InvokeWebSearch",
"Effect": "Allow",
"Action": "bedrock-agentcore:InvokeWebSearch",
"Resource": "arn:aws:bedrock-agentcore::aws:tool/web-search.v1"
}
]
}
```