Crear agentes web de IA con OpenAI SDK y Web Unlocker

En esta guía aprenderás:

Qué es el SDK de agentes de OpenAI
Por qué integrarlo con un servicio de desbloqueo web es clave para maximizar su eficacia
Cómo crear un agente Python utilizando el SDK de agentes OpenAI y una API de desbloqueo web en un detallado tutorial paso a paso.

Sumerjámonos.

¿Qué es el SDK de agentes de OpenAI?

OpenAI Agents SDK es una librería Python de código abierto de OpenAI. Está diseñada para construir aplicaciones de IA basadas en agentes de una forma sencilla, ligera y lista para producción. Esta librería es una evolución refinada del anterior proyecto experimental de OpenAI llamado Swarm.

El SDK de agentes de OpenAI se centra en proporcionar unas pocas primitivas básicas con una abstracción mínima:

Agentes: LLM emparejados con instrucciones y herramientas específicas para realizar tareas.
Traspasos: Permitir a los agentes delegar tareas en otros agentes cuando sea necesario.
Guardarraíles: Validar las entradas de los agentes para garantizar que cumplen los formatos o condiciones esperados.

Estos bloques de construcción, combinados con la flexibilidad de Python, facilitan la definición de interacciones complejas entre agentes y herramientas.

El SDK también incluye trazado integrado, para que pueda visualizar, depurar y evaluar los flujos de trabajo de sus agentes. Incluso permite ajustar los modelos a sus casos de uso específicos.

Principales limitaciones de este enfoque para crear agentes de IA

La mayoría de los agentes de IA pretenden automatizar operaciones en páginas web, ya sea recuperar contenidos o interactuar con elementos de una página. En otras palabras, necesitan navegar programáticamente por la Web.

Aparte de los posibles malentendidos del propio modelo de IA, el mayor reto al que se enfrentan estos agentes es lidiar con las medidas de protección de los sitios web. La razón es que muchos sitios implementan tecnologías anti-bot y anti-scraping que pueden bloquear o engañar a los agentes de IA. Esto es especialmente cierto hoy en día, cuando los CAPTCHA anti-AI y los sistemas avanzados de detección de bots son cada vez más comunes.

¿Es este el final del camino para los agentes web de IA? Por supuesto que no.

Para superar estas barreras, necesita mejorar la capacidad de su agente para navegar por la Web integrándolo con una solución como la API Web Unlocker de Bright Data. Esta herramienta funciona con cualquier cliente HTTP o solución que se conecte a Internet (incluidos los agentes de IA), actuando como una pasarela de desbloqueo web. Proporciona HTML limpio y desbloqueado desde cualquier página web. Se acabaron los CAPTCHA, las prohibiciones de IP y los contenidos bloqueados.

Descubra por qué combinar el SDK de Agentes OpenAI con la API Web Unlocker es la estrategia definitiva para crear agentes de IA potentes y expertos en la web.

Cómo integrar el SDK de Agentes con una API de desbloqueo web

En esta sección guiada, aprenderá a integrar el SDK OpenAI Agents con la API Web Unlocker de Bright Data para construir un agente de IA capaz de:

Resumir el texto de cualquier página web
Recuperación de datos estructurados de productos de sitios web de comercio electrónico
Recopilación de información clave de artículos periodísticos

Para conseguirlo, el agente ordenará al SDK de Agentes de OpenAI que utilice la API Web Unlocker como motor para recuperar el contenido de cualquier página web. Una vez recuperado el contenido, el agente aplicará lógica de IA para extraer y formatear los datos según sea necesario para cada una de las tareas anteriores.

Descargo de responsabilidad: Los tres casos de uso anteriores son sólo ejemplos. El enfoque mostrado aquí puede extenderse a muchos otros escenarios personalizando el comportamiento del agente.

Siga los pasos que se indican a continuación para crear un agente de raspado de IA en Python utilizando el SDK de agentes de OpenAI y la API Web Unlocker de Bright Data para obtener un alto rendimiento.

Requisitos previos

Antes de sumergirte en este tutorial, asegúrate de que tienes lo siguiente:

