View a markdown version of this page

Sincronizar registros de fontes externas - Base da Amazônia AgentCore

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Sincronizar registros de fontes externas

A migração já está aberta

AWS O Agent Registry foi lançado com o novo agent-registry namespace. O suporte para o bedrock-agentcore namespace de visualização pública será descontinuado em 17 de setembro de 2026. Para obter instruções de migração, consulte Guia abrangente de migração de registro.

Visão geral do

AWS O Agent Registry pode sincronizar automaticamente os metadados do registro de fontes externas conectando-se ao URL fornecido com credenciais de saída. Quando você fornece um provedor de URL e credenciais (opcional para recursos públicos que não exigem autorização de acesso), o sistema extrai as definições do servidor e da ferramenta e preenche os descritores do registro em conformidade com os esquemas de protocolo oficiais. Ele também atualiza o nome, a descrição e a versão do registro se esses valores forem encontrados na origem.

Sincronizar a partir de um servidor MCP público

Para servidores MCP públicos que não exigem autenticação ou autorização:

Console

exemplo
AWS Agent Registry namespace
  1. Abra a página de detalhes do registro no console do AWS Agent Registry.

  2. Na seção Registros do registro, escolha Criar registro.

  3. Escolha Sincronizar do endpoint.

  4. Em Detalhes do registro, em Tipo, escolha MCP. O descritor está definido como servidor MCP.

  5. Para Endpoint, insira a URL pública do servidor MCP (por exemplo,https://knowledge-mcp.global.api.aws). Deve ser um URL HTTPS válido.

  6. Em Tipo de credencial, escolha Nenhum.

  7. (Opcional) Na seção Tags, escolha Adicionar nova tag para anexar uma ou mais tags ao registro. Cada tag tem uma chave e um valor opcional.

  8. Escolha Create record (Criar registro).

Amazon Bedrock AgentCore namespace (to be deprecated)
  1. Abra a página de detalhes do registro no Bedrock-AgentCore console.

  2. Na seção Registros do registro, escolha Criar registro.

  3. Escolha Sincronizar do endpoint.

  4. Em Detalhes do registro, escolha MCP como o tipo de registro.

  5. Para Endpoint, insira a URL pública do servidor MCP (por exemplo,https://knowledge-mcp.global.api.aws). Deve ser um URL HTTPS válido.

  6. Em Tipo de credencial, escolha Nenhum.

  7. Escolha Create record (Criar registro).

O registro é criado no status CREATING. O registro se conecta ao endpoint, extrai as definições do servidor e da ferramenta e preenche os descritores do registro. Após a conclusão da sincronização, o registro passa para DRAFT. Se a sincronização falhar, o registro passará para o status CREATE_FAILED com os detalhes do erro disponíveis no campo Motivo do status. Para solucionar problemas, consulte Erros de sincronização de registros.

AWS CLI

exemplo
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

exemplo
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
nota

No agent-registry namespace, a configuração de sincronização se move dentro de cada descritor como source (compatível apenas com descritores a2aAgentCard primários mcpServer e com suporte). Os synchronizationConfiguration campossynchronizationType/de nível superior não existem mais.

O registro é criado no status CREATING. O tempo de sincronização varia de segundos a minutos, dependendo do tamanho dos metadados. Após a conclusão da sincronização, ela faz a transição para DRAFT com descritores extraídos do servidor MCP, incluindo definições de servidor e ferramentas.

Sincronizar a partir de um servidor OAuth-protected MCP

Quando o servidor MCP estiver protegido pelo OAuth, você precisará criar um cliente M2M no servidor de autorização e, em seguida, configurar um provedor de credenciais a partir do AgentCore Identity contendo a ID do cliente e o segredo permitido na lista de permissões para invocar o servidor MCP. Depois de ter o provedor de credenciais, você pode fornecê-lo ao registro para sincronização:

Console

exemplo
AWS Agent Registry namespace
  1. Abra a página de detalhes do registro no console do AWS Agent Registry.

  2. Na seção Registros do registro, escolha Criar registro.

  3. Escolha Sincronizar do endpoint.

  4. Em Detalhes do registro, em Tipo, escolha MCP. O descritor está definido como servidor MCP.

  5. Em Endpoint, insira a URL do servidor OAuth-protected MCP. Deve ser um URL HTTPS válido.

  6. Em Tipo de credencial, escolha OAuth.

  7. Para Provedor de credenciais, selecione ou insira o ARN do provedor de credenciais em Identity. AgentCore

  8. (Opcional) Expanda Configuração adicional para configurar:

    1. Escopos — Escopos do OAuth a serem solicitados ao obter um token de acesso.

    2. Parâmetros personalizados — parâmetros adicionais de valor-chave para a solicitação do token OAuth.

  9. (Opcional) Na seção Tags, escolha Adicionar nova tag para anexar uma ou mais tags ao registro. Cada tag tem uma chave e um valor opcional.

  10. Escolha Create record (Criar registro).

Amazon Bedrock AgentCore namespace (to be deprecated)
  1. Abra a página de detalhes do registro no Bedrock-AgentCore console.

  2. Na seção Registros do registro, escolha Criar registro.

  3. Escolha Sincronizar do endpoint.

  4. Em Detalhes do registro, escolha MCP como o tipo de registro.

  5. Em Endpoint, insira a URL do servidor OAuth-protected MCP. Deve ser um URL HTTPS válido.

  6. Em Tipo de credencial, escolha OAuth.

  7. Para Provedor de credenciais, selecione ou insira o ARN do provedor de credenciais em Identity. AgentCore

  8. (Opcional) Expanda Configuração adicional para configurar:

    1. Escopos — Escopos do OAuth a serem solicitados ao obter um token de acesso.

    2. Parâmetros personalizados — parâmetros adicionais de valor-chave para a solicitação do token OAuth.

  9. Escolha Create record (Criar registro).

O registro é criado no status CREATING. O registro se conecta ao endpoint usando as credenciais do OAuth, extrai as definições do servidor e da ferramenta e preenche os descritores do registro. Após a conclusão da sincronização, o registro passa para DRAFT. Se a sincronização falhar, o registro passará para o status CREATE_FAILED com os detalhes do erro disponíveis no campo Motivo do status. Para solucionar problemas, consulte Erros de sincronização de registros.

AWS CLI

exemplo
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

Permissões adicionais do IAM são necessárias:

nota

Essas permissões do IAM relacionadas à sincronização autorizam a identidade da carga de trabalho e os recursos do provedor de credenciais OAuth gerenciados pela Identity. AgentCore Esses recursos permanecem intencionalmente sob o bedrock-agentcore namespace, portanto, essa política não muda.

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

Defina o escopo da GetResourceOauth2Token declaração para o ARN específico do provedor de credenciais OAuth cujo token de acesso essa função precisa. Evite curingas no segmento de provedores do ARN — padrões como token-vault/ ou token-vault/default/oauth2credentialprovider/ conceda acesso a cada provedor de credenciais OAuth na conta, o que pode permitir o acesso a credenciais entre equipes. Siga o princípio do menor privilégio ao nomear o provedor específico no Resource campo, por exemplo. arn:aws:bedrock-agentcore:<region>:<account>:token-vault/default/oauth2credentialprovider/<oauthProviderName>

Limitações:

  • O chamador CreateRegistryRecord ou UpdateRegistryRecord deve ter identidade de carga GetWorkloadAccessToken de trabalho associada ao registro e GetResourceOauth2Token permissão no provedor de credenciais.

  • O provedor de credenciais deve vir da mesma conta.

Sincronizar a partir de um servidor IAM-protected MCP

Para servidores MCP no Amazon Bedrock AgentCore Runtime ou no Amazon Bedrock AgentCore Gateway, especifique uma função do IAM para assinatura SigV4. A função deve ter permissão para acessar o serviço de destino. Por exemplo: bedrock-agentcore:InvokeAgentRuntime ou bedrock-agentcore:InvokeAgentRuntimeForUser no AgentCore Runtime; bedrock-agentcore:InvokeGateway no AgentCore Gateway.

Além da função do IAM, você deve especificar o service campo para assinatura SigV4. Se seu MCP for executado em AgentCore Runtime ou AgentCore Gateway, o valor deverá seragent-registry. Se seu MCP é executado no Amazon API Gateway, deveria serexecute-api, e se seu MCP é executado no AWS Lambda, deveria ser. lambda

regiono valor é opcional. Por padrão, a solicitação será assinada com a mesma região do registro.

Console

exemplo
AWS Agent Registry namespace
  1. Abra a página de detalhes do registro no console do AWS Agent Registry.

  2. Na seção Registros do registro, escolha Criar registro.

  3. Escolha Sincronizar do endpoint.

  4. Em Detalhes do registro, em Tipo, escolha MCP. O descritor está definido como servidor MCP.

  5. Em Endpoint, insira a URL do servidor IAM-protected MCP. Deve ser um URL HTTPS válido.

  6. Em Tipo de credencial, escolha IAM.

  7. Em Role ARN, insira o ARN da função IAM a ser assumido para assinatura SigV4.

  8. Em Serviço, insira o nome do serviço para assinatura SigV4 (por exemplo,, agent-registryexecute-api,lambda).

  9. (Opcional) Expanda Configuração adicional e escolha uma região para assinatura SigV4. Se não for especificado, a própria região do registro será usada.

  10. (Opcional) Na seção Tags, escolha Adicionar nova tag para anexar uma ou mais tags ao registro. Cada tag tem uma chave e um valor opcional.

  11. Escolha Create record (Criar registro).

Amazon Bedrock AgentCore namespace (to be deprecated)
  1. Abra a página de detalhes do registro no Bedrock-AgentCore console.

  2. Na seção Registros do registro, escolha Criar registro.

  3. Escolha Sincronizar do endpoint.

  4. Em Detalhes do registro, escolha MCP como o tipo de registro.

  5. Em Endpoint, insira a URL do servidor IAM-protected MCP. Deve ser um URL HTTPS válido.

  6. Em Tipo de credencial, escolha IAM.

  7. Em Role ARN, insira o ARN da função IAM a ser assumido para assinatura SigV4.

  8. Em Serviço, insira o nome do serviço para assinatura SigV4 (por exemplo,, bedrock-agentcoreexecute-api,lambda).

  9. (Opcional) Expanda Configuração adicional e escolha uma região para assinatura SigV4. Se não for especificado, a própria região do registro será usada.

  10. Escolha Create record (Criar registro).

O registro é criado no status CREATING. O registro se conecta ao endpoint usando credenciais do IAM, extrai as definições do servidor e da ferramenta e preenche os descritores do registro. Após a conclusão da sincronização, o registro passa para DRAFT. Se a sincronização falhar, o registro passará para o status CREATE_FAILED com os detalhes do erro disponíveis no campo Motivo do status. Para solucionar problemas, consulte Erros de sincronização de registros.

AWS CLI

exemplo
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

Permissões adicionais do IAM são necessárias:

nota

Essa iam:PassRole política autoriza o registro a transferir uma função à AgentCore Identity para sincronização externa. O valor da iam:PassedToService condição bedrock-agentcore.amazonaws.com se refere ao principal do serviço de AgentCore identidade e não muda.

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

Sincronizar a partir de um cartão de agente A2A

Forneça o URL do cartão do agente ou o URL base do agente, onde .well-known/agent-card.json pode ser descoberto:

Console

exemplo
AWS Agent Registry namespace
  1. Abra a página de detalhes do registro no console do AWS Agent Registry.

  2. Na seção Registros do registro, escolha Criar registro.

  3. Escolha Sincronizar do endpoint.

  4. Em Detalhes do registro, em Tipo, escolha Agente. O descritor está definido como A2A Agent Card.

  5. Em Endpoint, insira a URL do cartão do agente (por exemplo,https://agent.example.com/.well-known/agent-card.json). Deve ser um URL HTTPS válido.

  6. Em Tipo de credencial, escolha o método de autorização apropriado:

    1. Nenhum — Para cartões de agente acessíveis ao público.

    2. IAM — Para agentes hospedados no AgentCore Runtime ou no Gateway. Forneça o ARN da função e o nome do serviço.

    3. OAuth — Para OAuth-protected agentes. Selecione ou insira o ARN do provedor de credenciais.

  7. (Opcional) Na seção Tags, escolha Adicionar nova tag para anexar uma ou mais tags ao registro. Cada tag tem uma chave e um valor opcional.

  8. Escolha Create record (Criar registro).

Amazon Bedrock AgentCore namespace (to be deprecated)
  1. Abra a página de detalhes do registro no Bedrock-AgentCore console.

  2. Na seção Registros do registro, escolha Criar registro.

  3. Escolha Sincronizar do endpoint.

  4. Em Detalhes do registro, escolha Agente como o tipo de registro.

  5. Em Endpoint, insira a URL do cartão do agente (por exemplo,https://agent.example.com/.well-known/agent-card.json). Deve ser um URL HTTPS válido.

  6. Em Tipo de credencial, escolha o método de autorização apropriado:

    1. Nenhum — Para cartões de agente acessíveis ao público.

    2. IAM — Para agentes hospedados no AgentCore Runtime ou no Gateway. Forneça o ARN da função e o nome do serviço.

    3. OAuth — Para OAuth-protected agentes. Selecione ou insira o ARN do provedor de credenciais.

  7. Escolha Create record (Criar registro).

O registro é criado no status CREATING. O registro se conecta ao endpoint, extrai os metadados do cartão do agente e preenche os descritores do registro. Após a conclusão da sincronização, o registro passa para DRAFT. Se a sincronização falhar, o registro passará para o status CREATE_FAILED com os detalhes do erro disponíveis no campo Motivo do status. Para solucionar problemas, consulte Erros de sincronização de registros.

AWS CLI

exemplo
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

Você também pode especificar provedores de credenciais para sincronização A2A, por exemplo, você pode sincronizar a partir de um agente hospedado em. AgentCore Use agent-registry como service campo quando o destino de sincronização for um agente hospedado no AgentCore Runtime ou no Gateway.

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

Acione a sincronização em um registro existente

Console

  1. Abra a página de detalhes do registro de um registro de MCP ou Agente que tenha a sincronização configurada.

exemplo
AWS Agent Registry namespace
  1. Na página de detalhes do registro no console do AWS Agent Registry, escolha Gerenciar e, em seguida, escolha Sincronização.

  2. Na caixa de diálogo de confirmação, revise a mensagem de que a sincronização reverterá o registro para o estado de rascunho.

  3. Escolha Sincronizar para confirmar.

Como alternativa, você pode acionar a sincronização durante a edição:

  1. Na página de detalhes do registro, escolha Gerenciar e, em seguida, escolha Editar.

  2. Em Sincronizar do endpoint, marque a caixa de seleção Re-sync do endpoint.

  3. Escolha Salvar alterações.

Amazon Bedrock AgentCore namespace (to be deprecated)
  1. Na página de detalhes do registro no Bedrock-AgentCore console, escolha o botão Sincronizar nas ações do cabeçalho.

  2. Na caixa de diálogo de confirmação, revise a mensagem de que a sincronização reverterá o registro para o estado de rascunho.

  3. Escolha Sincronizar para confirmar.

Como alternativa, você pode acionar a sincronização durante a edição:

  1. Na página de detalhes do registro, escolha o menu de três pontos () e escolha Editar.

  2. Em Sincronizar do endpoint, marque a caixa de seleção Re-sync do endpoint.

  3. Escolha Salvar alterações.

O registro passa para o status UPDATING durante a sincronização. Após a conclusão, ele retorna ao DRAFT com os descritores atualizados da fonte. Se a sincronização falhar, o registro passará para o status UPDATE_FAILED com os detalhes do erro disponíveis no campo Motivo do status. Para solucionar problemas, consulte Erros de sincronização de registros.

AWS CLI

exemplo
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

exemplo
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']}")
nota

Se o registro estiver em um status de Não rascunho (por exemplo, APROVADO), a atualização criará uma nova revisão de RASCUNHO. A revisão aprovada permanece detectável.

Solução de problemas: consulte Erros de sincronização de registros.