> ## 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.

# Tipos de Workers

> Los 5 tipos de workers disponibles en Plazbot

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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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 }
  }
})
```

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

***

## 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:**

```typescript theme={null}
async run(plz) {
  // No recibe payload - se ejecuta automaticamente
  return { ... }
}
```

**Ejemplo:**

```typescript theme={null}
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:**

```typescript theme={null}
async run(plz) {
  // No recibe payload - se ejecuta automaticamente
  return { ... }
}
```

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

**Ejemplo:**

```typescript theme={null}
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:**

```typescript theme={null}
async run(payload, plz) {
  // payload contiene el body del request HTTP
  return { ... }
}
```

**Ejemplo:**

```typescript theme={null}
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 }
  }
})
```

<Tip>
  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).
</Tip>

***

## 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`