Python 3 o superior instalado localmente
Una cuenta activa de Bright Data
Una cuenta activa de OpenAI
Conocimiento básico del funcionamiento de las peticiones HTTP
Conocimiento del funcionamiento de los modelos pydánticos
Una idea general del funcionamiento de los agentes de IA

No se preocupe si aún no está todo configurado. En las siguientes secciones se le guiará a través de la configuración.

Paso nº 1: Configuración del proyecto

Antes de empezar, asegúrate de que tienes Python 3 instalado en tu sistema. Si no es así, descarga Python y sigue las instrucciones de instalación correspondientes a tu sistema operativo.

Abra su terminal y cree una nueva carpeta para su proyecto de agente de raspado:

mkdir openai-sdk-agent

La carpeta openai-sdk-agent contendrá todo el código para su agente basado en Python y potenciado por el SDK de Agents.

Navega hasta la carpeta del proyecto y configura un entorno virtual:

cd openai-sdk-agent
python -m venv venv

Carga la carpeta del proyecto en tu IDE de Python favorito. Visual Studio Code con la extensión Python o PyCharm Community Edition son buenas opciones.

Dentro de la carpeta openai-sdk-agent, crea un nuevo archivo Python llamado agent.py. Su estructura de carpetas ahora debe tener este aspecto:

La estructura de archivos del proyecto de agente de IA

Actualmente, scraper.py es un script Python en blanco, pero pronto contendrá la lógica deseada del agente de IA.

En el terminal del IDE, active el entorno virtual. En Linux o macOS, ejecuta este comando:

./env/bin/activate

De forma equivalente, en Windows, ejecute:

env/Scripts/activate

¡Ya está todo listo! Ahora tienes un entorno Python para construir un potente agente de IA usando el SDK de Agentes OpenAI y un desbloqueador web.

Paso 2: Instalar las dependencias del proyecto y empezar

Este proyecto utiliza las siguientes bibliotecas de Python:

openai-agents: El SDK de Agentes OpenAI, utilizado para construir agentes de IA en Python.
peticiones: Para conectarse a la API Web Unlocker de Bright Data y obtener el contenido HTML de una página web sobre la que operará el agente de IA. Obtenga más información en nuestra guía sobre el dominio de la biblioteca Python Requests.
pydantic: Definir modelos de salida estructurados, que permitan al agente devolver datos en un formato claro y validado.
markdownify: Para convertir contenido HTML crudo en Markdown limpio. (Pronto explicaremos por qué es útil).
python-dotenv: Para cargar variables de entorno desde un archivo .env. Ahí es donde almacenaremos los secretos para OpenAI y Bright Data.

En un entorno virtual activado, instalarlos todos con:

pip install requests pydantic openai-agents openai-agents markdownify python-dotenv

Ahora, inicializa scraper.py con los siguientes imports y código async boilerplate:

import asyncio
from agents import Agent, RunResult, Runner, function_tool
import requests
from pydantic import BaseModel
from markdownify import markdownify as md
from dotenv import load_dotenv 

# AI agent logic...

async def run():
    # Call the async AI agent logic...

if __name__ == "__main__":
    asyncio.run(run())

¡Maravilloso! Hora de cargar las variables de entorno.

Paso nº 3: Configurar las variables de entorno Lectura

Añade un archivo .env en la carpeta de tu proyecto:

Este archivo contendrá tus variables de entorno, como las claves API y los tokens secretos. Para cargar las variables de entorno desde el archivo .env, utilice load_dotenv() del paquete dotenv:

load_dotenv()

Ahora puede leer variables de entorno específicas utilizando os.getenv() de la siguiente manera:

os.getenv("ENV_NAME")

No olvides importar os de la biblioteca estándar de Python:

import os

Muy bien. Las variables de entorno están listas para ser leídas.

Paso 4: Configurar el SDK de agentes de OpenAI

Necesitas una clave de API de OpenAI válida para utilizar el SDK de Agentes de OpenAI. Si aún no has generado una, sigue la guía oficial de OpenAI para crear tu clave API.

Una vez que la tengas, añade la clave a tu archivo .env de la siguiente manera:

