View a markdown version of this page

同步来自外部来源的记录 - 亚马逊基岩 AgentCore
概述从公共 MCP 服务器同步从 OAuth-protected MCP 服务器同步从 IAM-protected MCP 服务器同步从 A2A 代理卡同步在现有记录上触发同步

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

同步来自外部来源的记录

迁移现已开放

AWS 代理注册表已在新agent-registry命名空间下启动。对公共预览bedrock-agentcore命名空间的支持将于 2026 年 9 月 17 日停止。有关迁移说明，请参阅综合注册表迁移指南。

概述

AWS 通过使用出站凭据连接到提供的 URL，代理注册表可以自动同步来自外部来源的记录元数据。当您提供 URL 和凭据提供商（对于不需要任何授权即可访问的公共资源来说是可选的）时，系统会提取服务器和工具定义并填充符合官方协议架构的记录描述符。如果在源中找到这些值，它还会更新记录的名称、描述和版本。

从公共 MCP 服务器同步

对于不需要身份验证或授权的公共 MCP 服务器：

控制台

例
AWS Agent Registry namespace

  1. 在AWS 代理注册表控制台中打开注册表详细信息页面。

  2. 在注册表记录部分，选择创建记录。

  3. 选择 “从端点同步” 。

  4. 在 “记录详细信息” 下的 “类型” 中，选择 MCP 。描述符设置为 MCP 服务器。

  5. 对于端点，输入公共 MCP 服务器 URL（例如，https://knowledge-mcp.global.api.aws）。必须是有效的 HTTPS 网址。

  6. 在 “凭证类型” 下，选择 “无”。

  7. （可选）在 “标签” 部分，选择 “添加新标签” 以将一个或多个标签附加到记录中。每个标签都有一个密钥和一个可选值。

  8. 选择创建记录。

Amazon Bedrock AgentCore namespace (to be deprecated)

  1. 在Bedrock-AgentCore 控制台中打开注册表详细信息页面。

  2. 在注册表记录部分，选择创建记录。

  3. 选择 “从端点同步” 。

  4. 在 “记录详细信息” 下，选择 MCP 作为记录类型。

  5. 对于端点，输入公共 MCP 服务器 URL（例如，https://knowledge-mcp.global.api.aws）。必须是有效的 HTTPS 网址。

  6. 在 “凭证类型” 下，选择 “无”。

  7. 选择创建记录。

该记录的创建状态为 “正在创建”。注册表连接到端点，提取服务器和工具定义，并填充记录的描述符。同步完成后，记录将转换为 DRAFT。如果同步失败，记录将转换为 CREATE_FAILED 状态，错误详细信息可在 “状态原因” 字段中找到。有关故障排除，请参阅记录同步错误。

AWS CLI

例
AWS Agent Registry namespace
aws agent-registry-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "aws-knowledge-server" \
  --display-name "AWS Knowledge Server" \
  --record-type MCP \
  --descriptors '{
    "mcpServer": {
      "source": {
        "fromUrl": {
          "url": "https://knowledge-mcp.global.api.aws"
        }
      }
    }
  }' \
  --region us-east-1
Amazon Bedrock AgentCore namespace (to be deprecated)
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

例
AWS Agent Registry namespace
import boto3

client = boto3.client('agent-registry-control')

response = client.create_registry_record(
    registryId='<registryId>',
    name='aws-knowledge-server',
    displayName='AWS Knowledge Server',
    recordType='MCP',
    descriptors={
        'mcpServer': {
            'source': {
                'fromUrl': {
                    'url': 'https://knowledge-mcp.global.api.aws'
                }
            }
        }
    }
)
print(f"Record ARN: {response['recordArn']}")
print(f"Status: {response['status']}")  # CREATING
Amazon Bedrock AgentCore namespace (to be deprecated)
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
注意

