Synchroniser les enregistrements provenant de sources externes

Présentation de

AWS Le registre des agents peut synchroniser automatiquement les métadonnées des enregistrements provenant de sources externes en se connectant à l'URL fournie avec les informations d'identification sortantes. Lorsque vous fournissez une URL et un fournisseur d'informations d'identification (facultatif pour les ressources publiques qui ne nécessitent aucune autorisation d'accès), le système extrait les définitions du serveur et de l'outil et remplit les descripteurs de l'enregistrement conformément aux schémas de protocole officiels. Il met également à jour le nom, la description et la version de l'enregistrement si ces valeurs se trouvent à la source.

Synchronisation à partir d'un serveur MCP public

Pour les serveurs MCP publics qui ne nécessitent ni authentification ni autorisation :

Console

AWS INTERFACE DE LIGNE DE COMMANDE (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 Kit 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

L'enregistrement est créé dans le statut CREATING. Le temps de synchronisation varie de quelques secondes à quelques minutes, en fonction de la taille des métadonnées. Une fois la synchronisation terminée, il passe au format DRAFT avec les descripteurs extraits du serveur MCP, y compris les définitions du serveur et des outils.

Synchronisation à partir d'un OAuth-protected serveur MCP

Lorsque le serveur MCP est protégé par OAuth, vous devez créer un client M2M sur le serveur d'autorisation, puis configurer un fournisseur d'informations d'identification à partir d' AgentCore Identity contenant l'identifiant du client et la liste secrète autorisée pour appeler le serveur MCP. Une fois que vous avez le fournisseur d'informations d'identification, vous pouvez le fournir au registre pour la synchronisation :

Console

AWS INTERFACE DE LIGNE DE COMMANDE (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

Autorisations IAM supplémentaires requises :

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

Limites:

Synchronisation à partir d'un IAM-protected serveur MCP

Pour les serveurs MCP sur AgentCore Runtime ou AgentCore Gateway, spécifiez un rôle IAM pour la signature Sigv4. Le rôle doit être autorisé à accéder au service cible. Par exemple : bedrock-agentcore:InvokeAgentRuntime ou bedrock-agentcore:InvokeAgentRuntimeForUser sur AgentCore Runtime ; bedrock-agentcore:InvokeGateway sur AgentCore Gateway.

Outre le rôle IAM, vous devez spécifier un service champ pour la signature SigV4. Si votre MCP s'exécute sur AgentCore Runtime ou AgentCore Gateway, la valeur doit êtrebedrock-agentcore. Si votre MCP s'exécute sur une passerelle API, il devrait l'êtreexecute-api, et s'il fonctionne sur Lambda, il devrait l'être. lambda

regionla valeur est facultative. Par défaut, la demande sera signée avec la même région que le registre.

Console

AWS INTERFACE DE LIGNE DE COMMANDE (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

Autorisations IAM supplémentaires requises :

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

Synchronisation à partir d'une carte d'agent A2A

Indiquez l'URL de la carte d'agent ou l'URL de base de l'agent où .well-known/agent-card.json vous pouvez le découvrir :

Console

AWS INTERFACE DE LIGNE DE COMMANDE (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

Vous pouvez également spécifier des fournisseurs d'informations d'identification pour la synchronisation A2A. Par exemple, vous pouvez effectuer la synchronisation à partir d'un agent hébergé sur : 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\"
                }
            }
        }]
    }
  }"

Déclencher la synchronisation sur un enregistrement existant

Console

L'enregistrement passe au statut MISE À JOUR lors de la synchronisation. Une fois terminé, il revient à DRAFT avec les descripteurs mis à jour à partir de la source. Si la synchronisation échoue, l'enregistrement passe au statut UPDATE_FAILED avec les détails de l'erreur disponibles dans le champ Motif du statut. Pour résoudre les problèmes, consultez la section Enregistrer les erreurs de synchronisation.

Vous pouvez également déclencher la synchronisation lors de l'édition :

AWS INTERFACE DE LIGNE DE COMMANDE (CLI)

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

AWS Kit 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']}")

Résolution des problèmes : voir Erreurs de synchronisation des enregistrements.