OPENAI_API_KEY="<YOUR_OPENAI_KEY>"

Asegúrese de sustituir el por la clave real.

No es necesaria ninguna configuración adicional, ya que el SDK de openai-agents está diseñado para leer automáticamente la clave de la API desde el entorno OPENAI_API_KEY.

Paso #5: Configurar Web Unlocker API

Si aún no lo ha hecho, cree una cuenta de Bright Data. Si no, simplemente inicie sesión.

A continuación, lea la documentación oficial de Bright Data sobre Web Unlocker para recuperar su token de API. También puede seguir los pasos que se indican a continuación.

En la página “Panel de usuario” de Bright Data, pulse la opción “Obtener productos proxy”:

Haciendo clic en la opción "Obtener productos proxy

En la tabla de productos, localice la fila denominada “desbloqueador” y haga clic en ella:

⚠️Note: Primero tendrás que crear una nueva zona API de Web Unblocker si aún no lo has hecho. Revisa la documentación de configuración de Web Unblocker para empezar.

En la página del “desbloqueador”, copie su token de API utilizando el icono del portapapeles:

Además, asegúrese de que el conmutador de la esquina superior derecha está activado, lo que indica que el producto Web Unlocker está activo.

En la pestaña “Configuración”, asegúrese de que estas opciones están activadas para una eficacia óptima:

Asegurarse de que las opciones premium de eficacia están activadas.

En el archivo .env, añada la siguiente variable de entorno:

BRIGHT_DATA_WEB_UNLOCKER_API_TOKEN="<YOUR_BRIGHT_DATA_WEB_UNLOCKER_API_TOKEN>"

Sustituya el marcador de posición por su token de API real.

Perfecto. Ahora puede utilizar tanto el SDK de OpenAI como la API Web Unlocker de Bright Data en su proyecto.

Paso nº 6: Crear la función de extracción de contenido de páginas web

Crear una función get_page_content() que:

Lee la variable de entorno BRIGHT_DATA_WEB_UNLOCKER_API_TOKEN
Utiliza solicitudes para enviar una solicitud a la API del Desbloqueador Web de Bright Data utilizando la URL proporcionada.
Recupera el HTML sin procesar devuelto por la API
Convierte el HTML a Markdown y lo devuelve

Así es como se puede implementar la lógica anterior:

@function_tool
def get_page_content(url: str) -> str:
    """
    Retrieves the HTML content of a given web page using Bright Data's Web Unlocker API,
    bypassing anti-bot protections. The response is converted from raw HTML to Markdown
    for easier and cheaper processing.

    Args:
        url (str): The URL of the web page to scrape.

    Returns:
        str: The Markdown-formatted content of the requested page.
    """

    # Read the Bright Data's Web Unlocker API token from the envs
    BRIGHT_DATA_WEB_UNLOCKER_API_TOKEN = os.getenv("BRIGHT_DATA_WEB_UNLOCKER_API_TOKEN")

    # Configure the Web Unlocker API call
    api_url = "https://api.brightdata.com/request"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {BRIGHT_DATA_WEB_UNLOCKER_API_TOKEN}"
    }
    data = {
        "zone": "unblocker",
        "url": url,
        "format": "raw"
    }

    # Make the call to Web Uncloker to retrieve the unblocked HTML of the target page
    response = requests.post(api_url, headers=headers, data=json.dumps(data))

    # Extract the raw HTML response
    html = response.text

    # Convert the HTML to markdown and return it
    markdown_text = md(html)

    return markdown_text

Nota 1: La función debe estar anotada con @function_tool. Este decorador especial indica al SDK de Agentes de OpenAI que esta función puede ser utilizada como herramienta por un agente para realizar acciones específicas. En este caso, la función actúa como el “motor” que el agente puede utilizar para recuperar el contenido de la página web sobre la que operará.

