외부 소스의 레코드 동기화

개요

AWS 에이전트 레지스트리는 제공된 URL에 아웃바운드 자격 증명을 연결하여 외부 소스의 레코드 메타데이터를 자동으로 동기화할 수 있습니다. URL 및 자격 증명 공급자를 제공하면(액세스 권한 부여가 필요하지 않은 퍼블릭 리소스의 경우 선택 사항) 시스템은 서버 및 도구 정의를 추출하고 공식 프로토콜 스키마를 준수하는 레코드의 설명자를 채웁니다. 또한 소스에서 해당 값을 찾을 경우 레코드의 이름, 설명 및 버전을 업데이트합니다.

퍼블릭 MCP 서버에서 동기화

인증 또는 권한 부여가 필요하지 않은 퍼블릭 MCP 서버의 경우:

콘솔

AWS CLI

aws bedrock-agentcore-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "aws-knowledge-server" \
  --descriptor-type MCP \
  --synchronization-type URL \
  --synchronization-configuration '{
    "fromUrl":
    {
        "url": "https://knowledge-mcp.global.api.aws"
    }
  }' \
  --region us-east-1

AWS SDK

import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.create_registry_record(
    registryId='<registryId>',
    name='aws-knowledge-server',
    descriptorType='MCP',
    synchronizationType='URL',
    synchronizationConfiguration={
        'fromUrl': {
            'url': 'https://knowledge-mcp.global.api.aws'
        }
    }
)
print(f"Record ARN: {response['recordArn']}")
print(f"Status: {response['status']}")  # CREATING

레코드는 CREATING 상태로 생성됩니다. 동기화 시간은 메타데이터의 크기에 따라 초에서 분까지 다양합니다. 동기화가 완료되면 서버 및 도구 정의를 포함하여 MCP 서버에서 추출된 설명자를 사용하여 DRAFT로 전환됩니다.

OAuth 보호 MCP 서버에서 동기화

MCP 서버가 OAuth로 보호되는 경우 권한 부여 서버에서 M2M 클라이언트를 생성한 다음 클라이언트 ID와 보안 암호 허용 목록이 포함된 AgentCore Identity에서 자격 증명 공급자를 구성하여 MCP 서버를 호출해야 합니다. 자격 증명 공급자가 있으면 동기화를 위해 레지스트리에 제공할 수 있습니다.

콘솔

AWS CLI

aws bedrock-agentcore-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "oauth-mcp-server" \
  --descriptor-type MCP \
  --synchronization-type URL \
  --synchronization-configuration '{
    "fromUrl":
    {
        "url": "$MCP_OAUTH_URL",
        "credentialProviderConfigurations":
        [
            {
                "credentialProviderType": "OAUTH",
                "credentialProvider":
                {
                    "oauthCredentialProvider":
                    {
                        "providerArn": "$OAUTH_PROVIDER_ARN",
                        "grantType": "CLIENT_CREDENTIALS"
                    }
                }
            }
        ]
    }
  }' \
  --region us-east-1

필요한 추가 IAM 권한:

{
    "Statement":
    [
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:GetWorkloadAccessToken"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:workload-identity-directory/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:GetResourceOauth2Token"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:token-vault/*"
            ]
        }
    ]
}

제한 사항:

IAM 보호 MCP 서버에서 동기화

AgentCore 런타임 또는 AgentCore 게이트웨이의 MCP 서버의 경우 SigV4 서명을 위한 IAM 역할을 지정합니다. 역할에는 대상 서비스에 액세스할 수 있는 권한이 있어야 합니다. 예: AgentCore 런타임bedrock-agentcore:InvokeAgentRuntimeForUser의 bedrock-agentcore:InvokeAgentRuntime 또는 , AgentCore 게이트웨이bedrock-agentcore:InvokeGateway의 .

IAM 역할 외에도 SigV4 서명을 위한 service 필드를 지정해야 합니다. MCP가 AgentCore 런타임 또는 AgentCore 게이트웨이에서 실행되는 경우 값은 bedrock-agentcore 여야 합니다. MCP가 API 게이트웨이에서 실행되는 경우 execute-api 이고 MCP가 lambda에서 실행되는 경우 이어야 합니다lambda.

region 값은 선택 사항입니다. 기본적으로 요청은 레지스트리와 동일한 리전으로 서명됩니다.

콘솔

AWS CLI

aws bedrock-agentcore-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "gateway-mcp-server" \
  --descriptor-type MCP \
  --synchronization-type URL \
  --synchronization-configuration '{
    "fromUrl":
    {
        "url": "$MCP_IAM_URL",
        "credentialProviderConfigurations":
        [
            {
                "credentialProviderType": "IAM",
                "credentialProvider":
                {
                    "iamCredentialProvider":
                    {
                        "roleArn": "$IAM_ROLE_ARN",
                        "service": "$SIGNING_SERVICE",
                        "region": "$SIGNING_REGION"
                    }
                }
            }
        ]
    }
  }' \
  --region us-east-1

필요한 추가 IAM 권한:

{
    "Statement":
    [
        {
            "Effect": "Allow",
            "Action":
            [
                "iam:PassRole"
            ],
            "Resource":
            [
                "arn:aws:iam::<account>:role/<sync-role>"
            ],
            "Condition":
            {
                "StringEquals":
                {
                    "iam:PassedToService": "bedrock-agentcore.amazonaws.com"
                }
            }
        }
    ]
}

A2A 에이전트 카드에서 동기화

를 검색할 .well-known/agent-card.json 수 있는 에이전트 카드 URL 또는 에이전트의 기본 URL을 제공합니다.

콘솔

AWS CLI

aws bedrock-agentcore-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "travel-agent" \
  --descriptor-type A2A \
  --synchronization-type URL \
  --synchronization-configuration '{"fromUrl": {"url": "https://agent.example.com/.well-known/agent-card.json"}}' \
  --region us-east-1

A2A 동기화를 위한 자격 증명 공급자를 지정할 수도 있습니다. 예를 들어 AgentCore에서 호스팅되는 에이전트에서 동기화할 수 있습니다.

aws bedrock-agentcore-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "a2a_agent_record" \
  --descriptor-type A2A \
  --synchronization-type URL \
  --synchronization-configuration "{
    \"fromUrl\": {
        \"url\": \"$A2A_URL\",
        \"credentialProviderConfigurations\": [{
            \"credentialProviderType\": \"IAM\",
            \"credentialProvider\": {
                \"iamCredentialProvider\": {
                    \"roleArn\": \"$IAM_INVOKER_ROLE\",
                    \"service\": \"bedrock-agentcore\"
                }
            }
        }]
    }
  }"

기존 레코드에서 동기화 트리거

콘솔

레코드는 동기화 중에 업데이트 중 상태로 전환됩니다. 완료되면 소스의 업데이트된 설명자와 함께 초안으로 돌아갑니다. 동기화에 실패하면 레코드가 상태 이유 필드에서 사용 가능한 오류 세부 정보와 함께 UPDATE_FAILED 상태로 전환됩니다. 문제 해결은 동기화 오류 기록을 참조하세요.

또는 편집 중에 동기화를 트리거할 수 있습니다.

AWS CLI

aws bedrock-agentcore-control update-registry-record \
  --registry-id $REGISTRY_ID \
  --record-id $RECORD_ID \
  --trigger-synchronization \
  --region us-east-1

AWS SDK

import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.update_registry_record(
    registryId='<registryId>',
    recordId='<recordId>',
    triggerSynchronization=True
)
print(f"Status: {response['status']}")

문제 해결: 동기화 오류 기록을 참조하세요.