AWS Builder Center
Primeiros Passos com o Amazon Bedrock AgentCore Web Search Tool

Primeiros Passos com o Amazon Bedrock AgentCore Web Search Tool

Aprenda a configurar o Web Search Tool do AgentCore por meio de um Gateway, descobrir ferramentas MCP, autenticar com IAM e integrar busca web em tempo real ao seu agente de IA usando o Strands Agents SDK.

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (11 articles)

  1. …
  2. 5
    Primeiros Passos com o Amazon Bedrock AgentCore Web Search Tool This article
AWS Solutions Architect

Introdução

Agentes de IA se tornam significativamente mais úteis quando podem buscar informações atuais na internet. Em vez de depender apenas dos dados de treinamento do modelo (que estão sempre desatualizados), você pode dar ao seu agente a capacidade de pesquisar na web, recuperar resultados recentes e sintetizar respostas fundamentadas em dados ao vivo.
A  Amazon Bedrock AgentCore Web Search Tool  é um conector gerenciado de busca web disponível através do  AgentCore Gateway . Ela permite que agentes pesquisem na web sem a necessidade de chaves de API de terceiros (como Google Custom Search ou Bing API). A ferramenta é exposta como um endpoint MCP (Model Context Protocol), o que significa que qualquer framework compatível com MCP pode descobri-la e invocá-la automaticamente.
Este artigo faz parte de uma série que estou escrevendo sobre diferentes aspectos do Amazon Bedrock AgentCore. Aqui, focamos em como usar a Web Search Tool para dar aos agentes capacidades de busca web em tempo real. Para uma compreensão mais ampla do AgentCore e seus componentes, confira os outros artigos desta série:
Neste artigo, exploramos a Web Search Tool a partir de duas perspectivas:
  • Primeiro, invocamos a ferramenta localmente usando o Strands Agents SDK, demonstrando como desenvolvedores podem utilizá-la isoladamente fora de um Harness.
  • Em seguida, conectamos a ferramenta ao Harness da concessionária de veículos introduzido no  primeiro artigo  e deixamos o agente de IA utilizá-la de forma autônoma para responder perguntas de clientes.

O que é a Web Search Tool?

A Web Search Tool é um conector gerenciado disponível através do AgentCore Gateway. Se você acompanhou o  artigo sobre Gateway , já sabe que o Gateway transforma backends em ferramentas compatíveis com MCP. A Web Search Tool é um dos  conectores nativos  que o Gateway fornece pronto para uso.
Características principais:
  • Não requer chaves de API ou assinaturas
  • Exposta via AgentCore Gateway (protocolo MCP)
  • Retorna resultados de busca com títulos, trechos e URLs
  • O agente decide quando e o que pesquisar com base na conversa
Use a Web Search Tool quando o agente precisa encontrar informações mas não conhece a URL exata. O agente formula uma consulta de busca, recupera os resultados e sintetiza uma resposta.

Pré-requisitos

  • Conta AWS com credenciais configuradas
  • Python 3.12 instalado (Python 3.14 tem problemas de compatibilidade conhecidos com o Playwright)
  • Usuário ou role IAM com permissões para usar o Amazon Bedrock AgentCore Gateway e invocar modelos do Bedrock
  • Acesso ao modelo habilitado para Amazon Nova Pro no console do Amazon Bedrock
  • Região AWS onde o AgentCore está disponível (us-east-1, us-west-2, ap-southeast-2 ou eu-central-1)

Step 1: Clonar o Repositório e Instalar Dependências

Clone o repositório complementar e configure o ambiente Python:
git clone https://github.com/biagolini/PythonAwsBedrockAgentCoreWebSearch.git
cd PythonAwsBedrockAgentCoreWebSearch
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

No Windows, substitua o comando de ativação por  .venv\Scripts\activate .

Step 2: Criar o Gateway da Web Search Tool

A Web Search Tool é exposta através do  AgentCore Gateway  como um conector MCP. Para utilizá-la, você precisa criar um Gateway e adicionar um target de Web Search.

2.1 Criar a Role de Execução do Gateway

Antes de criar o Gateway, você precisa de uma role IAM que permita ao serviço AgentCore realizar operações de busca web. Crie uma role chamada  AgentCoreGatewayWebSearch  com uma política de confiança para  bedrock-agentcore.amazonaws.com  e anexe a seguinte política inline:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "GetGateway",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:GetGateway"
],
"Resource": "arn:aws:bedrock-agentcore:<your-region>:<your-account-id>:gateway/*"
},
{
"Sid": "InvokeWebSearch",
"Effect": "Allow",
"Action": "bedrock-agentcore:InvokeWebSearch",
"Resource": "arn:aws:bedrock-agentcore:<your-region>:aws:tool/web-search.v1"
}
]
}

