User's blog

Como adicionar busca web segura ao Claude Desktop com o Amazon Bedrock AgentCore

Written by

Make.com Service User

in

O problema: modelos de IA têm data de corte de conhecimento

O Claude Desktop integrado ao Amazon Bedrock oferece uma experiência poderosa de assistência por IA — mas há uma limitação importante: sem acesso à web, o modelo só consegue responder com base no conhecimento que tinha até a data de corte do seu treinamento. Isso significa que perguntas sobre documentações recentes, preços atualizados ou informações em tempo real ficam sem resposta adequada.

Para resolver esse problema, a AWS disponibilizou uma integração entre o Claude Desktop e o recurso de busca web do Amazon Bedrock AgentCore — uma plataforma para construir, conectar e otimizar agentes de IA em escala, compatível com qualquer framework ou modelo.

O que é o AgentCore Gateway e o Web Search

O AgentCore Gateway é uma capacidade do Amazon Bedrock AgentCore que funciona como ponto de entrada para ferramentas externas. Por meio dele, é possível conectar o Claude Desktop ao recurso de Web Search — uma funcionalidade gerenciada, compatível com o Protocolo de Contexto de Modelo (MCP, do inglês Model Context Protocol), que usa um índice web da Amazon com dezenas de bilhões de documentos.

Um ponto importante para equipes de segurança: todo o tráfego de consultas permanece dentro da infraestrutura AWS. Não há chaves de API externas para gerenciar e nenhuma consulta sai do seu perímetro. Com o Claude Desktop, é possível usar servidores MCP gerenciados para se conectar ao AgentCore Gateway com o alvo de busca web habilitado.

Arquitetura de autenticação

A solução usa uma cadeia de autenticação totalmente dentro da AWS. O fluxo funciona assim:

Essa abordagem se alinha à governança de identidade já existente nas organizações que usam AWS. Não são necessárias credenciais separadas nem provedores de identidade de terceiros.

Pré-requisitos

Para seguir o passo a passo descrito pela AWS, são necessários:

  • Uma conta AWS com permissões para criar funções do Gerenciamento de Identidade e Acesso AWS (IAM) e recursos do Amazon Bedrock AgentCore.
  • Acesso de administrador à conta de gerenciamento no AWS Organizations (para configuração do IAM Identity Center).
  • AWS IAM Identity Center pré-configurado para acesso SSO às contas AWS.
  • Claude Desktop configurado com o Amazon Bedrock como provedor de inferência.
  • Interface de Linha de Comando AWS (AWS CLI) v2 instalada e configurada.
  • Python 3.10 ou superior.
  • SDK Boto3 atualizado para a versão mais recente.

O Web Search no Amazon Bedrock AgentCore está disponível atualmente nas regiões Leste dos EUA (Norte da Virgínia) — us-east-1, Europa (Irlanda) — eu-west-1, e Pacífico Asiático (Tóquio) — ap-northeast-1.

Configuração passo a passo

Passo 1: Criar um pool de usuários no Amazon Cognito

O primeiro passo é criar um pool de usuários no Amazon Cognito na conta AWS alvo. Ele funcionará como emissor de tokens OpenID Connect (OIDC) para o AgentCore Gateway.

export AWS_REGION=<your-region>

# Create User Pool
aws cognito-idp create-user-pool \
  --pool-name "agentcore-websearch-pool" \
  --region $AWS_REGION \
  --auto-verified-attributes email \
  --schema '[{"Name":"email","Required":true,"Mutable":true,"AttributeDataType":"String"}]' \
  --username-attributes email \
  --username-configuration "CaseSensitive=false" \
  --mfa-configuration "OFF"

# Note the Pool ID
export USER_POOL_ID=$(aws cognito-idp list-user-pools --max-results 10 \
  --region $AWS_REGION \
  --query "UserPools[?Name=='agentcore-websearch-pool'].Id" --output text)
echo "User Pool ID: $USER_POOL_ID"

# Create a domain (must be globally unique)
aws cognito-idp create-user-pool-domain \
  --domain "<your-unique-prefix>" \
  --user-pool-id $USER_POOL_ID \
  --region $AWS_REGION