在agent-registry命名空间中，同步配置在每个描述符内移动为source（仅支持a2aAgentCard主描述符）。mcpServer顶级synchronizationType/synchronizationConfiguration字段已不存在。

该记录的创建状态为 “正在创建”。同步时间从几秒到几分钟不等，具体取决于元数据的大小。同步完成后，它将使用从 MCP 服务器提取的描述符（包括服务器和工具定义）转换为草稿。

从 OAuth-protected MCP 服务器同步

当 MCP 服务器受到 OAuth 保护时，您需要在授权服务器上创建一个 M2M 客户端，然后从 Ident AgentCore ity 配置一个包含客户端 ID 和密钥许可名单的凭据提供者来调用 MCP 服务器。有了凭据提供者后，就可以将其提供给注册表进行同步：

控制台

例
AWS Agent Registry namespace

  1. 在AWS 代理注册表控制台中打开注册表详细信息页面。

  2. 在注册表记录部分，选择创建记录。

  3. 选择 “从端点同步” 。

  4. 在 “记录详细信息” 下的 “类型” 中，选择 MCP 。描述符设置为 MCP 服务器。

  5. 对于端点，输入 OAuth-protected MCP 服务器 URL。必须是有效的 HTTPS 网址。

  6. 在 “凭证类型” 下，选择 OAuth 。

  7. 对于凭证提供商，从 “身份” 中选择或输入凭证提供商 ARN。 AgentCore

  8. （可选）展开其他配置以配置：

    1. 范围 — 获取访问令牌时要请求的 OAuth 范围。

    2. 自定义参数 -OAuth 令牌请求的其他键值参数。

  9. （可选）在 “标签” 部分，选择 “添加新标签” 以将一个或多个标签附加到记录中。每个标签都有一个密钥和一个可选值。

  10. 选择创建记录。

Amazon Bedrock AgentCore namespace (to be deprecated)

  1. 在Bedrock-AgentCore 控制台中打开注册表详细信息页面。

  2. 在注册表记录部分，选择创建记录。

  3. 选择 “从端点同步” 。

  4. 在 “记录详细信息” 下，选择 MCP 作为记录类型。

  5. 对于端点，输入 OAuth-protected MCP 服务器 URL。必须是有效的 HTTPS 网址。

  6. 在 “凭证类型” 下，选择 OAuth 。

  7. 对于凭证提供商，从 “身份” 中选择或输入凭证提供商 ARN。 AgentCore

  8. （可选）展开其他配置以配置：

    1. 范围 — 获取访问令牌时要请求的 OAuth 范围。

    2. 自定义参数 -OAuth 令牌请求的其他键值参数。

  9. 选择创建记录。

该记录的创建状态为 “正在创建”。注册表使用 OAuth 凭据连接到端点，提取服务器和工具定义，并填充记录的描述符。同步完成后，记录将转换为 DRAFT。如果同步失败，记录将转换为 CREATE_FAILED 状态，错误详细信息可在 “状态原因” 字段中找到。有关故障排除，请参阅记录同步错误。

AWS CLI

例
AWS Agent Registry namespace
aws agent-registry-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "oauth-mcp-server" \
  --display-name "OAuth MCP Server" \
  --record-type MCP \
  --descriptors '{
    "mcpServer": {
      "source": {
        "fromUrl": {
          "url": "$MCP_OAUTH_URL",
          "credentialProviderConfigurations": [
            {
              "credentialProviderType": "OAUTH",
              "credentialProvider": {
                "oauthCredentialProvider": {
                  "providerArn": "$OAUTH_PROVIDER_ARN",
                  "grantType": "CLIENT_CREDENTIALS"
                }
              }
            }
          ]
        }
      }
    }
  }' \
  --region us-east-1
Amazon Bedrock AgentCore namespace (to be deprecated)
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 权限：

注意

