En esta entrada del blog, verás:
- Qué es la especificación OpenAPI.
- Por qué es tan popular para la definición de herramientas en marcos y plataformas de IA.
- Cómo Bright Data es compatible con OpenAPI para simplificar la integración en agentes y flujos de trabajo de IA.
- La especificación OpenAPI de la API Web Unlocker de Bright Data.
- La especificación OpenAPI de la API SERP de Bright Data.
- Cómo funcionan estas especificaciones en la práctica dentro de una plataforma de IA real.
¡Vamos a profundizar en ello!
¿Qué es la especificación OpenAPI?
La especificación OpenAPI (OAS) es un estándar abierto e independiente del lenguaje para describir API RESTful. Proporciona un formato estructurado y legible por máquina (normalmente YAML o JSON) para definir las operaciones, los parámetros, las respuestas, los esquemas de seguridad y otras características de una API.
¡Explora el repositorio GitHub para ver la especificación!
Nota: La especificación OpenAPI se llamaba originalmente «especificación Swagger». Por lo tanto, si está buscando «especificaciones Swagger de Bright Data», ¡está en el lugar adecuado!
Por qué muchas soluciones de IA se basan en las especificaciones OpenAPI para la definición de herramientas
Muchos marcos de IA adoptan el soporte de OpenAPI para la definición de herramientas. La razón principal es que la especificación OpenAPI proporciona un contrato estandarizado y legible por máquina que describe exactamente lo que hace una API externa.
Esa estandarización ofrece tres ventajas principales:
- Interoperabilidad y fricción mínima: OpenAPI es un estándar ampliamente compatible. Una vez que se proporciona una especificación, la plataforma puede importar automáticamente la API, generar formularios de entrada, llamadas y gestión de respuestas, e integrarla en sus herramientas.
- Curva de aprendizaje reducida: incluso los usuarios sin conocimientos técnicos pueden crear herramientas utilizando API simplemente copiando las especificaciones OpenAPI de la documentación u otras fuentes. Por lo tanto, no es necesario realizar conexiones manuales ni codificación, por lo que el soporte OpenAPI es tan común en las plataformas de IA de bajo código o sin código.
- Mejor mantenimiento: con un contrato API explícito, las actualizaciones son fáciles. Cuando la API evoluciona, solo es necesario actualizar la especificación en la definición de la herramienta, lo que simplifica enormemente el mantenimiento y reduce la necesidad de grandes reescrituras.
En resumen, la definición de herramientas a través de OpenAPI abre la puerta a un ecosistema preparado para la empresa, en el que los CRM, los proveedores de datos, las API internas y otros servicios externos pueden conectarse, documentarse y mantenerse de forma segura con una mínima sobrecarga manual en los agentes de IA, los procesos y los flujos de trabajo.
Presentamos las especificaciones OpenAPI de Bright Data
Bright Data incluye un conjunto de productos y servicios para la extracción de datos web, la interacción web automatizada, el rastreo web y mucho más.
Estas soluciones están disponibles a través de API (y también a través de opciones sin código), lo que significa que se pueden configurar utilizando las especificaciones OpenAPI en plataformas de IA que admitan esta función.
En este artículo, nos centraremos en dos de las herramientas más importantes de Bright Data:
- API SERP: extrae automáticamente datos estructurados de motores de búsqueda como Google, Bing y Yandex. Se encarga de tareas complejas como la gestión de Proxies, la Resolución de CAPTCHA y la representación de JavaScript, lo que le permite obtener resultados limpios y en tiempo real en formato JSON o HTML sin ser bloqueado.
- API Web Unlocker: evita medidas antibots complejas (como CAPTCHAs, bloqueos de IP y huellas digitales) para extraer datos web de cualquier página web. Actúa como intermediario, gestionando Proxies, emulando usuarios reales y proporcionando respuestas limpias en HTML, JSON y Markdown.
Para cada servicio, verá la especificación OpenAPI 3.x en formatos YAML y JSON, así como ejemplos de pruebas en Swagger Editor.
A partir de estas especificaciones, puede convertir de forma similar las API de Scraping web y otros puntos finales de API en especificaciones OpenAPI para la integración de IA.
Nota: Algunos productos de Bright Data comparten los mismos puntos finales de API, cambiando el comportamiento solo en función del cuerpo de la solicitud. Dado que no se pueden definir dos especificaciones completamente separadas para la misma ruta y método en un único documento OpenAPI, se necesitan especificaciones OpenAPI separadas. Por eso proporcionaremos dos especificaciones OpenAPI dedicadas tanto para la API SERP como para la API Web Unlocker (ya que comparten el mismo punto final).
Especificación OpenAPI de la API Web Unlocker
Descubra la especificación OpenAPI para la API Web Unlocker de Bright Data.
Nota: Para obtener más detalles, consulte los argumentos, opciones, métodos de autenticación y mucho más disponibles en las siguientes páginas de documentación:
Especificación YAML
Esta es la especificación YAML de OpenAPI para la API Web Unlocker de Bright Data:
openapi: 3.0.4
info:
title: Web Unlocker de Bright Data
version: 1.0.0
description: |
La API Web Unlocker de Bright Data le permite eludir las medidas antibots, gestionar Proxies y realizar la resolución de CAPTCHA automáticamente para facilitar la recopilación de datos web.
[Documentación de la API Web Unlocker](https://docs.brightdata.com/scraping-automation/web-unlocker/introduction)
contact:
name: Bright Data
url:
servers:
- url: https://api.brightdata.com
tags:
- name: Web Unlocker
description: Operaciones para interactuar con la API de Bright Data Web Unlocker.
componentes:
esquemas de seguridad:
BearerAuth:
tipo: http
esquema: portador
formato del portador: BRIGHT_DATA_API_KEY
rutas:
/solicitud:
publicar:
operationId: sendWebUnlockerRequest
resumen: Enviar una solicitud de API de Web Unlocker
descripción: |
Enviar una solicitud a la API Web Unlocker utilizando su zona de la API Web Unlocker de Bright Data.
[Documentación de la API Web Unlocker `/request`](https://docs.brightdata.com/api-reference/rest-api/unlocker/unlock-website)
etiquetas:
- Web Unlocker
seguridad:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- zone
- url
- format
properties:
zone:
type: string
description: El nombre de su zona de Web Unlocker.
url:
type: string
description: La URL del sitio web de destino que se va a desbloquear y recuperar.
ejemplo: https://example.com/products
formato:
tipo: cadena
descripción: |
Formato de respuesta.
Valores permitidos:
- `raw`: Devuelve la respuesta inmediatamente en el cuerpo.
- `json`: Devuelve la respuesta como un objeto JSON estructurado.
predeterminado: raw
método:
tipo: cadena
descripción: Método HTTP utilizado al recuperar la URL de destino.
ejemplo: GET
país:
tipo: cadena
descripción: |
Código de país para la ubicación del Proxy (formato ISO 3166-1 alfa-2).
ejemplo: us
formato_de_datos:
tipo: cadena
descripción: |
Formato de los datos de salida extraídos.
Valores permitidos:
- `markdown`: Contenido de la página convertido a Markdown.
- `screenshot`: Para capturar una imagen PNG de la página renderizada.
enum:
- markdown
- screenshot
responses:
"200":
description: Respuesta satisfactoria que contiene los resultados de la búsqueda.
"400":
descripción: Solicitud no válida (faltan campos obligatorios o parámetros no válidos).
"401":
descripción: No autorizado (clave API de Bright Data no válida o faltante).Nota:
La sección securitySchemes especifica un esquema de seguridad que utiliza la autenticación HTTP bearer. En concreto, los clientes deben enviar una BRIGHT_DATA_API_KEY como token bearer en el encabezado Authorization al llamar a la API.
Al mismo tiempo, la mayoría de las plataformas de IA ya incluyen métodos de autenticación integrados y pueden ignorar ese campo de especificación. Aun así, es útil incluirlo en la especificación OpenAPI para mayor claridad y como referencia.
Especificación JSON
A continuación se muestra la especificación JSON OpenAPI para la API Web Unlocker:
{
"openapi": "3.0.4",
"info": {
"title": "Bright Data Web Unlocker API",
"version": "1.0.0",
"description": "Bright Data Unlocker API le permite eludir las medidas antibots, gestionar Proxies y realizar la resolución de CAPTCHA automáticamente para facilitar la recopilación de datos web.nn[Documentación de la API Web Unlocker](https://docs.brightdata.com/scraping-automation/web-unlocker/introduction)n",
"contact": {
"name": "Bright Data",
"url": ""
}
},
"servers": [
{
"url": "https://api.brightdata.com"
}
],
"tags": [
{
"name": "Web Unlocker",
"description": "Operaciones para interactuar con la API Web Unlocker de Bright Data."
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "BRIGHT_DATA_API_KEY"
}
}
},
"paths": {
"/request": {
"post": {
"operationId": "sendWebUnlockerRequest",
"summary": "Enviar una solicitud a la API de Web Unlocker",
"description": "Enviar una solicitud a la API de Web Unlocker utilizando su zona de la API de Bright Data Web Unlocker. nn[Documentación de la API de Web Unlocker `/request`](https://docs.brightdata.com/api-reference/rest-api/unlocker/unlock-website)n",
"tags": [
"Web Unlocker"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"zone",
"url",
"format"
],
"properties": {
"zone": {
"type": "string",
"description": "El nombre de su zona de Web Unlocker."
},
"url": {
"type": "string",
"description": "La URL del sitio web de destino para desbloquear y recuperar.",
"example": "https://example.com/products"
},
"format": {
"type": "string",
"description": "Formato de respuesta. nValores permitidos: n- `raw`: Devuelve la respuesta inmediatamente en el cuerpo. n- `json`: Devuelve la respuesta como un objeto JSON estructurado. n»,
«default»: «raw»
},
«method»: {
«type»: «string»,
«description»: «Método HTTP utilizado al recuperar la URL de destino.»,
"example": "GET"
},
"country": {
"type": "string",
"description": "Código de país para la ubicación del Proxy (formato ISO 3166-1 alfa-2). n",
"example": "us"
},
"data_format": {
"type": "string",
"description": "Formato de los datos de salida extraídos. nValores permitidos:n- `markdown`: Contenido de la página convertido a Markdown.n- `screenshot`: Para capturar una imagen PNG de la página renderizada.n",
"enum": [
"markdown",
"screenshot"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Respuesta satisfactoria que contiene los resultados de la búsqueda."
},
"400": {
"description": "Solicitud no válida (faltan campos obligatorios o parámetros no válidos)."
},
"401": {
"description": "No autorizado (clave API de Bright Data no válida o faltante)."
}
}
}
}
}
}Prueba en Swagger Editor
Prueba la especificación OpenAPI pegándola en Swagger Editor:
Especificación OpenAPI de la API SERP
Explore la especificación OpenAPI para la API SERP de Bright Data.
Nota: Para obtener más información, consulte los argumentos, las opciones, los métodos de autenticación y mucho más en las siguientes páginas de documentación:
Especificación YAML
Aquí está la especificación YAML de OpenAPI para la API SERP:
openapi: 3.0.4
info:
title: API SERP de Bright Data
version: 1.0.0
description: |
Extraiga los resultados del motor de búsqueda utilizando la API SERP de Bright Data. Extraiga datos estructurados de los principales motores de búsqueda, incluidos Google, Bing, Yandex, DuckDuckGo y muchos más.
Obtenga resultados orgánicos, anuncios pagados, listados locales, resultados de compras y otras funciones SERP.
[Documentación de la API SERP](https://docs.brightdata.com/scraping-automation/serp-api/introduction)
contacto:
nombre: Bright Data
url:
servidores:
- url: https://api.brightdata.com
etiquetas:
- nombre: SERP
descripción: Operaciones relacionadas con la API SERP de Bright Data.
componentes:
esquemas de seguridad:
BearerAuth:
tipo: http
esquema: bearer
formato bearer: BRIGHT_DATA_API_KEY
rutas:
/solicitud:
post:
operationId: sendSerpRequest
resumen: Enviar una solicitud de API SERP
descripción: |
Enviar una solicitud de API SERP utilizando su zona de API SERP de Bright Data.
[Documentación de la API SERP `/request`](https://docs.brightdata.com/api-reference/rest-api/serp/scrape-serp)
etiquetas:
- SERP
seguridad:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- zone
- url
- format
properties:
zone:
type: string
description: El nombre de su zona API SERP.
url:
tipo: cadena
descripción: La URL del motor de búsqueda que se va a consultar (por ejemplo, `https://www.google.com/search?q=<search_query>`).
ejemplo: https://www.google.com/search?q=pizza&hl=en&gl=us
formato:
tipo: cadena
descripción: |
Formato de respuesta.
Valores permitidos:
- `raw`: Devuelve la respuesta inmediatamente en el cuerpo.
- `json`: Devuelve la respuesta como un objeto JSON estructurado.
predeterminado: raw
enumeración:
- raw
- json
país:
tipo: cadena
descripción: |
Código de país para la ubicación del Proxy (formato ISO 3166-1 alfa-2).
ejemplo: us
data_format:
tipo: cadena
descripción: |
Formato de los datos de salida SERP.
Valores permitidos:
- `json`: Datos JSON totalmente parseados con resultados SERP estructurados, incluyendo fragmentos orgánicos, pagados, locales, de compras y destacados.
- `markdown`: Contenido SERP convertido a Markdown.
enum:
- json
- markdown
respuestas:
"200":
descripción: Respuesta satisfactoria que contiene los resultados de la búsqueda.
"400":
descripción: Solicitud no válida (faltan campos obligatorios o parámetros no válidos).
"401":
descripción: No autorizado (clave API de Bright Data no válida o faltante).Especificación JSON
Esta es la especificación JSON OpenAPI para la API SERP:
{
"openapi": "3.0.4",
"info": {
"title": "API SERP de Bright Data",
"version": "1.0.0",
"description": "Extraiga resultados de motores de búsqueda utilizando la API SERP de Bright Data. Extraiga datos estructurados de los principales motores de búsqueda, incluidos Google, Bing, Yandex, DuckDuckGo y muchos más. nObtenga resultados orgánicos, anuncios pagados, listados locales, resultados de compras y otras funciones SERP.n[Documentación de la API SERP](https://docs.brightdata.com/scraping-automation/serp-api/introduction)n",
"contact": {
"name": "Bright Data",
"url": ""
}
],
"servers": [
{
"url": "https://api.brightdata.com"
}
],
"tags": [
{
"name": "SERP",
"description": "Operaciones relacionadas con la API SERP de Bright Data."
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "BRIGHT_DATA_API_KEY"
}
}
},
"paths": {
"/request": {
"post": {
"operationId": "sendSerpRequest",
"summary": "Enviar una solicitud de API SERP",
"description": "Enviar una solicitud de API SERP utilizando su zona de API SERP de Bright Data. nn[Documentación de la API SERP `/request`](https://docs.brightdata.com/api-reference/rest-api/serp/scrape-serp)n»,
«tags»: [
«SERP»
],
«security»: [
{
«BearerAuth»: []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"zone",
"url",
"format"
],
"properties": {
"zone": {
"type": "string",
"description": "El nombre de su zona API SERP."
},
"url": {
"type": "string",
"description": "La URL del motor de búsqueda al que se va a consultar (por ejemplo, `https://www.google.com/search?q=<search_query>`).",
"example": "https://www.google.com/search?q=pizza&hl=en&gl=us"
},
"format": {
"type": "string",
"description": "Formato de respuesta. nValores permitidos: n- `raw`: Devuelve la respuesta inmediatamente en el cuerpo. n- `json`: Devuelve la respuesta como un objeto JSON estructurado. n",
"default": "raw",
"enum": [
"raw",
"json"
]
},
"country": {
"type": "string",
"description": "Código de país para la ubicación del Proxy (formato ISO 3166-1 alfa-2). n",
"example": "us"
},
"data_format": {
"type": "string",
"description": "Formato de los datos de salida SERP. nValores permitidos:n- `json`: Datos JSON completamente analizados con resultados SERP estructurados, incluyendo fragmentos orgánicos, pagados, locales, de compras y destacados.n- `markdown`: Contenido SERP convertido a Markdown. n",
"enum": [
"json",
"markdown"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Respuesta satisfactoria que contiene los resultados de la búsqueda."
},
"400": {
"description": "Solicitud no válida (faltan campos obligatorios o parámetros no válidos)."
},
"401": {
"description": "No autorizado (clave API de Bright Data no válida o faltante)."
}
}
}
}
}
}Prueba en Swagger Editor
Para probar esta especificación, péguela en el editor Swagger en línea:
Prueba de las especificaciones OpenAPI de Bright Data para la integración de herramientas en Dify
Para verificar que las especificaciones OpenAPI anteriores para conectarse a los servicios de Bright Data a través de la API funcionan, las probaremos en Dify.
Concretamente, probaremos la especificación OpenAPI de la API SERP de Bright Data, pero puede adaptar fácilmente esta sección guiada a otras especificaciones SERP de la API Web Unlocker.
Dify es una plataforma de desarrollo de código abierto y bajo código que simplifica la creación, implementación y gestión de aplicaciones basadas en IA. Entre sus muchas características, permite definir herramientas personalizadas utilizando especificaciones OpenAPI.
Esta capacidad no es exclusiva de Dify. Al contrario, muchas otras plataformas de creación de agentes de IA, especialmente las soluciones de bajo código/sin código o las soluciones preparadas para empresas, también admiten la integración de herramientas a través de especificaciones OpenAPI.
Explora integraciones adicionales con Bright Data a través de las especificaciones OpenAPI en las siguientes guías:
- Integrar la API SERP de Bright Data en un agente de IA en Microsoft Copilot Studio
- Integra la API SERP de Bright Data en un agente de IA en IBM watsonx
Ahora, probemos las especificaciones OpenAPI de Bright Data en Dify.
Requisitos previos
Para seguir esta sección del tutorial, necesitas:
- Una cuenta de Bright Data con una clave API y una zona API SERP configurada.
- Una cuenta de Dify Cloud para utilizar la versión en la nube, o una instancia local de Dify ejecutándose en su máquina.
Sigue la guía oficial para generar una clave API de Bright Data. Guárdala en un lugar seguro, ya que la necesitaremos para autenticar las llamadas a la herramienta API SERP.
A continuación, siga las instrucciones de la documentación de Bright Data para configurar una zona API SERP en su cuenta:
A partir de ahora, daremos por hecho que su zona API SERP se llama serp_api. Asegúrese de adaptar el nombre de la zona en los ejemplos para que coincida con el nombre de su zona.
Paso n.º 1: crear una nueva herramienta personalizada
Inicie sesión en su cuenta de Dify Cloud o inicie su instancia local. Para crear una nueva herramienta personalizada, comience seleccionando la opción «Herramientas» en el menú superior:
En la página «Herramientas», vaya a la pestaña «Personalizadas»:
En la pestaña «Personalizada», haga clic en la tarjeta «Crear herramienta personalizada»:
Aparecerá el siguiente modal «Crear herramienta personalizada»:
¡Genial! Aquí es donde pegará su especificación OpenAPI de la API SERP de Bright Data.
Paso n.º 2: definir la herramienta API SERP utilizando la especificación OpenAPI
En el modal «Crear herramienta personalizada», asigne un nombre a la herramienta, como «API SERP». En el campo «Esquema», pegue la especificación YAML OpenAPI para la API SERP de Bright Data.
Debería ver algo como esto:
Tenga en cuenta que la sección «Herramientas disponibles» se rellena automáticamente en función de la definición proporcionada en la especificación OpenAPI.
Como se anticipó anteriormente, la mayoría de las plataformas requieren que se defina la autenticación a través de un método integrado. En este caso, para hacerlo, haga clic en el icono de engranaje en la sección «Método de autenticación»:
Configure la autenticación de la siguiente manera:
- Tipo de autenticación: «Header»
- Tipo: «Portador»
- Clave: «Autorización»
- Valor: pegue su clave API de Bright Data
Esto configura la autenticación a través de un encabezado de autorización, que se enviará como:
Bearer <SU_CLAVE_DE_API_DE_BRIGHT_DATA>Ese es precisamente el método de autenticación compatible con las API de Bright Data.
¡Genial! La herramienta API SERP ya está definida y configurada correctamente.
Paso n.º 3: Prueba la herramienta
En la sección «Herramientas disponibles», localice la fila del punto final /request configurado y haga clic en el botón «Probar»:
Se abrirá el modal «Probar sendSerpRequest», donde podrá personalizar los parámetros y valores para verificar que la herramienta configurada funciona.
Por ejemplo, comience probando una respuesta básica en formato JSON. El resultado esperado es una respuesta JSON estructurada que contenga la página SERP extraída de Google en formato HTML (el formato de datos predeterminado de la API SERP):
Desplácese hacia abajo hasta la sección «Resultados de la prueba» para ver la respuesta de la API. Verá que el campo del cuerpo en JSON contiene el HTML de la página SERP como se esperaba:
¡Fantástico! Este resultado coincide con las expectativas.
Ahora, intente obtener la versión Markdown de la misma página directamente en el cuerpo de la respuesta:
Observe cómo, esta vez, la respuesta es texto sin formato (porque format: raw) que contiene los datos SERP en formato Markdown (debido a data_format: markdown),listos para su ingestión en LLM.
Ahora que sabe que la herramienta funciona (porque llama correctamente a la API subyacente), puede integrarla en cualquier flujo de trabajo de Dify o agente de IA.
¡Et voilà! La herramienta Bright Data definida a través de la especificación OpenAPI funciona perfectamente.
Conclusión
En este artículo, ha aprendido por qué las plataformas y bibliotecas de IA le permiten utilizar especificaciones OpenAPI para la definición de herramientas y cómo Bright Data admite esta opción. En concreto, ha visto las especificaciones OpenAPI para las soluciones Web Unlocker y API SERP de Bright Data.
Al integrar estas dos herramientas, puede crear agentes de IA complejos que buscan en la web y recuperan datos web para RAG, investigación profunda y muchas otras tareas. Aproveche el conjunto completo de servicios API de Bright Data para IA y libere todo el potencial de sus agentes.
¡Crea hoy mismo una cuenta gratuita en Bright Data y empieza a integrar nuestras API para la recuperación de datos web!