Guarde os seguintes valores para os próximos passos:

  • ID do Pool de Usuários: $USER_POOL_ID
  • Domínio: <your-unique-prefix>.auth.<region>.amazoncognito.com
  • Audience: urn:amazon:cognito:sp:<user-pool-id>
  • URL ACS: https://<your-unique-prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse

Passo 2: Configurar aplicação SAML no IAM Identity Center

Na conta de gerenciamento do AWS Organizations, crie uma aplicação SAML que federe com o Cognito. No console do IAM Identity Center, acesse Aplicações, escolha Adicionar aplicação, selecione SAML 2.0 e preencha os detalhes:

  • Nome de exibição: AgentCore Web Search
  • URL ACS: https://<your-unique-prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse
  • Audience: urn:amazon:cognito:sp:<user-pool-id>

Faça o download do arquivo XML de metadados SAML. Após criar a aplicação, edite os mapeamentos de atributos inserindo os valores Subject (formato Persistente) e Email (formato Básico). Em seguida, atribua os usuários ou grupos que terão acesso ao Web Search.

Passo 3: Registrar o provedor de identidade SAML no Cognito

De volta à conta alvo, registre o IAM Identity Center como provedor de identidade SAML no pool de usuários do Cognito:

# Add IAM Identity Center as SAML IdP
METADATA=$(cat /path/to/downloaded-metadata.xml)
aws cognito-idp create-identity-provider \
  --user-pool-id $USER_POOL_ID \
  --provider-name "IAMIdentityCenterIdP" \
  --provider-type SAML \
  --provider-details "{\"MetadataFile\": $(echo "$METADATA" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))')}" \
  --attribute-mapping '{"email": "email"}' \
  --region $AWS_REGION

Passo 4: Criar cliente de aplicação Cognito para o AgentCore

Crie um cliente de aplicação com segredo de cliente. O Claude Desktop usará esse cliente para iniciar o fluxo OAuth, autenticar o usuário via IAM Identity Center e obter um JWT para o AgentCore Gateway:

aws cognito-idp create-user-pool-client \
  --user-pool-id $USER_POOL_ID \
  --client-name "agentcore-websearch-client" \
  --generate-secret \
  --supported-identity-providers "IAMIdentityCenterIdP" \
  --callback-urls '["http://localhost:53280/callback"]' \
  --allowed-o-auth-flows code \
  --allowed-o-auth-scopes "openid" "email" "profile" \
  --allowed-o-auth-flows-user-pool-client \
  --region $AWS_REGION

Anote o Client ID e o Client Secret gerados na saída do comando.

Passo 5: Configurar o AgentCore Gateway com a ferramenta Web Search

Neste passo, cria-se um novo AgentCore Gateway com o Tipo de Autenticação de Entrada configurado como Token Web JSON (JWT), usando o ID do pool de usuários e o ID do cliente de aplicação do Cognito criados anteriormente. Execute o script Python abaixo, substituindo todos os valores de exemplo pelos dados reais do seu ambiente:

import boto3
import json
import time

session = boto3.Session(region_name="your-region")
iam_client = session.client("iam")
gateway_client = session.client("bedrock-agentcore-control")

ACCOUNT_ID = "your-target-aws-account-id"
ROLE_NAME = "websearch-gateway-role"
GATEWAY_NAME = "websearch-gateway"
COGNITO_DISCOVERY_URL = "https://cognito-idp.<your-region>.amazonaws.com/<user-pool-id>/.well-known/openid-configuration"
COGNITO_CLIENT_ID = "<cognito-application-client-id>"

# --- Step 1: Create IAM execution role ---
trust_policy = {
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": {"Service": "bedrock-agentcore.amazonaws.com"},
        "Action": "sts:AssumeRole",
        "Condition": {
            "StringEquals": {"aws:SourceAccount": ACCOUNT_ID}
        }
    }]
}