这些与同步相关的 IAM 权限授权工作负载身份和由 Identity 管理的 OAuth 凭证提供者资源。 AgentCore 这些资源故意保留在bedrock-agentcore命名空间下，因此此政策不会改变。

{
    "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:<region>:<account>:token-vault/default/oauth2credentialprovider/<oauthProviderName>"
            ]
        }
    ]
}
注意

将GetResourceOauth2Token声明范围限定为该角色需要其访问令牌的特定 OAuth 凭证提供商 ARN。避免在 ARN 的提供商部分使用通配符——例如token-vault/ 或向账户中的每个 OAuth 凭证提供商token-vault/default/oauth2credentialprovider/授予访问权限，这样可以启用跨团队的凭据访问。例如，遵循最小权限原则，在Resource字段中命名特定的提供商arn:aws:bedrock-agentcore:<region>:<account>:token-vault/default/oauth2credentialprovider/<oauthProviderName>。

限制：

  • CreateRegistryRecord 或的调用者 UpdateRegistryRecord 必须拥有与 GetWorkloadAccessToken 注册表相关的工作负载身份和凭证提供者的 GetResourceOauth2Token 权限。

  • 凭证提供者必须来自同一个账户。

从 IAM-protected MCP 服务器同步

对于亚马逊 Bedrock AgentCore Runtime 或 Amazon Bedrock AgentCore Gateway 上的 MCP 服务器，为 SigV4 签名指定 IAM 角色。该角色必须具有访问目标服务的权限。例如：bedrock-agentcore:InvokeAgentRuntime或者bedrock-agentcore:InvokeAgentRuntimeForUser在 AgentCore 运行时；bedrock-agentcore:InvokeGateway在 AgentCore 网关上。

除了 IAM 角色外，您还必须指定 SigV4 签名的service字段。如果您的 MCP 在 AgentCore 运行时或 AgentCore 网关上运行，则该值应agent-registry为。如果您的 MCP 在亚马逊 API 网关上运行，则应该execute-api如此；如果您的 MCP 在 AWS Lambda 上运行，则应该如此。lambda

region值是可选的。默认情况下，请求将使用与注册表相同的区域进行签名。

控制台

例
AWS Agent Registry namespace

  1. 在AWS 代理注册表控制台中打开注册表详细信息页面。

  2. 在注册表记录部分，选择创建记录。

  3. 选择 “从端点同步” 。

  4. 在 “记录详细信息” 下的 “类型” 中，选择 MCP 。描述符设置为 MCP 服务器。

  5. 对于端点，输入 IAM-protected MCP 服务器 URL。必须是有效的 HTTPS 网址。

  6. 在 “凭证类型” 下，选择 IAM 。

  7. 对于角色 ARN，输入要代入进行 SigV4 签名的 IAM 角色 ARN。

  8. 对于服务，输入用于 SigV4 签名的服务名称（例如、agent-registryexecute-api、lambda）。

  9. （可选）展开其他配置并选择用于 SigV4 签名的区域。如果未指定，则使用注册表自己的区域。

  10. （可选）在标签部分中，选择添加新标签以将一个或多个标签附加到记录中。每个标签都有一个密钥和一个可选值。

  11. 选择创建记录。

Amazon Bedrock AgentCore namespace (to be deprecated)

  1. 在Bedrock-AgentCore 控制台中打开注册表详细信息页面。

  2. 在注册表记录部分，选择创建记录。

  3. 选择 “从端点同步” 。

  4. 在 “记录详细信息” 下，选择 MCP 作为记录类型。

  5. 对于端点，输入 IAM-protected MCP 服务器 URL。必须是有效的 HTTPS 网址。

  6. 在 “凭证类型” 下，选择 IAM 。

  7. 对于角色 ARN，输入要代入进行 SigV4 签名的 IAM 角色 ARN。

  8. 对于服务，输入用于 SigV4 签名的服务名称（例如、、bedrock-agentcoreexecute-api、lambda）。

  9. （可选）展开其他配置并选择用于 SigV4 签名的区域。如果未指定，则使用注册表自己的区域。

  10. 选择创建记录。

