Cómo construir un agente de IA en Python

TL;DR:

• Un agente de IA es un bucle: el modelo elige una herramienta, tu código la ejecuta y el resultado regresa al modelo. La inteligencia es el modelo de lenguaje; el alcance proviene de las herramientas que le das. Para investigación y monitoreo, las dos herramientas que importan son la búsqueda en la web y la recuperación de páginas.
• Dale al agente herramientas reales de la web, no un conjunto de datos de entrenamiento congelado. Una herramienta web_search respaldada por Deep SerpApi devuelve resultados de Google en vivo, y una herramienta fetch_page respaldada por la Universal Scraping API devuelve HTML renderizado, por lo que el agente razona sobre datos actuales, no de hace un año.
• Ambas herramientas son una solicitud HTTP POST cada una. La búsqueda utiliza POST /api/v1/scraper/request con el actor scraper.google.search; la recuperación utiliza POST /api/v1/unlocker/request con js_render activado. No hay un navegador que gestionar, ni un pool de proxies que rotar.
• El modelo controla el flujo. Expones las firmas de las herramientas, el modelo decide qué llamar y cuándo, y tú ejecutas y alimentas los resultados hasta que responde; ese bucle es todo el agente.
• Mantén la capa de herramientas determinista y verificada. Las llamadas de búsqueda y recuperación devuelven datos estructurados que puedes probar independientemente del modelo, de donde proviene la fiabilidad.
• Gratis para empezar. Las nuevas cuentas de Scrapeless incluyen tiempo de ejecución gratuito de Deep SerpApi; regístrate en app.scrapeless.com.

Introducción: un agente es tan bueno como sus herramientas

Un modelo de lenguaje por sí solo puede razonar, pero no puede ver la web de hoy; responde a partir de datos de entrenamiento con un corte. Un agente de IA cierra esa brecha al envolver el modelo en un bucle: el modelo pide ejecutar una herramienta, tu código la ejecuta contra datos en vivo y el resultado regresa a la conversación. Repite hasta que el modelo tenga lo que necesita para responder.

La parte difícil rara vez es el bucle; son las herramientas. Un agente de investigación necesita buscar en la web abierta y leer las páginas que encuentra, y ambas cosas fallan en sitios reales: los motores de búsqueda limitan las tasas, y las páginas objetivo se renderizan con JavaScript o están detrás de defensas contra bots. Hacer esto a mano es la mayor parte del trabajo.

Esta guía construye un agente de investigación en Python donde ambas herramientas son llamadas HTTP gestionadas: web_search se ejecuta en Scrapeless Deep SerpApi y fetch_page se ejecuta en la Universal Scraping API. La capa de herramientas a continuación está verificada contra la API en vivo; el bucle de razonamiento del modelo se muestra con el patrón estándar de llamada a la herramienta. Solo datos públicos.

Secuencia de pasos a grandes rasgos

El agente tiene cuatro partes, y solo las dos del medio tocan la web:

1. Objetivo de entrada — una pregunta o tarea de investigación del usuario.
2. web_search(query) — resultados en vivo de Google a través de Deep SerpApi (título, enlace, fragmento).
3. fetch_page(url) — HTML renderizado de cualquier resultado que el modelo desee leer, a través de la Universal Scraping API.
4. Bucle del modelo — el modelo de lenguaje decide qué herramienta llamar, lee el resultado y llama a otra herramienta o escribe la respuesta final.

Los pasos 2 y 3 son llamadas HTTP deterministas que puedes verificar por sí solas. El paso 4 es el modelo; los pasos 1-3 son lo que hace que sus respuestas estén actualizadas.

Requisitos previos

• Python 3.10 o más reciente
• pip install requests (más el SDK de tu proveedor de modelo)
• Una cuenta de Scrapeless y una clave API: regístrate en app.scrapeless.com
• Una clave API del proveedor del modelo para el bucle de razonamiento (Paso 3)

export SCRAPELESS_API_KEY="tu_token_api_aquí"

Paso 1 — La herramienta de búsqueda en la web

La herramienta de búsqueda publica una consulta al actor de búsqueda de Google de Deep SerpApi y devuelve una lista compacta de resultados orgánicos: título, enlace y fragmento; que es exactamente lo que un modelo necesita para decidir qué leer a continuación:

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": "es", "gl": "es"},
        },
        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
    ]


# Ejecuta esto por su cuenta para confirmar la forma:
hits = web_search("mejores herramientas de scraping web 2026", 3)
print(len(hits), "resultados")
for h in hits:
    print("-", h["title"], "|", h["link"])

El actor devuelve organic_results con los campos de búsqueda estándar; la función lo recorta a los count superiores para que no abrumes el contexto del modelo con el SERP completo.

Obtén tu clave API en el plan gratuito: app.scrapeless.com

Paso 2 — La herramienta de recuperación de páginas

Una vez que el modelo elige un resultado para leer, necesita el contenido de la página. La herramienta de obtención envía la URL a la API de Scraping Universal con js_render activado, por lo que las páginas renderizadas en el cliente regresan como HTML terminado en lugar de una shell vacía:

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", "")


# Obtén una página renderizada y confirma que obtenemos HTML de vuelta:
html = fetch_page("https://www.scrapeless.com/en")
print("obtenido", len(html), "bytes")

Antes de entregar el HTML al modelo, conviértelo a texto (con selectolax o BeautifulSoup) para que gastes contexto en contenido y no en marcado. Mantén la herramienta devolviendo HTML en crudo; deja que el agente decida cuánto leer.

Paso 3 — El bucle del modelo