permissions_policy = {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "GetGateway",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:GetGateway",
            "Resource": f"arn:aws:bedrock-agentcore:us-east-1:{ACCOUNT_ID}:gateway/*"
        },
        {
            "Sid": "GetConfigBundle",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:GetConfigurationBundleVersion",
            "Resource": f"arn:aws:bedrock-agentcore:us-east-1:{ACCOUNT_ID}:configuration-bundle/*"
        },
        {
            "Sid": "InvokeWebSearch",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:InvokeWebSearch",
            "Resource": "arn:aws:bedrock-agentcore:us-east-1:aws:tool/web-search.v1"
        }
    ]
}

try:
    iam_client.create_role(
        RoleName=ROLE_NAME,
        AssumeRolePolicyDocument=json.dumps(trust_policy),
        Description="Execution role for web search AgentCore gateway",
    )
    print(f"✓ Role '{ROLE_NAME}' created.")
except iam_client.exceptions.EntityAlreadyExistsException:
    print(f"✓ Role '{ROLE_NAME}' already exists, reusing.")

iam_client.put_role_policy(
    RoleName=ROLE_NAME,
    PolicyName="websearch-gateway-policy",
    PolicyDocument=json.dumps(permissions_policy),
)
print(f"✓ Inline policy attached to '{ROLE_NAME}'.")

# --- Step 2: Create the gateway ---
response = gateway_client.create_gateway(
    name=GATEWAY_NAME,
    description="AgentCore gateway with managed Web Search connector",
    roleArn=f"arn:aws:iam::{ACCOUNT_ID}:role/{ROLE_NAME}",
    protocolType="MCP",
    protocolConfiguration={
        "mcp": {
            "supportedVersions": ["2025-03-26"],
        }
    },
    authorizerType="CUSTOM_JWT",
    authorizerConfiguration={
        "customJWTAuthorizer": {
            "discoveryUrl": COGNITO_DISCOVERY_URL,
            "allowedClients": [COGNITO_CLIENT_ID],
        }
    },
)

gateway_id = response["gatewayId"]
gateway_url = response.get("gatewayUrl")
print(f"✓ Gateway created: {gateway_id}")
print(f"  URL: {gateway_url}")

# --- Step 3: Wait for gateway to become READY ---
print(" Waiting for gateway to reach READY status...", end="", flush=True)
for i in range(40):  # up to ~10 minutes
    resp = gateway_client.get_gateway(gatewayIdentifier=gateway_id)
    status = resp.get("status")
    if status == "READY":
        print(f" READY (after {(i+1)*15}s)")
        break
    elif status == "FAILED":
        print(f"\n✗ Gateway entered FAILED status.")
        reasons = resp.get("statusReasons", [])
        for r in reasons:
            print(f"  Reason: {r}")
        exit(1)
    print(".", end="", flush=True)
    time.sleep(15)
else:
    print(f"\n✗ Gateway did not reach READY within 10 minutes (last status: {status})")
    exit(1)

# --- Step 4: Attach the managed Web Search connector target ---
gateway_client.create_gateway_target(
    gatewayIdentifier=gateway_id,
    name="web-search-tool",
    description="Managed Web Search connector",
    targetConfiguration={
        "mcp": {
            "connector": {
                "source": {"connectorId": "web-search"},
                "configurations": [{"name": "WebSearch", "parameterValues": {}}],
            }
        }
    },
    credentialProviderConfigurations=[
        {"credentialProviderType": "GATEWAY_IAM_ROLE"}
    ],
)
print("✓ Web search target attached.")

print()
print("=" * 60)
print(f"  Gateway ID:  {gateway_id}")
print(f"  Gateway URL: {gateway_url}")
print(f"  Auth:        CUSTOM_JWT (Cognito)")
print(f"  Target:      web-search (managed connector)")
print("=" * 60)

Ao final, o AgentCore Gateway estará criado com a ferramenta Web Search e autorização de entrada baseada em JWT.

Passo 6: Configurar o Claude Desktop