该记录的创建状态为 “正在创建”。注册表使用 IAM 证书连接到终端节点，提取服务器和工具定义，并填充记录的描述符。同步完成后，记录将转换为 DRAFT。如果同步失败，记录将转换为 CREATE_FAILED 状态，错误详细信息可在 “状态原因” 字段中找到。有关故障排除，请参阅记录同步错误。

AWS CLI

例
AWS Agent Registry namespace
aws agent-registry-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "gateway-mcp-server" \
  --display-name "Gateway MCP Server" \
  --record-type MCP \
  --descriptors '{
    "mcpServer": {
      "source": {
        "fromUrl": {
          "url": "$MCP_IAM_URL",
          "credentialProviderConfigurations": [
            {
              "credentialProviderType": "IAM",
              "credentialProvider": {
                "iamCredentialProvider": {
                  "roleArn": "$IAM_ROLE_ARN",
                  "service": "$SIGNING_SERVICE",
                  "region": "$SIGNING_REGION"
                }
              }
            }
          ]
        }
      }
    }
  }' \
  --region us-east-1
Amazon Bedrock AgentCore namespace (to be deprecated)
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 权限：

注意

此iam:PassRole策略授权注册表将角色移交给 I AgentCore dentity 以进行出站同步。iam:PassedToService条件值bedrock-agentcore.amazonaws.com是指 AgentCore 身份服务主体，不变。

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

从 A2A 代理卡同步

提供代理卡 URL 或代理的基本 URL，在那里.well-known/agent-card.json可以被发现：

控制台

例
AWS Agent Registry namespace

  1. 在AWS 代理注册表控制台中打开注册表详细信息页面。

  2. 在注册表记录部分，选择创建记录。

  3. 选择 “从端点同步” 。

  4. 在 “记录详细信息” 下的 “类型” 下，选择 “代理” 。描述符设置为 A2A 代理卡。

  5. 对于端点，输入代理卡 URL（例如，https://agent.example.com/.well-known/agent-card.json）。必须是有效的 HTTPS 网址。

  6. 在 “凭证类型” 下，选择相应的授权方法：

    1. 无 -适用于可公开访问的代理卡。

    2. IAM — 适用于 AgentCore 运行时或网关上托管的代理。提供角色 ARN 和服务名称。

    3. OAuth — 适用于 OAuth-protected 代理。选择或输入凭证提供商 ARN。

  7. （可选）在标签部分中，选择添加新标签以将一个或多个标签附加到记录中。每个标签都有一个密钥和一个可选值。

  8. 选择创建记录。

Amazon Bedrock AgentCore namespace (to be deprecated)

  1. 在Bedrock-AgentCore 控制台中打开注册表详细信息页面。

  2. 在注册表记录部分，选择创建记录。

  3. 选择 “从端点同步” 。

  4. 在 “记录详细信息” 下，选择 “代理” 作为记录类型。

  5. 对于端点，输入代理卡 URL（例如，https://agent.example.com/.well-known/agent-card.json）。必须是有效的 HTTPS 网址。

  6. 在 “凭证类型” 下，选择相应的授权方法：

    1. 无 -适用于可公开访问的代理卡。

    2. IAM — 适用于 AgentCore 运行时或网关上托管的代理。提供角色 ARN 和服务名称。

    3. OAuth — 适用于 OAuth-protected 代理。选择或输入凭证提供商 ARN。

  7. 选择创建记录。

该记录的创建状态为 “正在创建”。注册表连接到端点，提取代理卡元数据并填充记录的描述符。同步完成后，记录将转换为 DRAFT。如果同步失败，记录将转换为 CREATE_FAILED 状态，错误详细信息可在 “状态原因” 字段中找到。有关故障排除，请参阅记录同步错误。

