Como Construir um Agente de IA em Python

TL;DR:

• Um agente de IA é um loop: o modelo escolhe uma ferramenta, seu código a executa, e o resultado volta para o modelo. A inteligência é o modelo de linguagem; o alcance vem das ferramentas que você lhe dá. Para pesquisa e monitoramento, as duas ferramentas que importam são busca na web e captura de página.
• Dê ao agente ferramentas reais da web, não um conjunto de treinamento congelado. Uma ferramenta web_search apoiada no Deep SerpApi retorna resultados ao vivo do Google, e uma ferramenta fetch_page apoiada na API Universal Scraping retorna HTML renderizado — assim, o agente raciocina sobre dados atuais, não sobre os do ano passado.
• Ambas as ferramentas são uma requisição HTTP POST cada. A busca faz um POST /api/v1/scraper/request com o ator scraper.google.search; a captura faz um POST /api/v1/unlocker/request com js_render ativado. Sem navegador para gerenciar, sem pool de proxies para rotacionar.
• O modelo possui o controle do fluxo. Você expõe as assinaturas das ferramentas, o modelo decide o que chamar e quando, e você executa e alimenta os resultados de volta até que ele responda — esse loop é o agente inteiro.
• Mantenha a camada de ferramentas determinística e verificada. As chamadas de busca e captura retornam dados estruturados que você pode testar independentemente do modelo, de onde vem a confiabilidade.
• Gratuito para começar. Novas contas Scrapeless incluem tempo de execução gratuito do Deep SerpApi — inscreva-se em app.scrapeless.com.

Introdução: um agente é tão bom quanto suas ferramentas

Um modelo de linguagem por si só pode raciocinar, mas não consegue ver a web de hoje — ele responde com dados de treinamento com um corte. Um agente de IA fecha essa lacuna envolvendo o modelo em um loop: o modelo pede para executar uma ferramenta, seu código a executa contra dados ao vivo, e o resultado volta para a conversa. Repita até que o modelo tenha o que precisa para responder.

A parte difícil raramente é o loop — são as ferramentas. Um agente de pesquisa precisa pesquisar na web aberta e ler as páginas que encontra, e ambas quebram em sites reais: motores de busca limitam a taxa, e páginas-alvo são renderizadas com JavaScript ou ficam atrás de defesas contra bots. Fazer isso manualmente é a maior parte do trabalho.

Este guia constrói um agente de pesquisa em Python onde ambas as ferramentas são chamadas HTTP gerenciadas: web_search roda no Scrapeless Deep SerpApi e fetch_page roda na API Universal Scraping. A camada de ferramentas abaixo é verificada contra a API ao vivo; o loop de raciocínio do modelo é mostrado com o padrão padrão de chamada de ferramentas. Apenas dados públicos.

Pipeline em um relance

O agente tem quatro partes, e apenas as duas partes do meio tocam a web:

1. Objetivo de entrada — uma pergunta ou tarefa de pesquisa do usuário.
2. web_search(query) — resultados ao vivo do Google via Deep SerpApi (título, link, snippet).
3. fetch_page(url) — HTML renderizado para qualquer resultado que o modelo queira ler, via API Universal Scraping.
4. Loop do modelo — o modelo de linguagem decide qual ferramenta chamar, lê o resultado, e chama outra ferramenta ou escreve a resposta final.

As etapas 2 e 3 são chamadas HTTP determinísticas que você pode verificar por conta própria. A etapa 4 é o modelo; as etapas 1–3 são o que torna suas respostas atuais.

Pré-requisitos

• Python 3.10 ou superior
• pip install requests (além do SDK do seu provedor de modelo)
• Uma conta Scrapeless e chave da API — inscreva-se em app.scrapeless.com
• Uma chave da API do provedor de modelo para o loop de raciocínio (Etapa 3)

export SCRAPELESS_API_KEY="your_api_token_here"

Passo 1 — A ferramenta de busca na web

A ferramenta de busca envia uma consulta para o ator de Busca Google do Deep SerpApi e retorna uma lista compacta de resultados orgânicos — título, link e snippet — que é exatamente o que um modelo precisa para decidir o que ler a seguir:

import os
import requests