Para o processo detalhado de criação da role (política de confiança, política inline), siga os mesmos passos descritos no  artigo sobre Gateway . A única diferença é o conteúdo da política inline acima. Para referência, consulte a  documentação da service role da Web Search Tool .

2.2 Criar o Gateway

2.2.1. Navegue até Amazon Bedrock AgentCore > Gateways no Console AWS
2.2.2. Clique em Create Gateway
Console do Amazon Bedrock AgentCore mostrando o caminho de navegação Gateways no painel esquerdo e o botão Create Gateway pronto para iniciar o assistente de criação

O assistente de criação possui quatro etapas:
Etapa 1 — Definir detalhes do gateway:
2.2.3. No campo Gateway name, insira  WebSearchGateway 
2.2.4. Em Permissions, selecione Use another role e escolha a role que você criou no Passo 2.1 (por exemplo,  AgentCoreGatewayWebSearch )
2.2.5. Deixe todas as seções opcionais com seus valores padrão. Clique em Next.
Primeira página do assistente de criação do Gateway com o campo de nome preenchido e a opção Use another role selecionada para as permissões

Etapa 2 — Configurar Identidade de Entrada:
2.2.6. Em Inbound Auth type, selecione No authorization (para este tutorial). Clique em Next.
Segunda página do assistente de criação do Gateway mostrando o tipo de autenticação de entrada definido como No authorization para este tutorial

Etapa 3 — Adicionar targets:
2.2.7. Em Select a target protocol, selecione MCP target
2.2.8. No campo Target name, insira  WebSearchTool 
2.2.9. No campo Target description, insira  Web search connector for finding current information 
2.2.10. Em Passthrough, mantenha o padrão Do not use passthrough - default aggregated
2.2.11. Em Target type, selecione Connectors. Esta opção fornece targets pré-configurados de provedores de integração.
2.2.12. Em Pre-configured targets, selecione Web Search tool
2.2.13. Em Outbound Auth configurations, selecione IAM Role (esta é a única opção disponível para o conector Web Search)
2.2.14. Em Additional configurations, você pode opcionalmente adicionar domínios ao campo Exclude domains para filtrar resultados de sites específicos. Deixe vazio para este tutorial.
2.2.15. Clique em Next.
Terceira página do assistente de criação do Gateway mostrando o target MCP com Connectors como tipo de target e a ferramenta Web Search escolhida como target pré-configurado

Etapa 4 — Revisar e criar:
2.2.12. Revise sua configuração e clique em Create
2.2.13. Aguarde até que o status do Gateway e do target atinjam Ready

2.3 Copiar o ID do Gateway

Após a criação, abra a página de detalhes do Gateway e copie o Gateway ID. Você precisará dele na próxima etapa para configurar o script local. O ID segue o padrão  websearchgateway-xxxxxxxxxx .

Step 3: Testar a Web Search Tool Localmente

O script  web_search_agent.py  demonstra como usar a Web Search Tool via Gateway. Ele se conecta ao endpoint MCP do Gateway, descobre a ferramenta de busca e permite que o agente pesquise na web.

3.1 Entendendo o Script

# code/web_search_agent.py

Os conceitos principais:
  • A Web Search Tool é exposta como um endpoint MCP através do Gateway
  • Usamos o  MCPClient  do Strands com  aws_iam_streamablehttp_client  do  mcp-proxy-for-aws  para lidar com autenticação IAM
  • A URL do Gateway é construída a partir do Gateway ID:  https://{GATEWAY_ID}.gateway.bedrock-agentcore.{REGION}.amazonaws.com/mcp 
  • As ferramentas são descobertas dinamicamente via  mcp_client.list_tools_sync()  — o agente vê  WebSearchTool  e o utiliza quando necessário
O prompt do sistema inclui a data de hoje para que o agente possa delimitar os resultados de busca ao período atual.

3.2 Executar o Script

python web_search_agent.py

Comportamento esperado:
Prompt: What is the best 2-4 year old used car for value in the US market?

Discovered tools: ['WebSearchTool___WebSearch']

<thinking> To determine the best 2-4 year old used car for value in the US market, I need to search for recent reviews, expert opinions, and market analysis that focus on used cars within this age range. I will use the WebSearchTool to find the most relevant and up-to-date information. </thinking>

