View a markdown version of this page

从外部来源同步记录 - Amazon Bedrock AgentCore
概述从公共 MCP 服务器进行同步从 OAuth-protected MCP 服务器进行同步从 IAM-protected MCP 服务器进行同步从 A2A 代理卡进行同步触发现有记录的同步
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

从外部来源同步记录

迁移现已开放

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

概述

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

从公共 MCP 服务器进行同步

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

控制台

例
Amazon Agent Registry namespace

  1. 在 Amazon Agent Registry 控制台中打开注册表详细信息页面。

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

  3. 选择从端点同步。

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

  5. 对于 Endpoint，输入公共 MCP 服务器网址（例如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. 对于 Endpoint，输入公共 MCP 服务器网址（例如https://knowledge-mcp.global.api.aws）。必须是有效的 HTTPS 网址。

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

  7. 选择创建记录。

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

Amazon CLI

例
Amazon 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

Amazon SDK

例
Amazon 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（仅支持主描述符mcpServer和a2aAgentCard主描述符）。顶级synchronizationType/synchronizationConfiguration字段已不存在。

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

从 OAuth-protected MCP 服务器进行同步

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

控制台

例
Amazon Agent Registry namespace

  1. 在 Amazon Agent Registry 控制台中打开注册表详细信息页面。

  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 凭据连接到端点，提取服务器和工具定义，并填充记录的描述符。同步完成后，记录将转换为 “草稿”。如果同步失败，则记录将转换为 CREATE_FAILED 状态，错误详细信息显示在 “状态原因” 字段中。有关疑难解答，请参阅记录同步错误。

Amazon CLI

例
Amazon 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/ 例如token-vault/default/oauth2credentialprovider/或向账户中的每个 OAuth 凭证提供者授予访问权限，这样可以启用跨团队凭证访问权限。例如，通过在Resource字段中命名特定的提供商来遵循最低权限原则arn:aws:bedrock-agentcore:<region>:<account>:token-vault/default/oauth2credentialprovider/<oauthProviderName>。

限制：

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

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

从 IAM-protected MCP 服务器进行同步

对于 Amazon Bedrock R AgentCore untime 或 Amazon Bedrock AgentCore Gateway 上的 MCP 服务器，请指定用于 Sigv4 签名的 IAM 角色。该角色必须具有访问目标服务的权限。例如：bedrock-agentcore:InvokeAgentRuntime或者bedrock-agentcore:InvokeAgentRuntimeForUser在 AgentCore Runtime 上；bedrock-agentcore:InvokeGateway在 AgentCore 网关上。

除了 IAM 角色外，您还必须指定用于 Sigv4 签名的service字段。如果您的 MCP 在 R AgentCore untime 或 AgentCore Gateway 上运行，则该值应agent-registry为。如果你的 MCP 在 Amazon API Gateway 上运行execute-api，则应该如此；如果你的 MCP 在 Lambda 上运行，则应该 Amazon 如此。lambda

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

控制台

例
Amazon Agent Registry namespace

  1. 在 Amazon Agent Registry 控制台中打开注册表详细信息页面。

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

  3. 选择从端点同步。

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

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

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

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

  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，请输入要代入的 IAM 角色 ARN 以进行 Sigv4 签名。

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

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

  10. 选择创建记录。

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

Amazon CLI

例
Amazon 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策略授权注册表将角色移交给 Ident AgentCore ity 以进行出站同步。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 代理卡进行同步

提供.well-known/agent-card.json可以找到的代理卡片网址或代理的基本网址：

控制台

例
Amazon Agent Registry namespace

  1. 在 Amazon Agent Registry 控制台中打开注册表详细信息页面。

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

  3. 选择从端点同步。

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

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

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

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

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

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

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

  8. 选择创建记录。

Amazon Bedrock AgentCore namespace (to be deprecated)

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

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

  3. 选择从端点同步。

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

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

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

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

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

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

  7. 选择创建记录。

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

Amazon CLI

例
Amazon 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当同步目标是 Runt AgentCore ime 或 Gateway 上托管的代理时，agent-registry用作service字段。

例
Amazon 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 或 Agent 记录的记录详细信息页面。

例
Amazon Agent Registry namespace

  1. 在 Amazon Agent Registry 控制台的记录详细信息页面中，选择管理，然后选择同步。

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

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

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

  1. 在记录详细信息页面中，选择管理，然后选择编辑。

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

  3. 选择保存更改。

Amazon Bedrock AgentCore namespace (to be deprecated)

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

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

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

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

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

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

  3. 选择保存更改。

同步期间，记录将变为 “正在更新” 状态。完成后，它将返回到草稿，其中包含来自源代码的更新的描述符。如果同步失败，则记录将转换为 UPDATE_FAILED 状态，错误详细信息显示在 “状态原因” 字段中。有关疑难解答，请参阅记录同步错误。

Amazon CLI

例
Amazon 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

Amazon SDK

例
Amazon 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']}")
注意

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

疑难解答：请参阅记录同步错误。