Tipos de Workers

Existen 5 tipos de workers, cada uno diseñado para un caso de uso diferente. El tipo se define por la funcion define* que utilices.

Tabla comparativa

Tipo	Funcion	Trigger	Uso principal
Tool	`defineTool`	El agente IA lo invoca	Consultas a APIs durante conversaciones
Worker	`defineWorker`	Bajo demanda (API, acciones, otros workers)	Logica de negocio reutilizable
Sync	`defineSync`	Cron programado	Sincronizacion periodica de datos
Schedule	`defineSchedule`	Cron programado	Tareas automaticas recurrentes
Webhook	`defineWebhook`	HTTP request externo	Recibir eventos de servicios externos

Tool (`defineTool`)

Herramientas que el agente IA puede invocar durante una conversacion. Ideales para consultas a APIs externas, busquedas en base de datos, o cualquier operacion en tiempo real. Campos de configuracion:

Campo	Tipo	Descripcion
`name`	`string`	Nombre unico del tool.
`reference`	`string`	Descripcion para que el agente entienda cuando usarlo.
`agents`	`string[]`	IDs de los agentes que pueden invocar este tool.
`parameters`	`array`	Parametros que el agente debe recopilar del usuario.

Signature del handler:

async run(payload, plz) {
  // payload contiene los parametros + contactId
  // Retorna datos que el agente usara en su respuesta
  return { ... }
}

Cada parametro tiene:

Campo	Tipo	Descripcion
`name`	`string`	Nombre del parametro.
`type`	`string`	Tipo: `string`, `number`, `array`, `boolean`.
`description`	`string`	Descripcion para que el agente sepa que pedir al usuario.
`example`	`string`	Ejemplo de pregunta que el agente puede hacer.

Ejemplo:

import { defineTool } from 'plz/workers'

export default defineTool({
  name: 'consultar-stock',
  reference: 'Consulta disponibilidad de productos en inventario',
  agents: ['agent_abc123'],
  parameters: [
    { name: 'producto', type: 'string', description: 'Nombre del producto' }
  ],

  async run(payload, plz) {
    const res = await fetch(`${plz.env.API_URL}/stock?q=${payload.producto}`)
    return await res.json()
  }
})

Worker (`defineWorker`)

Funciones de proposito general invocadas bajo demanda. Se ejecutan desde automatizaciones, acciones del agente (action.worker), otros workers o la API. Campos de configuracion:

Campo	Tipo	Descripcion
`name`	`string`	Nombre unico del worker.
`reference`	`string`	Descripcion del proposito.

Signature del handler:

async run(payload, plz) {
  // payload contiene los datos enviados al ejecutar
  // payload.contactId y payload.contact disponibles si se invoca desde una accion
  return { ... }
}

Ejemplo:

import { defineWorker } from 'plz/workers'

export default defineWorker({
  name: 'notificar-equipo',
  reference: 'Envia notificacion al equipo por Slack',

  async run(payload, plz) {
    const { contactId, mensaje } = payload

    plz.log.info('Enviando notificacion', { contactId })

    await fetch(plz.env.SLACK_WEBHOOK, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ text: mensaje })
    })

    return { success: true }
  }
})

Este es el unico tipo de worker que puede ser invocado desde las acciones del agente de IA usando action.worker.

Sync (`defineSync`)

Sincronizaciones programadas que mantienen datos actualizados entre la plataforma y sistemas externos. Se ejecutan en intervalos regulares via cron. Campos de configuracion:

Campo	Tipo	Descripcion
`name`	`string`	Nombre unico del sync.
`reference`	`string`	Descripcion del proposito.
`cron`	`string`	Expresion cron que define la frecuencia.
`timezone`	`string`	Zona horaria para el cron (ej: `America/Mexico_City`).

Signature del handler:

async run(plz) {
  // No recibe payload - se ejecuta automaticamente
  return { ... }
}

Ejemplo:

import { defineSync } from 'plz/workers'

export default defineSync({
  name: 'sync-crm-contacts',
  reference: 'Sincroniza contactos modificados en el CRM',
  cron: '*/30 * * * *',
  timezone: 'America/Lima',

  async run(plz) {
    const contacts = await plz.contacts.list({ limit: 100 })
    // ... logica de sincronizacion
    return { synced: 15 }
  }
})

