# 게이트웨이 대상 구성 정의
대상 구성은 게이트웨이에 추가하려는 대상 유형에 따라 다릅니다. 지원되는 게이트웨이 대상 유형에 대한 자세한 내용은 [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)
+ [웹 검색 도구를 사용하여 커넥터 대상 추가](#gateway-add-target-api-connector-web-search)
## Lambda 대상 추가
를 `--type`로 지정`lambda-function-arn`하고 Lambda ARN 및 도구 스키마 파일을 제공하여 AgentCore CLI를 사용하여 게이트웨이에 Lambda 대상을 추가할 수 있습니다.
**대상 구성**
Lambda 함수의 대상 구성(또는 페이로드)에는 다음 필드가 포함됩니다.
+ **lambdaArn** - 대상으로 사용할 Lambda 함수의 ARN입니다.
+ **toolSchema** - 게이트웨이 대상의 도구 스키마입니다.
Lambda 대상에 대한 자세한 내용은 [AWS Lambda 함수 대상](gateway-add-target-lambda.md)을 참조하세요.
다음 방법 중 하나를 선택합니다.
**Example**
1. Lambda 함수를 대상으로 추가하려면 `--type lambda-function-arn` 옵션을 `agentcore add gateway-target` 사용하여를 실행합니다. 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 코드는 AWS Python SDK(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 대화형 터미널 UI에서 `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 단계를 대상으로 추가하려면 `--type api-gateway` 옵션을 `agentcore add gateway-target` 사용하여를 실행합니다.
```
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 SDK(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 대화형 터미널 UI에서 `agentcore`를 실행하고 **추가**를 선택한 다음 **게이트웨이 대상**을 선택한 다음 **API Gateway REST API**를 선택합니다.
그러면 마법사가 대상 이름, REST API ID, 단계 및 아웃바운드 권한 부여 구성을 묻는 메시지를 표시합니다.
## OpenAPI 대상 추가
다음 방법 중 하나를 선택합니다.
**Example**
1. OpenAPI 스키마 대상을 추가하려면 `--type open-api-schema` 옵션과 `agentcore add gateway-target` 함께를 실행하고 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 코드는 AWS Python SDK(Boto3)를 사용하여 OpenAPI 대상을 추가하는 방법을 보여줍니다. 스키마가에서 URI가 참조되는 S3 위치에 업로드되었습니다`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 대화형 터미널 UI에서 `agentcore`를 실행하고 **추가**를 선택한 다음 **게이트웨이 대상**을 선택한 다음 **OpenAPI 스키마**를 선택합니다.
그러면 마법사가 대상 이름, OpenAPI 사양 파일의 경로 및 아웃바운드 권한 부여 구성을 묻는 메시지를 표시합니다.
## Smithy 대상 추가
다음 방법 중 하나를 선택합니다.
**Example**
1. Smithy 모델 대상을 추가하려면 `--type smithy-model` 옵션을 `agentcore add gateway-target` 사용하여를 실행하고 Smithy 모델 파일의 경로를 제공합니다.
```
agentcore add gateway-target \
--name MySmithyTarget \
--type smithy-model \
--schema path/to/smithy-model.json \
--gateway MyGateway
agentcore deploy
```
1. 다음 Python 코드는 AWS Python 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 대화형 터미널 UI에서 `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 코드는 AWS Python 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 서버 대상 추가
AgentCore CLI 또는 AWS Python SDK(Boto3)를 사용하여 MCP 서버 대상을 추가할 수 있습니다. 다음 예제에서는 다양한 아웃바운드 권한 부여 유형을 사용하여 MCP 서버 대상을 생성하는 방법을 보여줍니다.
**IAM(SigV4) 권한이 있는 MCP 서버**
다음 예제에서는 IAM 권한 부여를 사용하여 MCP 서버 대상을 생성합니다. 게이트웨이는 게이트웨이 서비스 역할의 자격 증명과 함께 SigV4를 사용하여 MCP 서버에 대한 요청에 서명합니다. 서명할 `service` 이름을 지정해야 합니다. `region`는 선택 사항이며 기본적으로 게이트웨이의 리전으로 설정됩니다.
의 값은 MCP 서버가 호스팅되는 위치에 `service` 따라 달라집니다. 다음은 일반적인 값입니다.
+ `bedrock-agentcore` - 런타임( AgentCore 런타임에서 MCP 서버 [배포 참조) 또는 다른 게이트웨이와 같이 Amazon Bedrock AgentCore에서 호스팅되는 MCP 서버의](runtime-mcp.md) 경우.
+ `execute-api` - Amazon API Gateway 뒤에 있는 MCP 서버의 경우.
+ `lambda` - Lambda 함수 URLs 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 대화형 터미널 UI에서 `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` 옵션을 `agentcore add gateway-target` 사용하여를 실행하고 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
```
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 Managed Knowledge Bases 커넥터를 게이트웨이에 대상으로 추가할 수 있습니다.
Amazon Bedrock Managed Knowledge Bases 커넥터에 대한 자세한 내용은 [Amazon Bedrock Managed Knowledge Bases를 참조하세요](gateway-target-connector-managed-kb.md).
### 관리형 지식 기반 설정
커넥터는 백엔드 작업`AgenticRetrieveStream`(다단계, 스트리밍 에이전트 검색) 및 `Retrieve` (단일 하이브리드 검색)의 이름을 따서 각각 명명된 두 개의 도구를 노출합니다. 도구당 구성 항목을 추가합니다.
의 경우 `agenticRetrieveConfiguration`에서 `retrievers` (쿼리할 관리형 지식 기반) 및를 `AgenticRetrieveStream`설정합니다`parameterValues`. 둘 다 필요합니다. 생략하면 런타임 오류가 `agenticRetrieveConfiguration` 발생합니다. 서비스 관리형 기본값을 수락하는 빈 객체(`{}`)일 수 있지만를 지정`foundationModelType`하고 구성을 명시적으로 `rerankingModelType` 만듭니다. 에이전트는 통화 시 지식 기반 IDs 제공하지 않습니다. 의 경우 `knowledgeBaseId`에서를 `Retrieve`설정합니다. 필수 항목`parameterValues`입니다.
커넥터는 관리형 지식 기반만 지원합니다. 커넥터 대상은 `GATEWAY_IAM_ROLE` 자격 증명 공급자 유형만 지원합니다.
**Example**
1. 다음 Python 코드는 AWS Python SDK(Boto3)를 사용하여 Amazon Bedrock Managed Knowledge Bases 커넥터 구성을 사용하여 게이트웨이 대상을 생성하는 방법을 보여줍니다.
```
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 Managed Knowledge Bases 커넥터 구성을 사용하여 게이트웨이 대상을 생성합니다.
```
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 대화형 터미널 UI에서를 실행`agentcore add gateway-target`한 다음 대상 유형 선택기에서 **Amazon Bedrock 지식 기반을 선택합니다.**
마법사에 이름, 설명을 입력하라는 메시지가 표시되고 하나 이상의 소스 유형 및 소스를 선택할 수 있습니다.
`CreateGatewayTarget`를 호출하면 게이트웨이는 각 바인딩된 지식 기반에 대한 `GetKnowledgeBase` 검사를 포함하는 구성을 비동기적으로(일반적으로 약 30초 이내) 검증합니다. `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"
}
}
}
}
}
```
### 에이전트가 설정할 수 있는 파라미터 제어
각 도구 구성 항목은 호출 에이전트가 보는 것과 Gateway가 지식 기반에 보내는 것을 결정하는 두 가지 파라미터 제어를 허용합니다.
+ `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
}
]
}
```
### 게이트웨이 서비스 역할 구성
이 커넥터는 **게이트웨이 실행 역할**, 즉 AgentCore 서비스가 사용자를 대신하여 백엔드를 호출하기 위해 수임`CreateGateway`하는에 전달하는 IAM 역할 ARN을 사용합니다. 이는 사용자가 생성하는 역할이며 서비스 연결 역할이 아닙니다. Amazon Bedrock Managed Knowledge Bases 커넥터의 경우 다음 권한이 필요합니다.
+ `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:SourceAccount` 및 `aws:SourceArn` 조건을 사용하여 계정 및 게이트웨이에 범위를 지정하여 다음 신뢰 정책을 연결합니다.
```
{
"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/*"
}
}
}
]
}
```
## 웹 검색 도구를 사용하여 커넥터 대상 추가
기본 제공 커넥터를 게이트웨이에 대상으로 추가할 수 있습니다. 웹 검색 도구 커넥터는 사용자 지정 인프라 또는 API 키 없이 관리형 웹 검색 기능을 제공합니다.
웹 검색 도구 커넥터에 대한 자세한 내용은 [웹 검색 도구를](gateway-target-connector-web-search-tool.md) 참조하세요.
### 웹 검색 도구 설정
**Example**
1. 다음 Python 코드는 AWS Python 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를 사용하여 웹 검색 도구 커넥터 구성으로 게이트웨이 대상을 생성합니다.
```
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. 웹 검색 도구 대상을 추가하려면 `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 대화형 터미널 UI에서를 실행`agentcore add gateway-target`한 다음 대상 유형 선택기에서 **Amazon Web Search**를 선택합니다.
마법사에 대상 이름, 연결할 게이트웨이, 검색 결과에서 제외할 선택적 도메인 목록을 묻는 메시지가 표시됩니다.
### 도메인 필터링 구성
도메인 거부 목록을 구성하여 웹 검색 도구가 쿼리할 수 있는 도메인을 제한할 수 있습니다. 이는 에이전트가 특정 웹 사이트의 결과를 반환하지 못하도록 하려는 관리자에게 유용합니다.
도메인 필터링은 게이트웨이 대상을 생성하거나 업데이트할 때 `parameterValues.domainFilter.exclude` 필드를 사용하여 도구 수준에서 구성됩니다. 거부 목록은 서버 측에서 적용되며 LLM에서 숨겨집니다. 에이전트는 제한을 인식하지 못하고 제외된 도메인에서 결과를 수신하지 않습니다.
다음 예제에서는 `blocked-website-1.com` 및의 결과를 제외하는 도메인 필터링을 사용하여 웹 검색 도구 대상을 생성합니다. `blocked-website-2.com`
**Example**
1. 다음 Python 코드는 AWS Python 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를 사용하여 도메인 필터링을 사용하여 웹 검색 도구 대상을 생성합니다.
```
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 대화형 터미널 UI에서 게이트웨이 대상 추가 마법사는 **Amazon Web Search**를 선택하고 게이트웨이를 선택한 후 검색 결과에서 제외할 선택적 쉼표로 구분된 도메인 목록을 묻는 메시지를 표시합니다. 프롬프트를 비워 두면 도메인 필터링 없이 대상이 생성됩니다.
를 사용하여 도메인 필터링을 추가하거나 수정하도록 기존 대상을 업데이트할 수도 있습니다`UpdateGatewayTarget`.
### 게이트웨이 서비스 역할 구성
게이트웨이에는 AgentCore 서비스가 사용자를 대신하여 작업을 수행할 수 있는 서비스 역할이 필요합니다. 웹 검색 도구의 경우 역할에 다음 권한이 필요합니다.
+ `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"
}
]
}
```