Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.plazbot.com/llms.txt

Use this file to discover all available pages before exploring further.

Los Workers son funciones TypeScript que extienden las capacidades de tu workspace en Plazbot. Permiten ejecutar logica personalizada que se integra con el Agente de IA, responde a eventos externos, o se ejecuta de forma programada.

​
Para que sirven

  • Conectar tu agente con APIs externas (inventario, CRM, pagos).
  • Procesar webhooks de servicios como Stripe, Shopify o MercadoPago.
  • Ejecutar tareas programadas (reportes, sincronizaciones, alertas).
  • Automatizar operaciones sobre contactos, conversaciones y variables.

​
Requisitos previos

Antes de usar workers, debes configurar los siguientes secrets obligatorios desde el tab Developers > Secrets en el dashboard. Sin estos secrets, ningun worker podra ejecutarse.
SecretDescripcion
PLZ_API_KEYToken de acceso a la API de Plazbot. Permite que los workers interactuen con contactos, conversaciones, templates y demas recursos del workspace.
PLZ_ZONERegion del workspace (LA para Latinoamerica, EU para Europa). Determina a que servidor de API se conectan los workers.
Para configurarlos facilmente, haz click en el boton “Configurar Secrets de Plazbot” que aparece en el tab Secrets. Este genera el token automaticamente y detecta la zona de tu workspace.

​
Estructura de un Worker

Cada worker es un archivo .ts que importa una funcion define* del SDK de Plazbot y exporta su configuracion junto con un handler. 
import { defineTool } from 'plz/workers'

export default defineTool({
  name: 'mi-herramienta',
  reference: 'Descripcion de lo que hace esta herramienta',
  agents: ['id_del_agente'],
  parameters: [
    { name: 'query', type: 'string', description: 'Parametro requerido' }
  ],

  async run(payload, plz) {
    // Logica del worker
    return { resultado: 'ok' }
  }
})
Partes principales:
ParteDescripcion
importImporta la funcion define* correspondiente al tipo de worker.
nameNombre unico del worker dentro del workspace.
referenceDescripcion del worker. En tools, el agente usa esta descripcion para decidir cuando invocarlo.
run(payload, plz)Funcion handler que contiene la logica. Recibe el payload y el contexto plz.

​
Ciclo de vida

1

Escribir

Crea un archivo .ts con la definicion del worker usando una de las funciones define*.
2

Desplegar

Usa el CLI (plazbot workers deploy mi-worker.ts) o el editor del dashboard para subir el worker al workspace.
3

Ejecutar

El worker se ejecuta automaticamente segun su tipo: el agente lo invoca (tool), un cron lo dispara (schedule/sync), un HTTP request lo activa (webhook), o se ejecuta bajo demanda (worker).

​
Integracion con el Agente de IA

Los workers se integran con el Agente de IA a traves de las Acciones del Agente. Dentro de la configuracion de acciones, puedes usar el tipo action.worker para invocar un worker cuando el agente detecta una intencion.
El tipo action.worker en las acciones del agente solo soporta workers de tipo worker (definidos con defineWorker). No puedes invocar directamente un tool, schedule o webhook desde una accion del agente.
Los workers de tipo tool (defineTool) se integran de forma diferente: se registran directamente como herramientas del agente mediante el campo agents, y el agente los invoca automaticamente durante la conversacion cuando lo considera necesario.

​
Campos comunes del define*

Todos los tipos de workers comparten estos campos de configuracion:
CampoTipoRequeridoDescripcion
namestringSiNombre unico del worker. Se usa como identificador en el workspace.
referencestringNoDescripcion del proposito del worker.
Cada tipo agrega campos adicionales segun su funcion. Consulta la pagina de Tipos para ver los campos especificos.

​
Runtime

Los workers se ejecutan en un entorno aislado de Plazbot con acceso al contexto plz, que provee metodos para interactuar con la plataforma. El codigo TypeScript se compila a JavaScript antes del despliegue.
No necesitas instalar dependencias externas. El runtime provee automaticamente el SDK plz con acceso a contactos, WhatsApp, templates, key-value store y mas. Consulta la pagina de Contexto para ver todos los metodos disponibles.