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

# Definicion

> Que son los Workers y como funcionan en Plazbot

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

<Warning>
  **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.

  | Secret        | Descripcion                                                                                                                                       |
  | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `PLZ_API_KEY` | Token de acceso a la API de Plazbot. Permite que los workers interactuen con contactos, conversaciones, templates y demas recursos del workspace. |
  | `PLZ_ZONE`    | Region 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.
</Warning>

***

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

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

| Parte               | Descripcion                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| `import`            | Importa la funcion define\* correspondiente al tipo de worker.                                  |
| `name`              | Nombre unico del worker dentro del workspace.                                                   |
| `reference`         | Descripcion 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

<Steps>
  <Step title="Escribir">
    Crea un archivo `.ts` con la definicion del worker usando una de las funciones `define*`.
  </Step>

  <Step title="Desplegar">
    Usa el CLI (`plazbot workers deploy mi-worker.ts`) o el editor del dashboard para subir el worker al workspace.
  </Step>

  <Step title="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).
  </Step>
</Steps>

***

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

<Warning>
  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.
</Warning>

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:

| Campo       | Tipo     | Requerido | Descripcion                                                         |
| ----------- | -------- | --------- | ------------------------------------------------------------------- |
| `name`      | `string` | Si        | Nombre unico del worker. Se usa como identificador en el workspace. |
| `reference` | `string` | No        | Descripcion del proposito del worker.                               |

Cada tipo agrega campos adicionales segun su funcion. Consulta la pagina de [Tipos](/guides/agents/workers/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.

<Tip>
  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](/guides/agents/workers/contexto) para ver todos los metodos disponibles.
</Tip>