Workers: tu primer worker

Un worker es una función en TypeScript que corre dentro de Plazbot. Con ella le das herramientas nuevas a tu agente de IA, recibes webhooks de otros sistemas, programas tareas y sincronizas datos. En este artículo creas un worker de tipo Tool que consulta el estado de un pedido, lo despliegas y lo pruebas.

1. Activa el módulo Desarrolladores

Ve a Configuración › General.
En Configuración de administrador, enciende Activar módulo Desarrolladores.

En el menú aparece Desarrolladores, visible para administradores y supervisores. Tiene cuatro pestañas: Workers, Secrets, Ejemplos y Metricas.

2. Crea el worker

En Workers, presiona Agregar Worker. Se abre el editor, con las pestañas Codigo y Configuracion.
En Configuracion completa:

Campo	Qué va	Ejemplo
Nombre	Solo letras, números, guiones y guiones bajos	`consultar-pedido`
Tipo	Cómo se ejecuta el worker	`Tool - Herramienta para agente IA`
Referencia	La descripción que el agente lee para decidir cuándo usarlo	`Consulta el estado de un pedido cuando el cliente da su numero`

3. Entiende la plantilla

En Codigo ya tienes una plantilla. Todo worker se define con una función de plz/workers; para un Tool, defineTool:

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: ['id_agent_1'],
07  parameters: [
08    { name: 'campo1', type: 'string', description: 'Descripcion del campo' }
09  ],
10 
11  async run(payload, plz) {
12    const { contactId, campo1 } = payload
13    // Tu codigo aqui
14    return {
15      result: 'Respuesta del tool',
16    }
17  }
18})

run(payload, plz) es la función que se ejecuta.
payload trae los datos de entrada.
plz es el kit de Plazbot: plz.contacts, plz.whatsapp, plz.fetch, plz.log, plz.kv, plz.env y más.
Lo que run devuelve es la respuesta del worker. En un Tool, el agente lee result.

4. Escribe la lógica

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: ['id_agent_1'],
07  parameters: [
08    { name: 'numeroPedido', type: 'string', description: 'Numero de pedido del cliente' }
09  ],
10 
11  async run(payload, plz) {
12    const { numeroPedido } = payload
13    plz.log.info('Consultando pedido', { numeroPedido })
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})

Límites: todo va en un solo archivo, sin paquetes de npm, y cada ejecución tiene hasta 30 segundos.

5. Despliega

Presiona Deploy. Plazbot revisa el código, lo compila, guarda una versión y deja el worker activo. Vuelves a la lista, donde cada worker muestra su tipo, su estado, cuántas veces se ejecutó y sus errores.

6. Pruébalo

Abre el worker y presiona Test.
En Payload (JSON) escribe los datos de entrada:

json

01{ "numeroPedido": "1042" }

Presiona Ejecutar. Ves si fue Exitoso, cuánto tardó y lo que devolvió.

Cuidado: la prueba ejecuta tu código de verdad. Si tu worker envía mensajes o cambia contactos, lo hará.

7. Revisa el historial

Invocaciones: cada ejecución con su origen (test, agent…), su duración, la entrada y la salida.
Logs: lo que escribiste con plz.log.info(), plz.log.warn() o plz.log.error(). console.log no aparece aquí.
Versiones: cada despliegue. Compáralo con el código actual y vuelve atrás con Rollback.ers ves los cinco tipos (Tool, Webhook, Schedule, Sync y Worker) con un ejemplo de cada uno.