View a markdown version of this page

Sincronizar registros de fontes externas - Amazon Bedrock AgentCore
Visão geral doSincronizar a partir de um servidor MCP públicoSincronizar a partir de um servidor OAuth-protected MCPSincronizar a partir de um servidor IAM-protected MCPSincronizar a partir de um cartão de agente A2AAcione a sincronização em um registro existente

Sincronizar registros de fontes externas

Próxima migração de namespace

AWS O Agent Registry está atualmente em versão prévia pública sob o namespace bedrock-agentcore. A partir de 6 de agosto de 2026, o serviço passa para o namespace de registro do agente. Se você usa o AWS Agent Registry, deve atualizar seus endpoints, políticas do IAM, clientes SDK, scripts de CLI e dados de registro. Para obter mais informações sobre a migração da versão prévia pública, consulte o guia abrangente de migração do 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 credencial (opcional para recursos públicos que não exigem nenhuma autorização de acesso), o sistema extrai as definições do servidor e da ferramenta e preenche os descritores do registro de acordo com os esquemas oficiais do protocolo. Ele também atualiza o nome, a descrição e a versão do registro se esses valores forem encontrados na fonte.

Sincronizar a partir de um servidor MCP público

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

Console

  1. Abra a página de detalhes do registro.

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

  3. Escolha Sincronizar a partir do endpoint.

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

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

  6. Em Tipo de credencial, escolha Nenhuma.

  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

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

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

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 do AgentCore Identity contendo o ID do cliente e a lista secreta 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

  1. Abra a página de detalhes do registro.

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

  3. Escolha Sincronizar a partir do endpoint.

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

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

  6. Em Tipo de credencial, escolha OAuth.

  7. Em Provedor de credenciais, selecione ou insira o ARN do provedor de credenciais em Identidade. 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

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: 

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

Limitações:

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

  • O provedor da credencial deve ser proveniente da mesma conta.

Sincronizar a partir de um servidor IAM-protected MCP

Para servidores MCP no AgentCore Runtime ou no AgentCore Gateway, especifique uma função do IAM para a assinatura do 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á serbedrock-agentcore. Se seu MCP for executado no gateway de API, deveria serexecute-api, e se seu MCP for executado em lambda, deveria ser. lambda

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

Console

  1. Abra a página de detalhes do registro.

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

  3. Escolha Sincronizar a partir do endpoint.

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

  5. Para 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 do IAM a ser assumido para a assinatura SigV4.

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

  9. (Opcional) Expanda a configuração adicional e escolha uma região para a assinatura SigV4. Se não for especificada, 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

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: 

{
    "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

  1. Abra a página de detalhes do registro.

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

  3. Escolha Sincronizar a partir do endpoint.

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

  5. Para Endpoint, insira o 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

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

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 MCP ou Agente que tenha a sincronização configurada.

  2. Escolha o botão Sincronizar nas ações do cabeçalho.

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

  4. Escolha Sincronizar para confirmar.

O registro muda para o status ATUALIZANDO 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.

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 (customize) e, em seguida, escolha Editar.

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

  3. Escolha Salvar alterações.

AWS CLI

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

AWS 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']}")
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 pesquisável.

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