Con ambas herramientas verificadas, el agente es el bucle que permite que el modelo las llame. Expón las dos firmas de las herramientas a la API de llamada de herramientas de tu proveedor de modelo, luego ejecuta el ciclo estándar: envía la conversación, y mientras el modelo devuelva una llamada a la herramienta, ejecútala y agrega el resultado; cuando devuelva texto, esa es la respuesta.

Nota: este paso llama a tu proveedor de modelo y requiere la clave API de ese proveedor. Las funciones de las herramientas anteriores son completamente ejecutables por sí solas; el bucle a continuación es el patrón estándar de llamada a herramientas conectado a ellas.

TOOLS = [
    {
        "name": "web_search",
        "description": "Buscar en Google una consulta; devuelve título, enlace, fragmento.",
        "input_schema": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
    {
        "name": "fetch_page",
        "description": "Obtener el HTML renderizado de una 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)  # llamada a la API de herramienta del proveedor
        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

La estructura es independiente del proveedor: cada API principal de llamada a herramientas te da "el modelo quiere llamar a la herramienta X con argumentos Y", tú ejecutas DISPATCH[X](**Y), agregas el resultado y repites. La competencia del agente proviene de las dos herramientas que devuelven datos reales y actuales, que es la parte que esta guía verificó.

Lo que obtienes de vuelta

Cada resultado de web_search es un registro plano sobre el cual el modelo puede razonar directamente:

[
  {
    "title": "Las mejores herramientas de web scraping en 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": "Una comparación práctica de herramientas de scraping en cuanto a renderizado, proxies y precio ..."
  }
]
// El esquema refleja exactamente lo que devuelve web_search. Los valores de los campos son muestras ilustrativas.

Algunas observaciones honestas:

• Recorta los resultados de búsqueda antes de que lleguen al modelo. Los tres a cinco mejores suelen ser suficientes; la lista completa de SERP desperdicia contexto y dinero.
• Convierte HTML a texto en el agente, no en la herramienta. Mantén fetch_page devolviendo HTML en crudo para que siga siendo determinista; haz la limpieza donde controlas el presupuesto de tokens.
• Limita el bucle. Dale al agente un número máximo de llamadas a la herramienta para que una ejecución confusa no se quede dando vueltas: un límite estricto, no una reejecución.
• Las herramientas son probables de forma independiente. Dado que la búsqueda y la obtención son HTTP simples, puedes probarlas de forma unitaria sin el modelo en el bucle, que es donde reside la fiabilidad.

Conclusión: las herramientas hacen al agente

Un agente de investigación es un pequeño bucle alrededor de un modelo capaz: la palanca está en las herramientas. Respaldar web_search con Deep SerpApi y fetch_page con la API Universal Scraping, y el agente razona sobre los resultados en vivo de Google y las páginas renderizadas en lugar de datos de entrenamiento obsoletos, sin necesidad de mantener una flota de navegadores o rotación de proxies. Construye primero las herramientas, verifica su funcionamiento por separado y luego envuelve el bucle del modelo a su alrededor. Para un agente que controla un navegador completo en lugar de llamadas HTTP, consulta construyendo un agente de búsqueda en el Scraping Browser; la página del producto Deep SerpApi y documentación cubren cada actor. Verifica las herramientas, deja que el modelo se encargue y establece un límite en el bucle.

¿Listo para construir tu pipeline de datos impulsado por IA?

Únete a nuestra comunidad para reclamar un plan gratuito y conectar con desarrolladores que están construyendo agentes y pipelines de investigación: Discord · Telegram.

Regístrate en app.scrapeless.com para obtener tiempo de ejecución gratuito de Deep SerpApi y conectar las herramientas de búsqueda y captura en el marco del agente que ya utilizas. Consulta precios para escalabilidad.

Preguntas Frecuentes

P: ¿Necesito un proveedor de modelo específico para construir esto?
No. El bucle es agnóstico al proveedor: funciona cualquier API que llame a herramientas. Intercambia la llamada client.run(...) por la de tu proveedor; las herramientas web_search y fetch_page permanecen idénticas.

P: ¿Por qué usar APIs gestionadas para las herramientas en lugar de requests y un navegador sin cabeza?
Porque la web abierta combate a los scrapers en bruto: los motores de búsqueda imponen límites de tasa y las páginas se renderizan del lado del cliente o se bloquean detrás de desafíos. Deep SerpApi y la API Universal Scraping manejan el renderizado y el acceso, por lo que las herramientas devuelven datos limpios en lugar de bloqueos.

P: ¿Es legal el acceso web del agente?
El agente recopila datos disponibles públicamente. Cómo los almacenas y usas está regido por los Términos de Servicio de cada sitio y la legislación local: accede solo a datos públicos, respeta los Términos de Servicio y consulta con un abogado para tu caso de uso.

P: ¿Cómo evito que el agente se quede en un bucle infinito?
Establece un límite en el número de llamadas a herramientas por ejecución y detén el proceso cuando se alcance el límite. Eso es un límite estricto sobre el flujo de control, no sobre el manejo de errores.

P: ¿Qué tan grandes pueden ser las páginas obtenidas?
Grandes: una sola página de contenido puede devolver cientos de kilobytes de HTML. Convierte a texto y trunca antes de pasarlo al modelo para que controles el presupuesto de contexto.

P: ¿Puede el agente usar más de dos herramientas?
Sí. Agrega cualquier herramienta que devuelva datos estructurados: un actor de Google Maps, una búsqueda de noticias, una consulta de base de datos, a la lista de TOOLS y al mapa DISPATCH, y el modelo podrá llamarla de la misma manera.