# Sincronizzazione dei record da fonti esterne
<a name="registry-sync-records"></a>

**Prossima migrazione del namespace**  
 AWS Agent Registry è attualmente disponibile in anteprima pubblica nel namespace bedrock-agentcore. A partire dal 6 agosto 2026, il servizio passerà allo spazio dei nomi agent-registry. Se utilizzi AWS Agent Registry, devi aggiornare gli endpoint, le policy IAM, i client SDK, gli script CLI e i dati del registro. [Per ulteriori informazioni sulla migrazione dall'anteprima pubblica, consulta la Guida completa alla migrazione del registro.](registry-faq.md)

## Panoramica di
<a name="registry-sync-overview"></a>

 AWS Agent Registry può sincronizzare automaticamente i metadati dei record da fonti esterne collegandosi all'URL fornito con credenziali in uscita. Quando fornite un provider di URL e credenziali (facoltativo per le risorse pubbliche che non richiedono alcuna autorizzazione per l'accesso), il sistema estrae le definizioni di server e strumenti e compila i descrittori del record in conformità agli schemi di protocollo ufficiali. Aggiorna inoltre il nome, la descrizione e la versione del record se tali valori vengono trovati all'origine.

## Sincronizzazione da un server MCP pubblico
<a name="registry-sync-public"></a>

Per i server MCP pubblici che non richiedono autenticazione o autorizzazione:

### Console
<a name="registry-sync-public-console"></a>

1. Apri la pagina dei dettagli del registro.

1. Nella sezione **Record del registro**, scegli **Crea record**.

1. Scegli **Sincronizza dall'endpoint**.

1. In **Dettagli del record**, scegli **MCP come tipo** di record.

1. Per **Endpoint**, inserite l'URL del server MCP pubblico (ad es.). `https://knowledge-mcp.global.api.aws` Deve essere un URL HTTPS valido.

1. In **Tipo di credenziale**, scegli **Nessuno**.