Com o gateway pronto, o próximo passo é conectar o Claude Desktop a ele. Acesse a janela de configuração do Claude Desktop com Amazon Bedrock, vá até Conectores e Extensões, escolha Adicionar servidor e selecione Em branco. Preencha os seguintes campos:

  • Nome: websearchtool
  • Transporte: Streamable HTTP
  • URL: URL do recurso do AgentCore Gateway criado no Passo 5
  • OAuth: Traga seu próprio cliente
  • Client ID: ID do cliente de aplicação criado no Passo 4
  • Client Secret: Segredo do cliente criado no Passo 4
  • Servidor de Autorização: ["https://<your-unique-prefix>.auth.<region>.amazoncognito.com/oauth2/authorize"]
  • Scope: openid
  • Callback host: localhost
  • Callback port: 53280

Ao finalizar e clicar em Entrar e testar, um navegador será aberto redirecionando para a tela de login do AWS IAM Identity Center SSO. Após autenticação bem-sucedida, uma mensagem confirmará que a autorização foi concluída. De volta ao Claude Desktop, uma mensagem de registro MCP bem-sucedido será exibida.

Imagem original — fonte: Aws

A partir desse ponto, o Claude Desktop descobrirá a ferramenta WebSearchTool por meio da chamada tools/list do MCP e a invocará automaticamente sempre que precisar de informações atuais da web.

Teste e validação

Para validar a integração, basta enviar uma consulta que exija informações recentes. O Claude Desktop apresentará uma caixa de aprovação de execução da ferramenta, indicando que a ferramenta Web Search foi descoberta com sucesso. O diálogo mostra a consulta que o Claude pretende executar e oferece três opções: Negar, Permitir para esta tarefa ou Permitir uma vez. Após aprovação, os resultados da busca web são incluídos na resposta.

Limpeza dos recursos

Caso tenha seguido o passo a passo apenas para testes, a AWS recomenda excluir os recursos criados para evitar cobranças desnecessárias:

# Delete the gateway target
aws bedrock-agentcore-control delete-gateway-target --gateway-identifier <gateway-id> --target-id <target-id> --region $AWS_REGION

# Delete the gateway (only if it was created for this walkthrough)
aws bedrock-agentcore-control delete-gateway --gateway-identifier <gateway-id> --region $AWS_REGION

# Delete the IAM policy (only if it was created for this walkthrough)
aws iam delete-role-policy --role-name websearch-gateway-role --policy-name websearch-gateway-policy

# Delete the IAM role (only if it was created for this walkthrough)
aws iam delete-role --role-name websearch-gateway-role

# Delete the Cognito application client
aws cognito-idp delete-user-pool-client --user-pool-id $USER_POOL_ID --client-id <client-id> --region $AWS_REGION

# Delete the Cognito identity provider
aws cognito-idp delete-identity-provider --user-pool-id $USER_POOL_ID --provider-name IAMIdentityCenterIdP --region $AWS_REGION

# Delete the Cognito pool domain
aws cognito-idp delete-user-pool-domain --user-pool-id $USER_POOL_ID --domain <your-unique-prefix> --region $AWS_REGION

# Delete the cognito pool
aws cognito-idp delete-user-pool --user-pool-id $USER_POOL_ID --region $AWS_REGION

Por fim, no console do IAM Identity Center na conta de gerenciamento, exclua a aplicação SAML criada no Passo 2.

Conclusão

A integração entre o Web Search do AgentCore e o Claude Desktop resolve de forma elegante o problema da data de corte de conhecimento dos modelos de linguagem, sem introduzir dependências externas. Todo o fluxo de autenticação — do IAM Identity Center ao Cognito, até o JWT validado pelo gateway — permanece dentro da AWS.

Vale destacar que o padrão descrito não está limitado ao IAM Identity Center: qualquer provedor de identidade compatível com SAML ou OIDC pode ser configurado como fonte de federação no Amazon Cognito, tornando a solução adaptável a diferentes contextos corporativos.

Para configurações avançadas de gateway, consulte o Guia do Desenvolvedor do AgentCore Gateway. Para saber mais sobre o Web Search, acesse a documentação do Web Search.

Fonte

Add secure Web Search to Claude Desktop with Amazon Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/add-secure-web-search-to-claude-desktop-with-amazon-bedrock-agentcore/)

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

More posts