# Acciones > Guía completa para activar acciones del Agente de IA. Fuente: https://developers.plazbot.com/sdk/action/ ### Configuración de las Acciones del Agentes IA Este documento describe como se puede agregar en el archivo `agent.config.json`, acciones que se pueden ejecutar en el Agente de IA, como por ejemplo: - Apagar un agente de IA. - Asignar una etapa al contacto. - Asignar una etiqueta al contacto. - Asignar una segmentación al contacto. - Asignar un agente humano al contacto. - Marcar como resuelto. - Gestionar eventos (citas, reuniones, etc.). Puedes descargar nuestro repositorio de ejemplo para crear tus agentes. ### Estructura > **Tip:** Las acciones se pueden agregar en el archivo `agent.config.json`, para que el Agente de IA pueda ejecutar las acciones. Estas pueden agregar de forma independiente o agregar un campo `action` dentro de un servicio. ```json { "actions":[ { "intent": "conversar_humano", "reference": "Informacion cuando un usuario quiere hablar con un Agente humano.", "tags": ["conversacion", "humano", "agente"], "enabled": true, "requiredFields": [], "responseMessage": "Por favor, espera un momento mientras te conectamos con un agente humano.", "responseJson": false, "responseExact": true, "action": [ { "type": "action.asign", "value": "k@gmail.com" }, { "type": "action.stage", "value": "agendado" }, { "type": "action.agentShutDown", "value": "true" }, { "type": "action.segmentation", "value": "segmentacion1" }, { "type": "action.tag", "value": "pendiente" } ] } ] } ``` ### Campos de la Acción | Campo | Tipo | Descripción | |------------------|------|-------------| | `intent` | string | Identificador único de la intención de la action. (por ejemplo, `"conversar_humano"`). | | `reference` | string | Frase corta y descriptiva que ayuda a la IA a entender cuando debe activarse esta action. | | `tags` | string[] | Etiquetas para complementar la `reference` con contexto adicional. | | `enabled` | boolean | Indica si la action está activa (`true`) o no (`false`). | | `requiredFields` | array | Campos que el agente debe recopilar del usuario antes de ejecutar la acción. Funciona igual que en los servicios. | | `responseMessage` | string | Mensaje que el agente devuelve al usuario tras ejecutar la action. Soporta variables: `{{variable}}`, `{variable}`, `@variable`. | | `responseJson` | boolean | Si la action debe devolver un JSON (`true`) o texto plano (`false`). Solo aplica en orquestador clasico. | | `responseExact` | boolean | Si el `responseMessage` se envía **exactamente** al usuario sin reformulación del LLM. Solo aplica en modo Tool Calling. Default: `false`. | | `action` | array | Arreglo de objetos con `type` y `value` que definen las acciones a ejecutar. | ### Tipos de Acción | Tipo | Descripción | |------|-------------| | `action.asign` | Asigna un agente humano al contacto. El `value` es el email del agente. | | `action.stage` | Asigna una etapa al contacto. | | `action.agentShutDown` | Apaga el agente de IA para el contacto. El `value` debe ser `"true"`. | | `action.segmentation` | Asigna una segmentación al contacto. | | `action.tag` | Asigna una etiqueta al contacto. | | `action.solved` | Marca la conversación como resuelta. El `value` debe ser `"true"`. | | `action.event.add` | Crea un nuevo evento/cita en el calendario. | | `action.event.update` | Actualiza un evento existente. | | `action.event.delete` | Elimina un evento. | | `action.event.list` | Lista los eventos disponibles. | | `action.event.confirm` | Confirma un evento pendiente. | | `action.event.cancel` | Cancela un evento existente. | | `action.secuence` | Inscribe al contacto en una secuencia. El `value` es el identificador de la secuencia. | | `action.unassign` | Quita el agente humano asignado al contacto. | | `action.stage.remove` | Quita la etapa del contacto. | | `action.tag.remove` | Quita una etiqueta del contacto. | | `action.segmentation.remove` | Quita una segmentación del contacto. | | `action.worker` | Ejecuta un Worker de Plazbot. El `value` es el identificador del worker. | | `action.transfer.voip` | Transfiere la llamada a una extensión VoIP interna (solo agentes de voz). | | `action.transfer.voip.external` | Transfiere la llamada a un proxy SIP externo (solo agentes de voz). Requiere campos `sip*`. | | `action.send.image` | Envía una imagen al usuario. El `value` es la URL publica del archivo. | | `action.send.file` | Envía un archivo al usuario. El `value` es la URL publica del archivo. | > **Nota:** Las acciones de tipo `action.event.*` requieren que el agente tenga configurado un calendario. Cuando se configuran acciones de eventos, el sistema inyecta automáticamente una herramienta de **consulta de disponibilidad** (`check_availability`) para que el agente pueda verificar horarios libres antes de agendar. ### Campos adicionales por tipo de acción Algunos tipos de acción aceptan campos extra además de `type` y `value`: | Campo | Aplica a | Descripción | |-------|----------|-------------| | `durationMinutes` | `action.event.add`, `action.event.update` | Duracion del evento en minutos. Rango: 5-480. Default: 30. | | `availabilitySchedule` | `action.event.add` | Horario personalizado de disponibilidad para citas. Si no se configura o `useWorkspaceSchedule: true`, usa el horario del workspace. | | `sipServer` | `action.transfer.voip.external` | Servidor/proxy SIP del partner (ej: `trunks.vpbx.me`). La extensión destino va en `value`. | | `sipPort` | `action.transfer.voip.external` | Puerto SIP del proxy. Default: 5060. | | `sipUser` | `action.transfer.voip.external` | Usuario SIP para autenticación saliente. | | `sipPassword` | `action.transfer.voip.external` | Clave SIP para autenticación saliente. | | `sipDomain` | `action.transfer.voip.external` | From-domain opcional para PBX multi-tenant. | | `fileName` | `action.send.image`, `action.send.file` | Nombre original del archivo. La URL publica va en `value`. | | `mimeType` | `action.send.image`, `action.send.file` | Content-Type del archivo (ej: `image/png`, `application/pdf`). | #### Ejemplo de horario personalizado (`availabilitySchedule`) ```json { "type": "action.event.add", "value": "cita", "durationMinutes": 45, "availabilitySchedule": { "useWorkspaceSchedule": false, "days": [ { "enabled": true, "allDay": false, "from": "09:00", "to": "13:00", "ranges": [{ "from": "15:00", "to": "18:00" }] }, { "enabled": false } ] } } ``` #### Ejemplo de envio de archivo ```json { "type": "action.send.file", "value": "https://bucket.s3.amazonaws.com/catalogo.pdf", "fileName": "catalogo.pdf", "mimeType": "application/pdf" } ``` ### Asignar un agente humano ```json { "type": "action.asign", "value": "k@gmail.com" } ``` ### Asignar una etapa ```json { "type": "action.stage", "value": "agendado" } ``` ### Apagar un agente de IA ```json { "type": "action.agentShutDown", "value": "true" } ``` ### Asignar una segmentación ```json { "type": "action.segmentation", "value": "segmentacion1" } ``` ### Asignar una etiqueta ```json { "type": "action.tag", "value": "pendiente" } ``` ### Marcar como resuelto ```json { "type": "action.solved", "value": "true" } ``` ### Campos Requeridos en Acciones Las acciones también soportan `requiredFields`, que funcionan de la misma forma que en los servicios. Esto es útil cuando la acción necesita datos del usuario antes de ejecutarse (por ejemplo, una fecha para agendar un evento). ```json { "intent": "agendar_cita", "reference": "El usuario quiere agendar una cita o reunion", "enabled": true, "requiredFields": [ { "name": "fecha", "description": "Fecha deseada para la cita", "promptHint": "Cual es la fecha que prefieres para la cita?", "type": "datetime" }, { "name": "nombre_cliente", "description": "Nombre del cliente", "type": "string" } ], "responseMessage": "Listo {{nombre_cliente}}, tu cita ha sido agendada para el {{fecha}}.", "responseExact": true, "action": [ { "type": "action.event.add", "value": "cita" } ] } ``` #### Comportamiento de Respuesta **Modo Tool Calling (`useToolCalling: true`):** Con `responseExact: true`: ```json { "responseExact": true, "responseMessage": "He transferido tu conversación al equipo de soporte." } ``` - Ejecuta las acciones - Envía el `responseMessage` **exacto** al usuario (con variables sustituidas) - El LLM no reformula el mensaje Con `responseExact: false` (default): ```json { "responseExact": false, "responseMessage": "" } ``` - Ejecuta las acciones - El LLM genera una respuesta natural basada en el resultado - Más inteligente y conversacional **Modo Clasico (`useToolCalling: false`):** `responseJson: false`: ```json { "responseJson": false, "responseMessage": "Solicitud procesada correctamente." } ``` - Ejecuta las acciones - Responde con mensaje fijo - Útil para confirmaciones simples `responseJson: true`: ```json { "responseJson": true, "responseMessage": "Proceso completado" } ``` - Ejecuta las acciones - Responde con JSON estructurado - Ideal para integraciones con APIs/webhooks ### TypeScript ```typescript import type { AgentAction, AgentActionItem, ActionType } from 'plazbot'; ``` ### Consideraciones El `action` también se puede agregar dentro de un servicio, para que se ejecute cuando se active el servicio como un campo más adicional. En caso de que se agregue dentro de un servicio, se debe agregar el campo `action` dentro del servicio y solo ejecutara las acciones y no analizara el mensaje del usuario ya que las referencias ya se encuentran en el servicio.