Nota 2: La función get_page_content( ) debe declarar los tipos de entrada explícitamente.
Si los omite, obtendrá un error como Error obteniendo respuesta: Código de error: 400 - {'error': {'mensaje': "Esquema no válido para la función 'get_page_content': In context=('properties', 'url'), schema must have a 'type' key.``"

Tal vez te preguntes: ¿por qué convertir HTML sin formato a Markdown? La respuesta es sencilla: ¡eficacia y rentabilidad!

El HTML es muy prolijo y a menudo incluye elementos innecesarios como scripts, estilos y metadatos. Se trata de contenido que los agentes de IA no suelen necesitar. Si su agente sólo necesita lo esencial, como texto, enlaces e imágenes, Markdown ofrece una representación mucho más limpia y compacta.

En concreto, la transformación de HTML a Markdown puede reducir el tamaño de la entrada hasta en un 99%, con el consiguiente ahorro para ambos:

Tokens, que reducen el coste al utilizar modelos OpenAI
Tiempo de procesamiento, ya que los modelos trabajan más rápido con entradas más pequeñas.

Para más información, lea el artículo “¿Por qué los nuevos agentes de IA eligen Markdown en lugar de HTML?“.

Paso 7: Definir los modelos de datos

Para funcionar correctamente, los agentes del SDK de OpenAI requieren modelos Pydantic para definir la estructura esperada de sus datos de salida. Ahora, recuerda que el agente que estamos construyendo puede devolver una de tres posibles salidas:

Resumen de la página
Información sobre el producto
Información sobre artículos de noticias

Así pues, definamos tres modelos pydánticos correspondientes:

class Summary(BaseModel):
    summary: str

class Product(BaseModel):
    name: str
    price: Optional[float] = None
    currency: Optional[str] = None
    ratings: Optional[int] = None
    rating_score: Optional[float] = None

class News(BaseModel):
    title: str
    subtitle: Optional[str] = None
    authors: Optional[List[str]] = None
    text: str
    publication_date: Optional[str] = None

Nota: El uso de Opcional hace que su agente sea más robusto y de propósito general. No todas las páginas incluirán todos los datos definidos en el esquema, por lo que esta flexibilidad ayuda a evitar errores cuando faltan campos.

No olvide importar Opcional y Lista desde mecanografía:

from typing import Optional, List

Fantástico. Ahora está listo para construir la lógica de su agente.

Paso 8: Inicializar la lógica del Agente

Utilice la clase Agente del SDK openai-agents para definir los tres agentes especializados:

summarization_agent = Agent(
    name="Text Summarization Agent",
    instructions="You are a content summarization agent that summarizes the input text.",
    tools=[get_page_content],
    output_type=Summary,
)

product_info_agent = Agent(
    name="Product Information Agent",
    instructions="You are a product parsing agent that extracts product details from text.",
    tools=[get_page_content],
    output_type=Product,
)

news_info_agent = Agent(
    name="News Information Agent",
    instructions="You are a news parsing agent that extracts relevant news details from text.",
    tools=[get_page_content],
    output_type=News,
)

Cada agente:

Incluye una cadena de instrucciones clara que describe lo que se supone que debe hacer. Esto es lo que el SDK de Agentes OpenAI utilizará para guiar el comportamiento del agente.
Utiliza get_page_content() como herramienta para recuperar los datos de entrada (es decir, el contenido de la página web).
Devuelve su salida en uno de los modelos Pydantic(Resumen, Producto o Noticias) definidos anteriormente.

Para dirigir automáticamente las solicitudes de los usuarios al agente especializado correcto, defina un agente de nivel superior:

routing_agent = Agent(
    name="Routing Agent",
    instructions=(
        "You are a high-level decision-making agent. Based on the user's request, "
        "hand off the task to the appropriate agent."
    ),
    handoffs=[summarization_agent, product_info_agent, news_info_agent],
)

Este es el agente que interrogarás en tu función run() para manejar la lógica del agente AI.

Paso 9: Implementar el bucle de ejecución

En la función run(), añade el siguiente bucle para lanzar la lógica de tu agente de IA:

# Keep iterating until the use type "exit"
while True:
    # Read the user's request
    request = input("Your request -> ")
    # Stops the execution if the user types "exit"
    if request.lower() in ["exit"]:
        print("Exiting the agent...")
        break
    # Read the page URL to operate on
    url = input("Page URL -> ")

    # Routing the user's request to the right agent
    output = await Runner.run(routing_agent, input=f"{request} {url}")
    # Conver the agent's output to a JSON string
    json_output = json.dumps(output.final_output.model_dump(), indent=4)
    print(f"Output -> \n{json_output}\n\n")

Este bucle escucha continuamente la entrada del usuario y procesa cada solicitud dirigiéndola al agente adecuado (resumen, producto o noticias). Combina la consulta del usuario con la URL de destino, ejecuta la lógica y, a continuación, imprime el resultado estructurado en formato JSON utilizando json. Imprímelo con:

import json

¡Sorprendente! La integración de su SDK de Agentes OpenAI con la API Web Unlocker de Bright Data ya está completa.

Paso nº 10: Póngalo todo junto

Tu archivo scraper.py debería contener ahora:

import asyncio
from agents import Agent, RunResult, Runner, function_tool
import requests
from pydantic import BaseModel
from markdownify import markdownify as md
from dotenv import load_dotenv
import os
from typing import Optional, List
import json

# Load the environment variables from the .env file
load_dotenv()

# Define the Pydantic output models for your AI agent
class Summary(BaseModel):
    summary: str

class Product(BaseModel):
    name: str
    price: Optional[float] = None
    currency: Optional[str] = None
    ratings: Optional[int] = None
    rating_score: Optional[float] = None

class News(BaseModel):
    title: str
    subtitle: Optional[str] = None
    authors: Optional[List[str]] = None
    text: str
    publication_date: Optional[str] = None

@function_tool
def get_page_content(url: str) -> str:
    """
    Retrieves the HTML content of a given web page using Bright Data's Web Unlocker API,
    bypassing anti-bot protections. The response is converted from raw HTML to Markdown
    for easier and cheaper processing.

    Args:
        url (str): The URL of the web page to scrape.

    Returns:
        str: The Markdown-formatted content of the requested page.
    """

    # Read the Bright Data's Web Unlocker API token from the envs
    BRIGHT_DATA_WEB_UNLOCKER_API_TOKEN = os.getenv("BRIGHT_DATA_WEB_UNLOCKER_API_TOKEN")

    # Configure the Web Unlocker API call
    api_url = "https://api.brightdata.com/request"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {BRIGHT_DATA_WEB_UNLOCKER_API_TOKEN}"
    }
    data = {
        "zone": "unblocker",
        "url": url,
        "format": "raw"
    }

    # Make the call to Web Uncloker to retrieve the unblocked HTML of the target page
    response = requests.post(api_url, headers=headers, data=json.dumps(data))

    # Extract the raw HTML response
    html = response.text

    # Convert the HTML to markdown and return it
    markdown_text = md(html)

    return markdown_text

# Define the individual OpenAI agents
summarization_agent = Agent(
    name="Text Summarization Agent",
    instructions="You are a content summarization agent that summarizes the input text.",
    tools=[get_page_content],
    output_type=Summary,
)

product_info_agent = Agent(
    name="Product Information Agent",
    instructions="You are a product parsing agent that extracts product details from text.",
    tools=[get_page_content],
    output_type=Product,
)

news_info_agent = Agent(
    name="News Information Agent",
    instructions="You are a news parsing agent that extracts relevant news details from text.",
    tools=[get_page_content],
    output_type=News,
)

# Define a high-level routing agent that delegates tasks to the appropriate specialized agent
routing_agent = Agent(
    name="Routing Agent",
    instructions=(
        "You are a high-level decision-making agent. Based on the user's request, "
        "hand off the task to the appropriate agent."
    ),
    handoffs=[summarization_agent, product_info_agent, news_info_agent],
)

async def run():
    # Keep iterating until the use type "exit"
    while True:
        # Read the user's request
        request = input("Your request -> ")
        # Stops the execution if the user types "exit"
        if request.lower() in ["exit"]:
            print("Exiting the agent...")
            break
        # Read the page URL to operate on
        url = input("Page URL -> ")

        # Routing the user's request to the right agent
        output = await Runner.run(routing_agent, input=f"{request} {url}")
        # Conver the agent's output to a JSON string
        json_output = json.dumps(output.final_output.model_dump(), indent=4)
        print(f"Output -> \n{json_output}\n\n")


if __name__ == "__main__":
    asyncio.run(run())

¡Et voilà! En poco más de 100 líneas de Python, has construido un agente de IA que puede:

Resuma el contenido de cualquier página web
Extraiga información sobre productos de cualquier sitio de comercio electrónico
Extrae detalles de noticias de cualquier artículo en línea

Es hora de verlo en acción.

Paso nº 11: Probar el agente de IA

Para iniciar su agente de IA, ejecute:

python agent.py

Ahora, supongamos que desea resumir el contenido del centro de servicios de IA de Bright Data. Solo tiene que introducir una solicitud como esta:

La entrada para obtener un resumen de los servicios de IA de Bright Data

A continuación se muestra el resultado en formato JSON que obtendrá:

Esta vez, supongamos que desea recuperar los datos de un producto de una página de productos de Amazon, como el listado de PS5:

Normalmente, los sistemas CAPTCHA y anti-bot de Amazon bloquearían su solicitud. Gracias a la API Web Unlocker, tu agente de IA puede acceder a la página y analizarla sin que se bloquee:

La salida será:

{
    "name": "PlayStation\u00ae5 console (slim)",
    "price": 499.0,
    "currency": "USD",
    "ratings": 6321,
    "rating_score": 4.7
}

Estos son los datos exactos del producto de la página de Amazon.

Por último, considere que desea obtener información estructurada de un artículo de Yahoo Noticias:

Consigue tu objetivo con las siguientes aportaciones:

Your request -> Give me news info
Page URL -> https://www.yahoo.com/news/pope-francis-dies-88-080859417.html

El resultado será:

{
    "title": "Pope Francis Dies at 88",
    "subtitle": null,
    "authors": [
        "Nick Vivarelli",
        "Wilson Chapman"
    ],
    "text": "Pope Francis, the 266th Catholic Church leader who tried to position the church to be more inclusive, died on Easter Monday, Vatican officials confirmed. He was 88. (omitted for brevity...)",
    "publication_date": "Mon, April 21, 2025 at 8:08 AM UTC"
}

Una vez más, el agente de IA proporciona datos precisos y, gracias a Web Unlocker, ¡no hay bloqueos del sitio de noticias!

Conclusión

En esta entrada de blog, aprendiste cómo usar el SDK de Agentes OpenAI en combinación con una API de desbloqueo web para construir un agente web altamente efectivo en Python.

Como se ha demostrado, la combinación del SDK de OpenAI con la API Web Unlocker de Bright Data ayuda a crear agentes de IA que pueden funcionar de forma fiable en cualquier página web. Este es solo un ejemplo de cómo los productos y servicios de Bright Data pueden soportar potentes integraciones de IA.

Explore nuestras soluciones para el desarrollo de agentes de IA:

Agentes autónomos de IA: Busque, acceda e interactúe con cualquier sitio web en tiempo real mediante un potente conjunto de API.
Aplicaciones verticales de IA: cree canalizaciones de datos fiables y personalizadas para extraer datos web de fuentes específicas del sector.
Modelos básicos: Acceda a conjuntos de datos compatibles a escala web para potenciar el preentrenamiento, la evaluación y el ajuste.
IA multimodal: aproveche el mayor repositorio del mundo de imágenes, vídeos y audio optimizados para la IA.
Proveedores de datos: Conéctese con proveedores de confianza para obtener conjuntos de datos de alta calidad preparados para la IA a escala.
Paquetes de datos: Obtenga conjuntos de datos curados y listos para usar: estructurados, enriquecidos y anotados.

Para obtener más información, explore nuestra gama completa de productos de IA.

Cree una cuenta de Bright Data y pruebe todos nuestros productos y servicios para el desarrollo de agentes de IA.

Prueba gratuita

Iniciar grátis com o Google

No se requiere tarjeta de crédito

Integración del SDK de agentes de OpenAI con un desbloqueador web para obtener un alto rendimiento