Tipos de workers

Hay cinco tipos de workers y cada uno se activa de una forma distinta. El tipo lo define la función que usas en el código:

Tipo	Función	Cuándo se ejecuta	`run` recibe
Tool	`defineTool`	Tu agente de IA la usa cuando la necesita	`payload, plz`
Webhook	`defineWebhook`	Otro sistema hace un POST a su URL	`payload, plz`
Schedule	`defineSchedule`	Corre solo, según un horario (cron)	`plz`
Sync	`defineSync`	Por horario, y recuerda hasta dónde llegó	`plz`
Worker	`defineWorker`	La acción Ejecutar Worker del agente o la API	`payload, plz`

Importante: plz.contacts, plz.whatsapp y las demás llamadas a datos de Plazbot necesitan los secrets PLZ_API_KEY y PLZ_ZONE (ver Secrets). plz.fetch, plz.log, plz.kv y plz.env funcionan sin ellos.

Tool: una herramienta para tu agente

01import { defineTool } from 'plz/workers'
02 
03export default defineTool({
04  name: 'consultar-pedido',
05  reference: 'Consulta el estado de un pedido cuando el cliente da su numero',
06  agents: ['agt_1x8r3w'],
07  parameters: [
08    { name: 'numeroPedido', type: 'string', description: 'Numero de pedido', example: 'Cual es tu pedido?' }
09  ],
10 
11  async run(payload, plz) {
12    const { numeroPedido, contactId } = payload
13    plz.log.info('Consultando pedido', { numeroPedido, contactId })
14    const res = await plz.fetch(`https://api.tutienda.com/pedidos/${numeroPedido}`)
15    if (!res.ok) return { result: `No encontre el pedido ${numeroPedido}` }
16    const pedido = await res.json()
17    return { result: `Pedido ${numeroPedido}: ${pedido.estado}` }
18  }
19})

agents: los IDs de los agentes que pueden usar la herramienta.
parameters: los datos que el agente debe conseguir del cliente. Cada parámetro va en una sola línea, con name, type, description y, opcionalmente, example (la pregunta que el agente le hará al cliente).

Así lo usa el agente

El cliente pregunta por su pedido. El agente ve la herramienta worker_consultar-pedido con tu Referencia y decide usarla.
Si le falta el número de pedido, lo pregunta.
Llama al worker. El payload trae los parámetros más contactId, agentId, workspaceId y workerName.
Responde con lo que devuelve result. El agente solo lee result: el resto de lo que devuelvas no le llega.

Webhook: recibe datos de otros sistemas

01import { defineWebhook } from 'plz/workers'
02 
03export default defineWebhook({
04  name: 'nuevo-lead',
05  reference: 'Recibe leads del formulario web',
06 
07  async run(payload, plz) {
08    const { email, nombre } = payload
09    plz.log.info('Lead recibido')
10    if (!email) return { ok: false, motivo: 'email requerido' }
11    await plz.kv.set(`lead:${email}`, { nombre, recibido: new Date().toISOString() }, { ttl: 86400 })
12    return { ok: true, email }
13  }
14})

El cuerpo JSON de la petición llega en payload. plz.kv.set guarda datos con vencimiento (ttl en segundos: 86400 = 1 día).

Al desplegarlo, Plazbot crea una URL única que ves en la cabecera del worker (botón Ver cURL):

bash

01curl -X POST 'https://api.plazbot.com/api/worker/webhook/nuevo-lead?workspace=wok_8f2kQxLm4Tz9' \
02  -H 'Content-Type: application/json' \
03  -d '{"email":"ana@tuempresa.com","nombre":"Ana"}'

Respuesta:

json

01{
02  "success": true,
03  "result": { "ok": true, "email": "ana@tuempresa.com" },
04  "duration": 184,
05  "logs": [ ... ]
06}

Acepta solo POST y es pública: no pide token.
La respuesta incluye los logs. Nunca escribas datos sensibles en los logs de un webhook.

Schedule: una tarea programada

01import { defineSchedule } from 'plz/workers'
02 
03export default defineSchedule({
04  name: 'contar-pendientes',
05  reference: 'Cuenta los chats pendientes',
06  cron: '*/5 * * * *',
07  timezone: 'America/Lima',
08 
09  async run(plz) {
10    const pendientes = await plz.contacts.list({ filter: { isSolved: false }, limit: 1000 })
11    plz.log.info(`Chats pendientes: ${pendientes.length}`)
12    return { pendientes: pendientes.length }
13  }
14})

cron: cinco campos (minuto, hora, día, mes, día de la semana). Lo más frecuente es cada minuto.

cron	Significa
`/5 * * *`	Cada 5 minutos
`0 9 * * 1-5`	A las 9:00, de lunes a viernes

timezone: tu zona horaria. Sin ella, el horario es UTC.
run(plz) no recibe payload: nadie lo llama, corre solo.

Sync: sincroniza solo lo nuevo

01import { defineSync } from 'plz/workers'
02 
03export default defineSync({
04  name: 'sync-productos',
05  reference: 'Trae los productos nuevos de la tienda',
06  cron: '*/30 * * * *',
07 
08  async run(plz) {
09    const desde = Number(plz.cursor ?? '0')
10    const res = await plz.fetch(`https://api.tutienda.com/productos?desde=${desde}&limite=50`)
11    const items = await res.json()
12    for (const item of items) await plz.kv.set(`producto:${item.id}`, { nombre: item.nombre })
13    plz.setCursor(String(desde + items.length))
14    plz.log.info(`Sincronizados ${items.length} desde ${desde}`)
15    return { synced: items.length }
16  }
17})

Un Sync es un Schedule con memoria: plz.cursor es donde quedaste en la ejecución anterior (la primera vez está vacío) y plz.setCursor() guarda el nuevo punto.

Ojo: probarlo con Test también guarda el cursor.

Worker: lo ejecutas cuando lo necesitas

01import { defineWorker } from 'plz/workers'
02 
03export default defineWorker({
04  name: 'marcar-derivado',
05  reference: 'Etiqueta y avisa cuando el agente deriva al contacto',
06 
07  async run(payload, plz) {
08    const { contactId, contact } = payload
09    if (!contactId) return { ok: false, motivo: 'contactId requerido' }
10    await plz.contacts.addTag(contactId, 'derivado')
11    if (contact?.phoneNumber) {
12      await plz.whatsapp.send({ to: contact.phoneNumber, message: 'Un asesor te atendera en breve' })
13    }
14    return { ok: true }
15  }
16})

Aunque el selector de tipo dice «Worker - Escuchar eventos», hoy un Worker no se activa solo con eventos. Se ejecuta de dos formas:

Desde tu agente: en una acción, agrega Ejecutar Worker y elige el worker en Seleccionar worker.... El ícono de ayuda muestra el payload que recibe: