# 同步来自外部来源的记录
<a name="registry-sync-records"></a>

**即将进行的命名空间迁移**  
 AWS Agent Registry 目前在 bedrock-agentcore 命名空间下处于公开预览状态。从 2026 年 8 月 6 日起，该服务将移至代理注册表命名空间。如果您使用 AWS 代理注册表，则必须更新您的终端节点、IAM 策略、SDK 客户端、CLI 脚本和注册表数据。有关从公共预览版迁移的更多信息，请参阅[注册表迁移综合指南](registry-faq.md)。

## 概述
<a name="registry-sync-overview"></a>

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

## 从公共 MCP 服务器进行同步
<a name="registry-sync-public"></a>

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

### 控制台
<a name="registry-sync-public-console"></a>

1. 打开注册表详情页面。

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

1. 选择**从端点同步**。

1. 在**记录详细信息**下，选择 **MCP** 作为记录类型。

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

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

1. 选择**创建记录**。

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

### AWS CLI
<a name="registry-sync-public-cli"></a>

```
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
<a name="registry-sync-public-sdk"></a>

```
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
```

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

## 从 OAuth-protected MCP 服务器进行同步
<a name="registry-sync-oauth"></a>

当 MCP 服务器受到 OAuth 保护时，您需要在授权服务器上创建 M2M 客户端，然后[从 Ident AgentCore ity 中配置一个包含客户端 ID 和密钥许可名单的凭证提供商](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/resource-providers.html)，以调用 MCP 服务器。获得凭据提供商后，可以将其提供给注册表进行同步：

### 控制台
<a name="registry-sync-oauth-console"></a>

1. 打开注册表详情页面。

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

1. 选择**从端点同步**。

1. 在**记录详细信息**下，选择 **MCP** 作为记录类型。

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

1. 在 “**凭据类型**” 下，选择 **OAuth**。

1. 对于**凭证提供者**，请从 “身份” 中选择或输入凭证提供者 ARN。 AgentCore 

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

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

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

1. 选择**创建记录**。

   该记录的创建状态为 “正在创建”。注册表使用 OAuth 凭据连接到端点，提取服务器和工具定义，并填充记录的描述符。同步完成后，记录将转换为 “草稿”。如果同步失败，则记录将转换为 CREATE\_FAILED 状态，错误详细信息显示在 “状态原因” 字段中。有关疑难解答，请参阅[记录同步错误](registry-troubleshooting.md#registry-troubleshooting-sync-errors)。

### AWS CLI
<a name="registry-sync-oauth-cli"></a>

```
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/*"
            ]
        }
    ]
}
```

限制：
+  CreateRegistryRecord 或的调用者 UpdateRegistryRecord 必须拥有与 GetWorkloadAccessToken 注册表关联的工作负载身份和凭据提供者的 GetResourceOauth2Token 权限。
+ 凭证提供者必须来自同一个账户。

## 从 IAM-protected MCP 服务器进行同步
<a name="registry-sync-iam"></a>

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

除了 IAM 角色外，您还必须为 Sigv4 签名指定`service`字段。如果您的 MCP 在 R AgentCore untime 或 AgentCore Gateway 上运行，则该值应`bedrock-agentcore`为。如果您的 MCP 在 API 网关上运行，则应该`execute-api`如此；如果您的 MCP 在 lambda 上运行，则应该如此。`lambda`

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

### 控制台
<a name="registry-sync-iam-console"></a>

1. 打开注册表详情页面。

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

1. 选择**从端点同步**。

1. 在**记录详细信息**下，选择 **MCP** 作为记录类型。

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

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

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

1. 对于**服务**，输入 Sigv4 签名的服务名称（例如、`bedrock-agentcore``execute-api`、`lambda`）。

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

1. 选择**创建记录**。

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

### AWS CLI
<a name="registry-sync-iam-cli"></a>

```
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 代理卡进行同步
<a name="registry-sync-a2a"></a>

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

### 控制台
<a name="registry-sync-a2a-console"></a>

1. 打开注册表详情页面。

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

1. 选择**从端点同步**。

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

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

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

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

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

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

1. 选择**创建记录**。

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

### AWS CLI
<a name="registry-sync-a2a-cli"></a>

```
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\"
                }
            }
        }]
    }
  }"
```

## 触发现有记录的同步
<a name="registry-sync-trigger"></a>

### 控制台
<a name="registry-sync-trigger-console"></a>

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

1. 在标题操作中选择 “**同步**” 按钮。

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

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

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

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

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

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

1. 选择**保存更改**。

### AWS CLI
<a name="registry-sync-trigger-cli"></a>

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

### AWS SDK
<a name="registry-sync-trigger-sdk"></a>

```
import boto3

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

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

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

 **疑难解答**：请参阅[记录同步错误](registry-troubleshooting.md#registry-troubleshooting-sync-errors)。