API = "https://api.scrapeless.com"
HEADERS = {
    "Content-Type": "application/json",
    "x-api-token": os.environ["SCRAPELESS_API_KEY"],
}

def web_search(query: str, count: int = 5):
    r = requests.post(
        f"{API}/api/v1/scraper/request",
        headers=HEADERS,
        json={
            "actor": "scraper.google.search",
            "input": {"q": query, "hl": "en", "gl": "us"},
        },
        timeout=90,
    )
    r.raise_for_status()
    results = r.json().get("organic_results", [])[:count]
    return [
        {"title": x.get("title"), "link": x.get("link"), "snippet": x.get("snippet")}
        for x in results
    ]


# Execute-o sozinho para confirmar o formato:
hits = web_search("melhores ferramentas de scraping web 2026", 3)
print(len(hits), "resultados")
for h in hits:
    print("-", h["title"], "|", h["link"])

O ator retorna organic_results com os campos de busca padrão; a função corta para os count mais altos para que você não inunde o contexto do modelo com a SERP completa.

Obtenha sua chave da API no plano gratuito: app.scrapeless.com

Passo 2 — A ferramenta de captura de página

Uma vez que o modelo escolhe um resultado para ler, ele precisa do conteúdo da página. A ferramenta de busca envia o URL para a API Universal Scraping com js_render ativado, para que as páginas renderizadas pelo cliente retornem como HTML completo em vez de um shell vazio:

import os
import requests

API = "https://api.scrapeless.com"
HEADERS = {
    "Content-Type": "application/json",
    "x-api-token": os.environ["SCRAPELESS_API_KEY"],
}

def fetch_page(url: str):
    r = requests.post(
        f"{API}/api/v1/unlocker/request",
        headers=HEADERS,
        json={
            "actor": "unlocker.webunlocker",
            "input": {"url": url, "method": "GET", "js_render": True},
        },
        timeout=120,
    )
    r.raise_for_status()
    return r.json().get("data", "")


# Busca uma página renderizada e confirma que obtemos HTML:
html = fetch_page("https://www.scrapeless.com/en")
print("fetched", len(html), "bytes")

Antes de entregar o HTML ao modelo, extraia-o para texto (com selectolax ou BeautifulSoup) para que você gaste contexto com conteúdo, não com marcação. Mantenha a ferramenta retornando HTML bruto — deixe o agente decidir quanto ler.

Passo 3 — O loop do modelo

Com ambas as ferramentas verificadas, o agente é o loop que permite ao modelo chamá-las. Exponha as duas assinaturas das ferramentas à API de chamada de ferramentas do seu provedor de modelo, e então execute o ciclo padrão: envie a conversa, e enquanto o modelo retornar uma chamada de ferramenta, execute-a e anexe o resultado; quando ela retornar texto, essa será a resposta.

Nota: este passo chama seu provedor de modelo e requer a chave da API desse provedor. As funções da ferramenta acima são totalmente executáveis sozinhas; o loop abaixo é o padrão de chamada de ferramenta conectado a elas.

