Configuracion 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 segmentacion al contacto.
- Asignar un agente humano al contacto.
- Marcar como resuelto.
- Gestionar eventos (citas, reuniones, etc.).
Github
Puedes descargar nuestro repositorio de ejemplo para crear tus agentes.
Estructura
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
01{02 "actions":[03 {04 "intent": "conversar_humano",05 "reference": "Informacion cuando un usuario quiere hablar con un Agente humano.",06 "tags": ["conversacion", "humano", "agente"],07 "enabled": true,08 "requiredFields": [],09 "responseMessage": "Por favor, espera un momento mientras te conectamos con un agente humano.",10 "responseJson": false,11 "responseExact": true,12 "action": [13 {14 "type": "action.asign",15 "value": "k@gmail.com"16 },17 {18 "type": "action.stage",19 "value": "agendado"20 },21 {22 "type": "action.agentShutDown",23 "value": "true"24 },25 {26 "type": "action.segmentation",27 "value": "segmentacion1"28 },29 {30 "type": "action.tag",31 "value": "pendiente"32 }33 ]34 }35 ]36}
Campos de la Accion
| Campo | Tipo | Descripcion |
|---|---|---|
intent | string | Identificador unico de la intencion 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 esta activa (true) o no (false). |
requiredFields | array | Campos que el agente debe recopilar del usuario antes de ejecutar la accion. 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 envia exactamente al usuario sin reformulacion 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 Accion
| Tipo | Descripcion |
|---|---|
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 segmentacion al contacto. |
action.tag | Asigna una etiqueta al contacto. |
action.solved | Marca la conversacion 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 segmentacion del contacto. |
action.worker | Ejecuta un Worker de Plazbot. El value es el identificador del worker. |
action.transfer.voip | Transfiere la llamada a una extension 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 | Envia una imagen al usuario. El value es la URL publica del archivo. |
action.send.file | Envia un archivo al usuario. El value es la URL publica del archivo. |
Las acciones de tipo action.event.* requieren que el agente tenga configurado un calendario. Cuando se configuran acciones de eventos, el sistema inyecta automaticamente una herramienta de consulta de disponibilidad (check_availability) para que el agente pueda verificar horarios libres antes de agendar.
Campos adicionales por tipo de accion
Algunos tipos de accion aceptan campos extra ademas de type y value:
| Campo | Aplica a | Descripcion |
|---|---|---|
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 extension destino va en value. |
sipPort | action.transfer.voip.external | Puerto SIP del proxy. Default: 5060. |
sipUser | action.transfer.voip.external | Usuario SIP para autenticacion saliente. |
sipPassword | action.transfer.voip.external | Clave SIP para autenticacion 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
01{02 "type": "action.event.add",03 "value": "cita",04 "durationMinutes": 45,05 "availabilitySchedule": {06 "useWorkspaceSchedule": false,07 "days": [08 { "enabled": true, "allDay": false, "from": "09:00", "to": "13:00", "ranges": [{ "from": "15:00", "to": "18:00" }] },09 { "enabled": false }10 ]11 }12}
Ejemplo de envio de archivo
json
01{02 "type": "action.send.file",03 "value": "https://bucket.s3.amazonaws.com/catalogo.pdf",04 "fileName": "catalogo.pdf",05 "mimeType": "application/pdf"06}
Asignar un agente humano
json
01 {02 "type": "action.asign",03 "value": "k@gmail.com"04}
Asignar una etapa
json
01 {02 "type": "action.stage",03 "value": "agendado"04}
Apagar un agente de IA
json
01{02 "type": "action.agentShutDown",03 "value": "true"04}
Asignar una segmentacion
json
01{02 "type": "action.segmentation",03 "value": "segmentacion1"04}
Asignar una etiqueta
json
01{02 "type": "action.tag",03 "value": "pendiente"04}
Marcar como resuelto
json
01{02 "type": "action.solved",03 "value": "true"04}
Campos Requeridos en Acciones
Las acciones tambien soportan requiredFields, que funcionan de la misma forma que en los servicios. Esto es util cuando la accion necesita datos del usuario antes de ejecutarse (por ejemplo, una fecha para agendar un evento).
json
01{02 "intent": "agendar_cita",03 "reference": "El usuario quiere agendar una cita o reunion",04 "enabled": true,05 "requiredFields": [06 {07 "name": "fecha",08 "description": "Fecha deseada para la cita",09 "promptHint": "Cual es la fecha que prefieres para la cita?",10 "type": "datetime"11 },12 {13 "name": "nombre_cliente",14 "description": "Nombre del cliente",15 "type": "string"16 }17 ],18 "responseMessage": "Listo {{nombre_cliente}}, tu cita ha sido agendada para el {{fecha}}.",19 "responseExact": true,20 "action": [21 {22 "type": "action.event.add",23 "value": "cita"24 }25 ]26}
Comportamiento de Respuesta
Modo Tool Calling (useToolCalling: true):
Con responseExact: true:
json
01{02 "responseExact": true,03 "responseMessage": "He transferido tu conversacion al equipo de soporte."04}
- Ejecuta las acciones
- Envia el
responseMessageexacto al usuario (con variables sustituidas) - El LLM no reformula el mensaje
Con responseExact: false (default):
json
01{02 "responseExact": false,03 "responseMessage": ""04}
- Ejecuta las acciones
- El LLM genera una respuesta natural basada en el resultado
- Mas inteligente y conversacional
Modo Clasico (useToolCalling: false):
responseJson: false:
json
01{02 "responseJson": false,03 "responseMessage": "Solicitud procesada correctamente."04}
- Ejecuta las acciones
- Responde con mensaje fijo
- Util para confirmaciones simples
responseJson: true:
json
01{02 "responseJson": true,03 "responseMessage": "Proceso completado"04}
- Ejecuta las acciones
- Responde con JSON estructurado
- Ideal para integraciones con APIs/webhooks
TypeScript
typescript
01import type { AgentAction, AgentActionItem, ActionType } from 'plazbot';
Consideraciones
El action tambien se puede agregar dentro de un servicio, para que se ejecute cuando se active el servicio como un campo mas 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.