Tool #1: WebSearchTool___WebSearch
Based on the search results, the best 2-4 year old used cars for value in the US market are:

1. **2021-2023 Toyota 4Runner** - Known for its reliability and strong resale value, the Toyota 4Runner is a great option for a used SUV. It has consistently high J.D. Power reliability ratings and many satisfied owners report few problems.

2. **2021-2022 Hyundai Elantra** - The pre-facelift, seventh-generation Hyundai Elantra is beginning to depreciate below $20,000. It's important to check the condition of the drivetrain and ensure the transmissions have been well-maintained.

3. **2022-2023 Toyota Camry** - These sedans have high J.D. Power reliability ratings and many satisfied owners. Be sure to inspect the condition of the drivetrain and check for any recalls, such as the 'Do Not Drive' recall for early 2023 models.

...
Done.

O agente descobre a ferramenta  WebSearchTool___WebSearch  a partir do Gateway, formula uma consulta de busca e sintetiza os resultados em uma resposta coerente. Isso se conecta diretamente ao nosso cenário de concessionária de veículos — um assistente de vendas que pode pesquisar informações atuais do mercado.

Step 4: Integrando com o Harness

Agora conectamos a Web Search Tool ao Harness para que o agente possa utilizá-la de forma autônoma.

4.1 Editar o Harness para Adicionar o Gateway

4.1.1. Navegue até Amazon Bedrock AgentCore > Harness
4.1.2. Clique no nome do seu Harness ( car_agent ) para abrir sua página de detalhes
4.1.3. Clique em Edit na área superior direita
4.1.4. Na seção Tools, clique em Add Gateway e selecione o  WebSearchGateway 
4.1.5. Clique em Save Harness e aguarde o status retornar para Ready
Após salvar, o console pode exibir uma mensagem sugerindo que a role de execução do Harness precisa ser atualizada com permissões para invocar o Gateway. Se esta mensagem aparecer, siga as instruções fornecidas pelo console para atualizar a role. Isso garante que o Harness tenha as permissões necessárias para chamar o Gateway em seu nome.

4.2 Testar a Web Search Tool via Harness

4.2.1. Uma vez que o Harness esteja Ready, clique no botão Test Harness
4.2.2. Insira um prompt que exija busca web:
Search the web for: What are the most reliable used SUVs under $25,000?

4.2.3. O agente invocará a Web Search Tool, pesquisará as informações solicitadas e apresentará um resumo dos resultados. A interface de teste mostrará um indicador como "WebSearchTool WebSearch" confirmando que a ferramenta foi utilizada.
Interface de teste do Harness exibindo a resposta do agente e um indicador confirmando que a Web Search Tool foi invocada para responder ao prompt


Conclusão

Neste artigo, você aprendeu como usar a Amazon Bedrock AgentCore Web Search Tool para dar aos agentes capacidades de busca web em tempo real:
  • A Web Search Tool é um conector gerenciado disponível através do AgentCore Gateway que não requer chaves de API de terceiros. Você criou um Gateway com o conector Web Search, conectou-se a ele via protocolo MCP e demonstrou como o agente pesquisa na web e sintetiza os resultados.
  • Invocação local permite que desenvolvedores testem a ferramenta isoladamente usando o Strands Agents SDK com o  MCPClient  e  aws_iam_streamablehttp_client  para autenticação IAM.
  • Integração com o Harness permite que o agente use a Web Search Tool de forma autônoma, decidindo quando pesquisar com base no contexto da conversa.
A Web Search Tool é ideal para cenários onde o agente precisa de informações atuais mas não conhece a URL exata. Uma vez que seu Gateway esteja rodando em produção, considere habilitar observabilidade (entrega de logs e rastreamento) conforme descrito em  Getting Started with Observability for Amazon Bedrock AgentCore  para monitorar invocações de ferramentas, latência e erros.
No próximo artigo, exploraremos a Browser Tool, que complementa a Web Search ao permitir que o agente navegue até URLs específicas e extraia conteúdo detalhado de páginas web.

Referências




Fique Conectado

Se você achou este artigo útil e quer aprender mais sobre AWS, arquitetura cloud, IA, infraestrutura como código e segurança na nuvem, siga o autor para conteúdos futuros e tutoriais:
Fique ligado para mais walkthroughs práticos e soluções para desafios de infraestrutura cloud e DevOps.
Happy building on AWS! 🚀☁️

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (11 articles)

  1. …
  2. 5
    Primeiros Passos com o Amazon Bedrock AgentCore Web Search Tool This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article