TOOLS = [
    {
        "name": "web_search",
        "description": "Procura no Google por uma consulta; retorna título, link, trecho.",
        "input_schema": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
    {
        "name": "fetch_page",
        "description": "Busca o HTML renderizado de um URL.",
        "input_schema": {
            "type": "object",
            "properties": {"url": {"type": "string"}},
            "required": ["url"],
        },
    },
]

DISPATCH = {"web_search": web_search, "fetch_page": fetch_page}

def run_agent(client, goal: str):
    messages = [{"role": "user", "content": goal}]
    while True:
        reply = client.run(messages=messages, tools=TOOLS)  # chamado de API do provedor
        if reply.tool_call:
            name, args = reply.tool_call.name, reply.tool_call.args
            result = DISPATCH[name](**args)
            messages.append({"role": "tool", "name": name, "content": result})
            continue
        return reply.text

A forma é independente do provedor: toda API de chamada de ferramentas principal oferece a você "o modelo quer chamar a ferramenta X com args Y", você executa DISPATCH[X](**Y), anexa o resultado e continua. A competência do agente vem do retorno de dados reais e atuais de ambas as ferramentas — que é a parte que este guia verificou.

O que você recebe de volta

Cada resultado de web_search é um registro plano que o modelo pode raciocinar diretamente:

[
  {
    "title": "Melhores Ferramentas de Web Scraping em 2026",
    "link": "https://dev.to/nitinfab/best-web-scraping-tools-in-2026-i-tested-30-tools-and-these-are-the-only-ones-worth-using-11l3",
    "snippet": "Uma comparação prática de ferramentas de scraping em termos de renderização, proxies e preço ..."
  }
]
// O esquema reflete exatamente o que web_search retorna. Os valores dos campos são amostras ilustrativas.

Algumas observações honestas:

• Corte os resultados da busca antes de chegarem ao modelo. Os três a cinco primeiros são geralmente suficientes; o SERP completo desperdiça contexto e dinheiro.
• Converta HTML em texto no agente, não na ferramenta. Mantenha fetch_page retornando HTML bruto para que permaneça determinístico; faça a limpeza onde você controla o orçamento de tokens.
• Limite o loop. Dê ao agente uma contagem máxima de chamadas de ferramentas para que uma execução confusa não fique em loop — um limite rígido, não uma re-execução.
• As ferramentas são testáveis de forma independente. Como busca e fetch são HTTP simples, você pode testá-las unitariamente sem o modelo no loop, que é onde a confiabilidade reside.

Conclusão: as ferramentas fazem o agente

Um agente de pesquisa é um pequeno loop em torno de um modelo capaz — a alavanca está nas ferramentas. Reforce a web_search com a Deep SerpApi e fetch_page com a Universal Scraping API, e o agente raciocina sobre resultados ao vivo do Google e páginas renderizadas em vez de dados de treinamento desatualizados, sem necessidade de manter uma frota de navegadores ou rotação de proxies. Construa primeiro as ferramentas, verifique-as sozinhas e, em seguida, envolva o loop do modelo ao redor delas. Para um agente que opera um navegador completo em vez de chamadas HTTP, veja construindo um agente de pesquisa no Scraping Browser; a página do produto Deep SerpApi e documentação cobrem todos os atores. Verifique as ferramentas, deixe o modelo operar e limite o loop.

Pronto para construir seu pipeline de dados alimentado por IA?

Junte-se à nossa comunidade para reivindicar um plano gratuito e conectar-se com desenvolvedores que estão construindo agentes e pipelines de pesquisa: Discord · Telegram.

Inscreva-se em app.scrapeless.com para um runtime gratuito da Deep SerpApi e conecte as ferramentas de pesquisa e fetch à estrutura de agente que você já utiliza. Confira preços para escalabilidade.

FAQ

Q: Preciso de um provedor de modelo específico para construir isso?
Não. O loop é indiferente ao provedor — qualquer API que chame ferramentas funciona. Troque a chamada client.run(...) pela do seu provedor; as ferramentas web_search e fetch_page permanecem idênticas.

Q: Por que usar APIs gerenciadas para as ferramentas em vez de requests e um navegador sem interface?
Porque a web aberta combate raspadores brutos: motores de busca limitam a taxa e páginas de destino renderizam do lado do cliente ou se escondem atrás de desafios. A Deep SerpApi e a Universal Scraping API lidam com renderização e acesso, então as ferramentas retornam dados limpos em vez de bloqueios.

Q: O acesso do agente à web é legal?
O agente coleta dados disponíveis publicamente. Como você armazena e utiliza isso é regido pelos Termos de Serviço de cada site e pela lei local — acesse apenas dados públicos, respeite os ToS e consulte um advogado para seu caso de uso.

Q: Como posso impedir que o agente fique em loop para sempre?
Limite o número de chamadas às ferramentas por execução e pare quando o limite é atingido. Esse é um teto rígido sobre o fluxo de controle, não sobre o tratamento de erros.

Q: Qual o tamanho máximo que as páginas buscadas podem ter?
Grande — uma única página de conteúdo pode retornar centenas de kilobytes de HTML. Converta para texto e truncagem antes de passar para o modelo, assim você controla o orçamento de contexto.

Q: O agente pode usar mais de duas ferramentas?
Sim. Adicione qualquer ferramenta que retorne dados estruturados — um ator do Google Maps, uma busca de notícias, uma consulta a banco de dados — à lista TOOLS e ao mapa DISPATCH, e o modelo pode chamá-la da mesma forma.