AWS CLI

例
AWS Agent Registry namespace
aws agent-registry-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "travel-agent" \
  --display-name "Travel Agent" \
  --record-type AGENT \
  --descriptors '{
    "a2aAgentCard": {
      "source": {
        "fromUrl": {
          "url": "https://agent.example.com/.well-known/agent-card.json"
        }
      }
    }
  }' \
  --region us-east-1
Amazon Bedrock AgentCore namespace (to be deprecated)
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当同步目标是托管在 AgentCore Runtime 或 Gateway 上的代理时，用agent-registry作service字段。

例
AWS Agent Registry namespace
aws agent-registry-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "a2a_agent_record" \
  --display-name "A2A Agent Record" \
  --record-type AGENT \
  --descriptors "{
    \"a2aAgentCard\": {
      \"source\": {
        \"fromUrl\": {
          \"url\": \"$A2A_URL\",
          \"credentialProviderConfigurations\": [{
            \"credentialProviderType\": \"IAM\",
            \"credentialProvider\": {
              \"iamCredentialProvider\": {
                \"roleArn\": \"$IAM_INVOKER_ROLE\",
                \"service\": \"agent-registry\"
              }
            }
          }]
        }
      }
    }
  }"
Amazon Bedrock AgentCore namespace (to be deprecated)
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\"
                }
            }
        }]
    }
  }"

在现有记录上触发同步

控制台

  1. 打开已配置同步的 MCP 或代理记录的记录详细信息页面。

例
AWS Agent Registry namespace

  1. 在AWS 代理注册控制台的记录详细信息页面上，选择管理，然后选择同步。

  2. 在确认对话框中，查看同步将使记录恢复为草稿状态的消息。

  3. 选择 “同步” 进行确认。

或者，你可以在编辑期间触发同步：

  1. 在记录详情页面上，选择管理，然后选择编辑。

  2. 在 “从端点同步” 下，选中 “Re-sync 从端点同步” 复选框。

  3. 选择保存更改。

Amazon Bedrock AgentCore namespace (to be deprecated)

  1. 在Bedrock-AgentCore 控制台的记录详细信息页面上，选择标题操作中的同步按钮。

  2. 在确认对话框中，查看同步将使记录恢复为草稿状态的消息。

  3. 选择 “同步” 进行确认。

或者，你可以在编辑期间触发同步：

  1. 在记录详情页面上，选择三点式菜单 ()，然后选择编辑。

  2. 在 “从端点同步” 下，选中 “Re-sync 从端点同步” 复选框。

  3. 选择保存更改。

同步期间，记录将转换为 UPDATING 状态。完成后，它返回到 DRAFT，其中包含来自源代码的更新描述符。如果同步失败，记录将转换为 UPDATE_FAILED 状态，错误详细信息可在 “状态原因” 字段中找到。有关故障排除，请参阅记录同步错误。

AWS CLI

例
AWS Agent Registry namespace
aws agent-registry-control update-registry-record \
  --registry-id $REGISTRY_ID \
  --record-id $RECORD_ID \
  --trigger-synchronization \
  --region us-east-1
Amazon Bedrock AgentCore namespace (to be deprecated)
aws bedrock-agentcore-control update-registry-record \
  --registry-id $REGISTRY_ID \
  --record-id $RECORD_ID \
  --trigger-synchronization \
  --region us-east-1

AWS SDK

例
AWS Agent Registry namespace
import boto3

client = boto3.client('agent-registry-control')

response = client.update_registry_record(
    registryId='<registryId>',
    recordId='<recordId>',
    triggerSynchronization=True
)
print(f"Status: {response['status']}")
Amazon Bedrock AgentCore namespace (to be deprecated)
import boto3

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

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

如果记录处于非草稿状态（例如，已批准），则更新会创建新的草稿修订版。批准的修订版仍然可以被发现。

故障排除：请参阅记录同步错误。