게이트웨이 대상 구성 정의
대상 구성은 게이트웨이에 추가하려는 대상 유형에 따라 다릅니다. 지원되는 게이트웨이 대상 유형에 대한 자세한 내용은 Amazon Bedrock AgentCore 게이트웨이에 지원되는 대상을 참조하세요.
대상 유형을 추가하는 예를 보려면 주제를 선택합니다.
Lambda 대상 추가
를 --type로 지정lambda-function-arn하고 Lambda ARN 및 도구 스키마 파일을 제공하여 AgentCore CLI를 사용하여 게이트웨이에 Lambda 대상을 추가할 수 있습니다.
대상 구성
Lambda 함수의 대상 구성(또는 페이로드)에는 다음 필드가 포함됩니다.
Lambda 대상에 대한 자세한 내용은 AWS Lambda 함수 대상을 참조하세요.
다음 방법 중 하나를 선택합니다.
예
- AgentCore CLI
-
-
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
- AgentCore Python SDK
-
-
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": "<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
-
-
다음 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"
}
]
)
- Interactive
-
-
AgentCore CLI 대화형 터미널 UI에서 agentcore를 실행하고 추가를 선택한 다음 게이트웨이 대상을 선택한 다음 Lambda 함수를 선택합니다.
그러면 마법사가 대상 이름, Lambda 함수 ARN, 도구 스키마 파일 및 아웃바운드 권한 부여 구성을 묻는 메시지를 표시합니다.
API Gateway 스테이지 대상 추가
API Gateway REST API의 단계를 대상으로 추가하려면 API 및 단계의 ARN을 지정하고 API 게이트웨이의 도구를 필터링하거나 게이트웨이의 도구 이름 및 설명을 재정의하는 설정을 정의합니다.
다음 예제에서는 API Gateway 대상을 추가하는 방법을 보여줍니다. 다음 구성도 적용됩니다.
다음 방법 중 하나를 선택합니다.
예
- AgentCore CLI
-
-
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
- AWS CLI
-
-
다음 명령은 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
-
-
다음 코드는가 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"
}
]
)
- Interactive
-
-
AgentCore CLI 대화형 터미널 UI에서 agentcore를 실행하고 추가를 선택한 다음 게이트웨이 대상을 선택한 다음 API Gateway REST API를 선택합니다.
그러면 마법사가 대상 이름, REST API ID, 단계 및 아웃바운드 권한 부여 구성을 묻는 메시지를 표시합니다.
OpenAPI 대상 추가
다음 방법 중 하나를 선택합니다.
예
- AgentCore CLI
-
-
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
- Boto3
-
-
다음 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"
}
}
}
]
)
- Interactive
-
-
AgentCore CLI 대화형 터미널 UI에서 agentcore를 실행하고 추가를 선택한 다음 게이트웨이 대상을 선택한 다음 OpenAPI 스키마를 선택합니다.
그러면 마법사가 대상 이름, OpenAPI 사양 파일의 경로 및 아웃바운드 권한 부여 구성을 묻는 메시지를 표시합니다.
Smithy 대상 추가
다음 방법 중 하나를 선택합니다.
예
- AgentCore CLI
-
-
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
- Boto3
-
-
다음 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"
}
]
)
- Interactive
-
-
AgentCore CLI 대화형 터미널 UI에서 agentcore를 실행하고 추가를 선택한 다음 게이트웨이 대상을 선택한 다음 Smithy 모델을 선택합니다.
그러면 마법사가 대상 이름, Smithy 모델 파일 경로 및 아웃바운드 권한 부여 구성을 묻는 메시지를 표시합니다.
HTTP 런타임 대상 추가
Amazon Bedrock AgentCore 런타임 에이전트를 게이트웨이에 HTTP 대상으로 추가할 수 있습니다. 게이트웨이는 집계 또는 프로토콜 변환 없이 트래픽을 런타임 에이전트로 직접 전송합니다.
HTTP 대상에 대한 자세한 내용은 Amazon Bedrock AgentCore 런타임 대상을 참조하세요.
다음 방법 중 하나를 선택합니다.
예
- AWS CLI
-
-
다음 명령은 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"
}]'
- Boto3
-
-
다음 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 따라 달라집니다. 다음은 일반적인 값입니다.
다음 방법 중 하나를 선택합니다.
예
- 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
-
-
AgentCore CLI 대화형 터미널 UI에서 agentcore를 실행하고 추가를 선택한 다음 게이트웨이 대상을 선택한 다음 MCP 서버 엔드포인트를 선택합니다.
그러면 마법사가 대상 이름, MCP 서버 엔드포인트 URL 및 아웃바운드 권한 부여 구성을 묻는 메시지를 표시합니다.
- 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"
}
}
}
]
)
OAuth 권한이 있는 MCP 서버
다음 예제에서는 OAuth(클라이언트 자격 증명) 권한 부여를 사용하여 MCP 서버 대상을 생성합니다.
다음 방법 중 하나를 선택합니다.
예
- 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
-
-
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
- 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": []
}
}
}
]
)
API 키 권한이 있는 MCP 서버
다음 예제에서는 API 키 권한 부여를 사용하여 MCP 서버 대상을 생성합니다.
다음 방법 중 하나를 선택합니다.
예
- 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": ""
}
}
}
]
)
Amazon Bedrock 관리형 지식 기반을 사용하여 커넥터 대상 추가
Amazon Bedrock Managed Knowledge Bases 커넥터를 게이트웨이에 대상으로 추가할 수 있습니다.
Amazon Bedrock Managed Knowledge Bases 커넥터에 대한 자세한 내용은 Amazon Bedrock Managed Knowledge Bases를 참조하세요.
관리형 지식 기반 설정
커넥터는 백엔드 작업AgenticRetrieveStream(다단계, 스트리밍 에이전트 검색) 및 Retrieve (단일 하이브리드 검색)의 이름을 따서 각각 명명된 두 개의 도구를 노출합니다. 도구당 구성 항목을 추가합니다.
의 경우 agenticRetrieveConfiguration에서 retrievers (쿼리할 관리형 지식 기반) 및를 AgenticRetrieveStream설정합니다parameterValues. 둘 다 필요합니다. 생략하면 런타임 오류가 agenticRetrieveConfiguration 발생합니다. 서비스 관리형 기본값을 수락하는 빈 객체({})일 수 있지만를 지정foundationModelType하고 구성을 명시적으로 rerankingModelType 만듭니다. 에이전트는 통화 시 지식 기반 IDs 제공하지 않습니다. 의 경우 knowledgeBaseId에서를 Retrieve설정합니다. 필수 항목parameterValues입니다.
커넥터는 관리형 지식 기반만 지원합니다. 커넥터 대상은 GATEWAY_IAM_ROLE 자격 증명 공급자 유형만 지원합니다.
예
- Boto3
-
-
다음 Python 코드는 AWS Python SDK(Boto3)를 사용하여 Amazon Bedrock Managed Knowledge Bases 커넥터 구성을 사용하여 게이트웨이 대상을 생성하는 방법을 보여줍니다.
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
-
-
다음 명령은 AWS CLI를 사용하여 Amazon Bedrock Managed Knowledge Bases 커넥터 구성을 사용하여 게이트웨이 대상을 생성합니다.
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
-
-
관리형 지식 기반 커넥터 대상을 추가하려면를 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 <KB_ID> \
--gateway MyGateway
agentcore deploy
- Interactive
-
-
AgentCore CLI 대화형 터미널 UI에서를 실행agentcore add gateway-target한 다음 대상 유형 선택기에서 Amazon Bedrock 지식 기반을 선택합니다.
마법사에 이름, 설명을 입력하라는 메시지가 표시되고 하나 이상의 소스 유형 및 소스를 선택할 수 있습니다.
CreateGatewayTarget를 호출하면 게이트웨이는 각 바인딩된 지식 기반에 대한 GetKnowledgeBase 검사를 포함하는 구성을 비동기적으로(일반적으로 약 30초 이내) 검증합니다. GetGatewayTarget 까지 폴링status. READY FAILED 상태에는 문제를 설명하는 이유가 포함됩니다.
계획 반복을 제한하거나 가드레일을 연결하는 등 에이전트 검색을 사용자 지정하려면 선택적 필드를에 추가합니다agenticRetrieveConfiguration. 이를 생략하면 서비스 관리형 기본값이 적용됩니다. 허용되는 모든 값은 구성 참조를 참조하세요.
{
"name": "AgenticRetrieveStream",
"parameterValues": {
"retrievers": [
{ "configuration": { "knowledgeBase": { "knowledgeBaseId": "<KB_ID>" } } }
],
"agenticRetrieveConfiguration": {
"maxAgentIteration": 5,
"policyConfiguration": {
"guardrailConfiguration": {
"guardrailId": "<GUARDRAIL_ID>",
"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": "<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
}
]
}
게이트웨이 서비스 역할 구성
이 커넥터는 게이트웨이 실행 역할, 즉 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:<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": "*"
}
]
}
서비스 역할은 역할을 수임할 수 있도록 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": "<ACCOUNT_ID>"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:bedrock-agentcore:<REGION>:<ACCOUNT_ID>:gateway/*"
}
}
}
]
}
웹 검색 도구를 사용하여 커넥터 대상 추가
기본 제공 커넥터를 게이트웨이에 대상으로 추가할 수 있습니다. 웹 검색 도구 커넥터는 사용자 지정 인프라 또는 API 키 없이 관리형 웹 검색 기능을 제공합니다.
웹 검색 도구 커넥터에 대한 자세한 내용은 웹 검색 도구를 참조하세요.
웹 검색 도구 설정
예
- Boto3
-
-
다음 Python 코드는 AWS Python SDK(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
-
-
다음 명령은 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
-
-
웹 검색 도구 대상을 추가하려면 agentcore add gateway-target를 사용하여를 실행합니다--type connector --connector web-search.
agentcore add gateway-target \
--name MyWebSearchTarget \
--type connector \
--connector web-search \
--gateway MyGateway
agentcore deploy
- Interactive
-
-
AgentCore CLI 대화형 터미널 UI에서를 실행agentcore add gateway-target한 다음 대상 유형 선택기에서 Amazon Web Search를 선택합니다.
마법사에 대상 이름, 연결할 게이트웨이, 검색 결과에서 제외할 선택적 도메인 목록을 묻는 메시지가 표시됩니다.
도메인 필터링 구성
도메인 거부 목록을 구성하여 웹 검색 도구가 쿼리할 수 있는 도메인을 제한할 수 있습니다. 이는 에이전트가 특정 웹 사이트의 결과를 반환하지 못하도록 하려는 관리자에게 유용합니다.
도메인 필터링은 게이트웨이 대상을 생성하거나 업데이트할 때 parameterValues.domainFilter.exclude 필드를 사용하여 도구 수준에서 구성됩니다. 거부 목록은 서버 측에서 적용되며 LLM에서 숨겨집니다. 에이전트는 제한을 인식하지 못하고 제외된 도메인에서 결과를 수신하지 않습니다.
다음 예제에서는 blocked-website-1.com 및의 결과를 제외하는 도메인 필터링을 사용하여 웹 검색 도구 대상을 생성합니다. blocked-website-2.com
예
- Boto3
-
-
다음 Python 코드는 AWS Python SDK(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
-
-
다음 명령은 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
-
-
를 통해 쉼표로 구분된 도메인 목록을 전달합니다. --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
-
-
AgentCore CLI 대화형 터미널 UI에서 게이트웨이 대상 추가 마법사는 Amazon Web Search를 선택하고 게이트웨이를 선택한 후 검색 결과에서 제외할 선택적 쉼표로 구분된 도메인 목록을 묻는 메시지를 표시합니다. 프롬프트를 비워 두면 도메인 필터링 없이 대상이 생성됩니다.
를 사용하여 도메인 필터링을 추가하거나 수정하도록 기존 대상을 업데이트할 수도 있습니다UpdateGatewayTarget.
게이트웨이 서비스 역할 구성
게이트웨이에는 AgentCore 서비스가 사용자를 대신하여 작업을 수행할 수 있는 서비스 역할이 필요합니다. 웹 검색 도구의 경우 역할에 다음 권한이 필요합니다.
게이트웨이에 연결된 서비스 역할에 다음 내용이 포함된 정책을 추가합니다.
{
"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"
}
]
}