Schedule (`defineSchedule`)

Tareas programadas que se ejecutan automaticamente en horarios definidos. Utiles para reportes, limpiezas, notificaciones periodicas y mas. Campos de configuracion:

Campo	Tipo	Descripcion
`name`	`string`	Nombre unico del schedule.
`reference`	`string`	Descripcion del proposito.
`cron`	`string`	Expresion cron que define cuando se ejecuta.
`timezone`	`string`	Zona horaria para el cron.

Signature del handler:

async run(plz) {
  // No recibe payload - se ejecuta automaticamente
  return { ... }
}

La diferencia entre defineSync y defineSchedule es conceptual: sync se usa para sincronizar datos entre sistemas, schedule para tareas autonomas. Tecnicamente funcionan igual.

Ejemplo:

import { defineSchedule } from 'plz/workers'

export default defineSchedule({
  name: 'reporte-diario',
  reference: 'Envia resumen diario de chats pendientes',
  cron: '0 22 * * 1-5',
  timezone: 'America/Mexico_City',

  async run(plz) {
    const contacts = await plz.contacts.list({ limit: 200 })
    const pending = contacts.filter(c => !c.isSolved)
    // ... enviar reporte
    return { pending: pending.length }
  }
})

Webhook (`defineWebhook`)

Endpoints HTTP que reciben eventos de servicios externos en tiempo real. Al desplegarse, se genera una URL unica que puedes configurar en el servicio externo. Campos de configuracion:

Campo	Tipo	Descripcion
`name`	`string`	Nombre unico del webhook.
`reference`	`string`	Descripcion del proposito.
`method`	`string`	Metodo HTTP aceptado: `POST`, `GET`, `PUT`.

Signature del handler:

async run(payload, plz) {
  // payload contiene el body del request HTTP
  return { ... }
}

Ejemplo:

import { defineWebhook } from 'plz/workers'

export default defineWebhook({
  name: 'webhook-pagos',
  reference: 'Recibe eventos de pago de Stripe',
  method: 'POST',

  async run(payload, plz) {
    if (payload.type !== 'checkout.session.completed') {
      return { ignored: true }
    }

    const email = payload.data.object.customer_details.email
    const matches = await plz.contacts.search({ email })

    if (matches.length > 0) {
      await plz.contacts.addTag(matches[0].id, 'cliente-pagado')
    }

    return { success: true }
  }
})

Al desplegar un webhook, el sistema genera automaticamente una URL. Puedes verla en el dashboard o con plazbot workers list. Usa esa URL para configurar el webhook en el servicio externo (Stripe, Shopify, etc).

Expresiones Cron

Los workers de tipo sync y schedule usan expresiones cron para definir su frecuencia de ejecucion.

Expresion	Significado
`/5 * * *`	Cada 5 minutos
`/30 * * *`	Cada 30 minutos
`0 * * * *`	Cada hora en punto
`0 9 * * *`	Todos los dias a las 9:00
`0 22 * * 1-5`	Lunes a viernes a las 22:00
`0 0 * * 0`	Domingos a medianoche
`0 /6 * *`	Cada 6 horas

El campo timezone determina en que zona horaria se evalua la expresion cron. Valores comunes:

America/Mexico_City
America/Lima
America/Bogota
America/Santiago
America/Argentina/Buenos_Aires

Introducción

Primeros Pasos

Contactos

Agente de IA

Marketing

Partners Marca Blanca

Legal

Tabla comparativa

Tool (`defineTool`)

Worker (`defineWorker`)

Sync (`defineSync`)

Schedule (`defineSchedule`)

Webhook (`defineWebhook`)

Expresiones Cron

​Tabla comparativa

​Tool (defineTool)

​Worker (defineWorker)

​Sync (defineSync)

​Schedule (defineSchedule)

​Webhook (defineWebhook)

​Expresiones Cron

Tabla comparativa

Tool (`defineTool`)

Worker (`defineWorker`)

Sync (`defineSync`)

Schedule (`defineSchedule`)

Webhook (`defineWebhook`)

Expresiones Cron