Apify Actors

Apify Actors es un componente que permite a los usuarios de Nappai lanzar y gestionar Apify Actors, que son scripts preconstruidos para extraer datos de la web, automatizar procesos y mucho más. Con este componente, puedes ejecutar un Actor, pasarle la configuración necesaria, filtrar los campos que quieres conservar y, opcionalmente, aplanar la estructura de los datos resultantes. Además, el componente puede generar una herramienta (Tool) que los agentes de IA de Nappai pueden usar para ejecutar el Actor directamente desde sus flujos de trabajo.

¿Cómo funciona?

El componente se conecta a la API de Apify usando el token que el usuario ha guardado en la credencial Apify. Cuando se ejecuta, el flujo es el siguiente:

1. Preparación: Se lee la configuración JSON (Run input) y se convierte en un diccionario.
2. Llamada al Actor: Se envía la solicitud a la API de Apify con el actor_id y el JSON de entrada.
3. Seguimiento: Se sigue el log del run en tiempo real y se espera a que termine.
4. Descarga del dataset: Una vez finalizado, se recupera el dataset generado por el Actor.
5. Filtrado y aplanado:
   • Si se especifican Output fields, solo se extraen esos campos.
   • Si Flatten output está activado, cualquier estructura anidada se convierte en una sola capa con claves separadas por guiones bajos.
6. Salida:
   • Output: Una lista de objetos Data que contienen los registros finales.
   • Tool: Una herramienta que los agentes de IA pueden invocar para ejecutar el mismo Actor con nuevos parámetros.

Entradas

Campos de Entrada

• Actor
  Identificador del Apify Actor que quieres ejecutar (por ejemplo, apify/website-content-crawler). Puedes encontrar los IDs en el Apify Store: https://apify.com/store.

• Output fields
  Lista de campos que deseas extraer del dataset del Actor, separados por comas.

  • Si lo dejas vacío, se devuelven todos los campos.
  • Usa notación de punto para campos anidados (metadata.title). Los puntos se convierten en guiones bajos (metadata_title).
  • Ejemplo: text, url, metadata.title.

• Flatten output
  Si está activado, convierte cualquier clave anidada en una sola capa ({'a': {'b': 1}} → {'a_b': 1}). Esto facilita el procesamiento posterior.

• Run input
  JSON que define la configuración específica del Actor.

  • Revisa la documentación del Actor en Apify para saber qué parámetros necesita.
  • Ejemplo para apify/website-content-crawler:

  {
      "startUrls": [
          {
              "url": "https://docs.apify.com/academy/web-scraping-for-beginners"
          }
      ],
      "maxCrawlDepth": 0
  }

Nota: El token de Apify se gestiona a través de la credencial Apify. Antes de usar el componente, asegúrate de haber configurado la credencial en la sección de credenciales de Nappai y de seleccionarla en el campo “Credential” del componente.

Salidas

• Output
  Una lista de objetos Data que contienen los registros finales del dataset. Cada registro es un diccionario con los campos que seleccionaste (o todos los campos si no se especificó ninguno).

• Tool
  Una herramienta que los agentes de IA pueden usar para ejecutar el mismo Actor con nuevos parámetros. La herramienta devuelve el resultado como texto formateado en JSON.

Ejemplo de Uso

Supongamos que quieres extraer el contenido de la página de documentación de Apify y solo te interesa el texto y la URL. En el dashboard:

1. Selecciona la credencial Apify.

2. Actor: apify/website-content-crawler.

3. Run input:

   {
       "startUrls": [
           {
               "url": "https://docs.apify.com/academy/web-scraping-for-beginners"
           }
       ],
       "maxCrawlDepth": 0
   }

4. Output fields: text, url.

5. Flatten output: desactivado (por defecto).

6. Ejecuta el componente.

7. En la salida Output verás algo parecido a:

   [
       {
           "text": "Welcome to the Apify Academy...",
           "url": "https://docs.apify.com/academy/web-scraping-for-beginners"
       },
       ...
   ]

Si quieres usar el Actor dentro de un agente de IA, selecciona la salida Tool y pásala al flujo de tu agente. El agente podrá invocar el Actor con nuevos parámetros y recibir el resultado como texto.

Componentes Relacionados

• Apify Dataset Loader – Se utiliza internamente para leer el dataset del Actor.
• Apify Actor Builder – Si necesitas crear tus propios Actors, este componente te permite diseñarlos y publicarlos en Apify.

Consejos y Mejores Prácticas

• Limita la cantidad de datos: Si solo necesitas unas pocas columnas, especifica Output fields para reducir el tamaño de la respuesta.
• Aplana solo cuando sea necesario: El aplanado puede simplificar el procesamiento, pero también puede perder la jerarquía de los datos.
• Revisa la documentación del Actor: Cada Actor tiene requisitos de entrada diferentes; usar un JSON incorrecto puede hacer que el run falle.
• Controla los logs: El componente muestra los logs en tiempo real; revisa el panel de logs para depurar problemas.
• Usa credenciales seguras: Nunca expongas tu token de Apify en el código; confía en la gestión de credenciales de Nappai.

Consideraciones de Seguridad

• Confidencialidad del token: El token de Apify se almacena en la credencial y no se muestra en el panel de configuración.
• Acceso restringido: Solo los usuarios con permisos de edición pueden cambiar la credencial o el Actor.
• Auditoría: Los logs de ejecución se guardan en el historial de Nappai, lo que permite rastrear quién ejecutó qué Actor y cuándo.

---