1. Scegli **Crea record**.

   Il record viene creato nello stato CREATING. Il registro si connette all'endpoint, estrae le definizioni dei server e degli strumenti e compila i descrittori del record. Al termine della sincronizzazione, il record passa a DRAFT. Se la sincronizzazione fallisce, il record passa allo stato CREATE\_FAILED con i dettagli dell'errore disponibili nel campo Status Reason. [Per la risoluzione dei problemi, vedere Errori di sincronizzazione dei record.](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
```

Il record viene creato nello stato CREATING. Il tempo di sincronizzazione varia da secondi a minuti, a seconda della dimensione dei metadati. Una volta completata la sincronizzazione, passa a DRAFT con i descrittori estratti dal server MCP, incluse le definizioni dei server e degli strumenti.

## Sincronizzazione da un server MCP OAuth-protected
<a name="registry-sync-oauth"></a>

Quando il server MCP è protetto da OAuth, è necessario creare un client M2M sul server di autorizzazione e quindi configurare un [provider di credenziali da AgentCore Identity](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/resource-providers.html) contenente l'ID client e il segreto consentito per richiamare il server MCP. Una volta ottenuto il provider di credenziali, è possibile fornirlo al registro per la sincronizzazione:

### Console
<a name="registry-sync-oauth-console"></a>

1. Apri la pagina dei dettagli del registro.

1. Nella sezione **Record del registro**, scegli **Crea record**.

1. Scegli **Sincronizza dall'endpoint**.

1. In **Dettagli del record**, scegli **MCP come tipo** di record.

1. Per **Endpoint**, inserite l'URL del server OAuth-protected MCP. Deve essere un URL HTTPS valido.

1. In **Tipo di credenziale**, scegli **OAuth**.

1. Per Provider di **credenziali, selezionare o immettere l'ARN del provider** di credenziali da Identity. AgentCore 

1. (Facoltativo) Espandi **Configurazione aggiuntiva per configurare**:

   1.  **Ambiti: ambiti** OAuth da richiedere quando si ottiene un token di accesso.

   1.  **Parametri personalizzati: parametri** chiave-valore aggiuntivi per la richiesta del token OAuth.

1. Scegli **Crea record**.

   Il record viene creato nello stato CREATING. Il registro si connette all'endpoint utilizzando le credenziali OAuth, estrae le definizioni del server e dello strumento e compila i descrittori del record. Al termine della sincronizzazione, il record passa a DRAFT. Se la sincronizzazione fallisce, il record passa allo stato CREATE\_FAILED con i dettagli dell'errore disponibili nel campo Status Reason. [Per la risoluzione dei problemi, vedere Errori di sincronizzazione dei record.](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
```

 **Sono necessarie autorizzazioni IAM aggiuntive:** 

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

Restrizioni:
+ Il chiamante CreateRegistryRecord o UpdateRegistryRecord deve disporre dell'identità del carico di lavoro GetWorkloadAccessToken associata al registro e dell' GetResourceOauth2Token autorizzazione sul fornitore delle credenziali.
+ Il fornitore di credenziali deve provenire dallo stesso account.

## Sincronizzazione da un server MCP IAM-protected
<a name="registry-sync-iam"></a>

Per i server MCP su AgentCore Runtime o AgentCore Gateway, specifica un ruolo IAM per la firma SigV4. Il ruolo deve disporre dell'autorizzazione per accedere al servizio di destinazione. Ad esempio: `bedrock-agentcore:InvokeAgentRuntime` o `bedrock-agentcore:InvokeAgentRuntimeForUser` su AgentCore Runtime; `bedrock-agentcore:InvokeGateway` su AgentCore Gateway.

Oltre al ruolo IAM, è necessario specificare il `service` campo per la firma SigV4. Se l'MCP viene eseguito su AgentCore Runtime o AgentCore Gateway, il valore dovrebbe essere. `bedrock-agentcore` Se l'MCP funziona su API gateway, dovrebbe esserlo`execute-api`, mentre se l'MCP funziona su lambda, dovrebbe esserlo. `lambda`

 `region`il valore è facoltativo. Per impostazione predefinita, la richiesta verrà firmata con la stessa regione del registro.

### Console
<a name="registry-sync-iam-console"></a>

1. Apri la pagina dei dettagli del registro.

1. Nella sezione **Record del registro**, scegli **Crea record**.

1. Scegli **Sincronizza dall'endpoint**.

1. In **Dettagli del record**, scegli **MCP come tipo** di record.

1. Per **Endpoint**, inserite l'URL del server IAM-protected MCP. Deve essere un URL HTTPS valido.

1. In **Tipo di credenziale**, scegli **IAM**.

1. Per **Role ARN, inserisci il ruolo** IAM ARN da assumere per la firma SigV4.

1. Per **Service**, inserisci il nome del servizio per la firma SigV4 (ad esempio,,,). `bedrock-agentcore` `execute-api` `lambda`

1. (Facoltativo) Espandi la **configurazione aggiuntiva** e scegli una **regione** per la firma SigV4. Se non specificato, viene utilizzata la regione del registro.

1. Scegli **Crea record**.

   Il record viene creato nello stato CREATING. Il registro si connette all'endpoint utilizzando le credenziali IAM, estrae le definizioni dei server e degli strumenti e compila i descrittori del record. Al termine della sincronizzazione, il record passa a DRAFT. Se la sincronizzazione fallisce, il record passa allo stato CREATE\_FAILED con i dettagli dell'errore disponibili nel campo Status Reason. [Per la risoluzione dei problemi, vedere Errori di sincronizzazione dei record.](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
```

 **Sono necessarie autorizzazioni IAM aggiuntive:** 

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

## Sincronizzazione da una scheda agente A2A
<a name="registry-sync-a2a"></a>

Fornisci l'URL della carta dell'agente o l'URL di base dell'agente dove `.well-known/agent-card.json` puoi trovare:

### Console
<a name="registry-sync-a2a-console"></a>

1. Apri la pagina dei dettagli del registro.

1. Nella sezione **Record del registro**, scegli **Crea record**.

1. Scegli **Sincronizza dall'endpoint**.

1. In **Dettagli del record**, scegli **Agente** come tipo di record.

1. Per **Endpoint**, inserisci l'URL della scheda dell'agente (ad esempio,`https://agent.example.com/.well-known/agent-card.json`). Deve essere un URL HTTPS valido.

1. In **Tipo di credenziale**, scegli il metodo di autorizzazione appropriato:

   1.  **Nessuna**: per le carte di agente accessibili al pubblico.

   1.  **IAM**: per agenti ospitati su AgentCore Runtime o Gateway. Fornire l'**ARN del ruolo** e il nome del **servizio**.

   1.  **OAuth**: per gli agenti. OAuth-protected Seleziona o inserisci l'ARN del **provider di credenziali**.

1. Scegli **Crea record**.

   Il record viene creato nello stato CREATING. Il registro si connette all'endpoint, estrae i metadati della scheda agente e compila i descrittori del record. Al termine della sincronizzazione, il record passa a DRAFT. Se la sincronizzazione fallisce, il record passa allo stato CREATE\_FAILED con i dettagli dell'errore disponibili nel campo Status Reason. [Per la risoluzione dei problemi, vedere Errori di sincronizzazione dei record.](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
```

Puoi anche specificare i fornitori di credenziali per la sincronizzazione A2A, ad esempio puoi eseguire la sincronizzazione da un agente ospitato su: 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\"
                }
            }
        }]
    }
  }"
```

## Attiva la sincronizzazione su un record esistente
<a name="registry-sync-trigger"></a>

### Console
<a name="registry-sync-trigger-console"></a>

1. Aprire la pagina dei dettagli del record per un record MCP o Agent con la sincronizzazione configurata.

1. Scegli il pulsante **Sincronizza** nelle azioni dell'intestazione.

1. Nella finestra di dialogo di conferma, esamina il messaggio secondo cui la sincronizzazione ripristinerà lo stato di bozza del record.

1. Scegli **Sincronizza** per confermare.

Il record passa allo stato UPDATING durante la sincronizzazione. Dopo il completamento, torna a DRAFT con i descrittori aggiornati dalla fonte. Se la sincronizzazione fallisce, il record passa allo stato UPDATE\_FAILED con i dettagli dell'errore disponibili nel campo Status Reason. [Per la risoluzione dei problemi, vedere Errori di sincronizzazione dei record.](registry-troubleshooting.md#registry-troubleshooting-sync-errors)

In alternativa, puoi attivare la sincronizzazione durante la modifica:

1. **Dalla pagina dei dettagli del record, scegli il menu a tre punti (⋮), quindi scegli Modifica.**

1. In **Sincronizza dall'endpoint**, seleziona la casella di controllo **Re-sync dall'**endpoint.

1. Scegli **Save changes** (Salva modifiche).

### 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']}")
```

**Nota**  
Se lo stato del record non è Bozza (ad esempio, APPROVATO), l'aggiornamento crea una nuova revisione BOZZA. La revisione approvata rimane ricercabile.

 **Risoluzione dei problemi**: vedi Errori di [sincronizzazione dei record](registry-troubleshooting.md#registry-troubleshooting-sync-errors).