Este documento describe como se puede agregar acciones al Agente de IA, como por ejemplo:
- Apagar un agente de IA.
- Asignar una fase 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.).
Campos de la Accion
| Campo | Descripcion |
|---|
| intent | Identificador unico de la intencion de la accion. Se usa para detectar que esta solicitando el usuario (por ejemplo, "asignar_soporte"). |
| reference | Descripcion detallada del contenido de la intencion. Se utiliza para poder darle informacion al agente y sepa la intencion del usuario, como por ejemplo: “Quiero hablar con un agente humano”. |
| tags | Son referencias para poder entender mas la informacion dentro de la accion. Complementa la reference con contexto adicional. |
| enabled | Booleano que indica si la accion esta activada (true) o no (false). |
| requiredFields | Campos que el agente debe recopilar del usuario antes de ejecutar la accion. Funciona igual que en los servicios. |
| responseMessage | Mensaje que el agente debe de responder al usuario. Soporta variables con formato {{variable}}, {variable} o @variable. |
| responseJson | Booleano que indica si el agente debe de responder con un JSON estructurado (true) o un mensaje de texto plano (false). Solo aplica en el orquestador clasico. |
| responseExact | Booleano que indica si el responseMessage debe enviarse exactamente al usuario sin reformulacion del LLM (true). Solo aplica en modo Tool Calling. Por defecto false. |
| action | Listado de acciones que se ejecutaran. Cada accion tiene un type y un value. |
El agente de IA ejecutara las acciones en orden, esto quiere decir que si puso dos asignaciones, el agente de IA asignara la primera asignacion y luego la segunda asignacion. Por lo que prevalecera la ultima accion ejecutada.
Tipos de Accion
Cada accion dentro del arreglo action tiene un type que define que operacion se ejecutara:
| Tipo | Descripcion |
|---|
action.asign | Asigna un agente humano al contacto. El value es el email del agente. |
action.stage | Asigna una fase/etapa al contacto. El value es el nombre de la fase. |
action.agentShutDown | Apaga el agente de IA para el contacto. El value debe ser "true". |
action.segmentation | Asigna una segmentacion al contacto. El value es el nombre de la segmentacion. |
action.tag | Asigna una etiqueta al contacto. El value es el nombre de la etiqueta. |
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. |
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 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).
{
"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": "motivo",
"description": "Motivo de la cita",
"type": "string"
}
],
"responseMessage": "Tu cita ha sido agendada para el {{fecha}}.",
"responseExact": true,
"action": [
{
"type": "action.event.add",
"value": "cita"
}
]
}
requiredFields se pueden usar en el responseMessage con los formatos {{variable}}, {variable} o @variable.
Tipos de Respuesta
Las acciones del agente tienen configuraciones que determinan como responde despues de ejecutar las acciones:
Cuando el agente esta en modo Tool Calling (useToolCalling: true), el resultado de una accion normalmente pasa al LLM, que reformula el mensaje antes de enviarlo al usuario. Con responseExact: true, el responseMessage se envia directamente al usuario sin pasar por el LLM.
| Valor | Comportamiento |
|---|
true | Ejecuta las acciones + envia el responseMessage exacto al usuario (con variables sustituidas) |
false | Ejecuta las acciones + el LLM genera una respuesta basada en el resultado (comportamiento por defecto) |
Usuario: "Quiero hablar con soporte"
Bot: [Ejecuta acciones: action.asign → soporte@empresa.com]
Bot: "He transferido tu conversacion al equipo de soporte. Te atenderan en breve."
(exactamente el responseMessage configurado)
Usuario: "Quiero hablar con soporte"
Bot: [Ejecuta acciones: action.asign → soporte@empresa.com]
Bot: "Entendido, he asignado tu caso a nuestro equipo de soporte tecnico. Ellos se pondran en contacto contigo muy pronto para ayudarte."
(el LLM reformula el mensaje)
responseJson (Orquestador Clasico)
Controla el formato de la respuesta cuando se consume via API/SDK. Solo aplica en el orquestador clasico (sin Tool Calling).
| Valor | Formato de Respuesta |
|---|
false | Texto plano |
true | JSON estructurado |
{
"success": true,
"answer": "Gracias por tu consulta, un ejecutivo te contactara pronto."
}
{
"success": true,
"answer": {
"message": "Gracias por tu consulta, un ejecutivo te contactara pronto.",
"actionsExecuted": [
{
"type": "action.tag",
"value": "comercial"
},
{
"type": "action.stage",
"value": "prospecto"
}
]
}
}
En modo Tool Calling, la respuesta siempre incluye actionsExecuted en el resultado del tool, independientemente del valor de responseJson.
Casos de Uso Comunes
{
"intent": "contactar_soporte",
"reference": "El usuario quiere contactar con soporte tecnico",
"tags": ["soporte", "ayuda"],
"enabled": true,
"responseMessage": "He registrado tu solicitud de soporte. Un tecnico se comunicara contigo en breve.",
"responseExact": true,
"responseJson": false,
"action": [
{
"type": "action.tag",
"value": "soporte"
},
{
"type": "action.stage",
"value": "ticket_abierto"
}
]
}
{
"intent": "solicitar_informacion",
"reference": "El usuario solicita informacion sobre productos o servicios",
"tags": ["informacion", "productos"],
"enabled": true,
"responseMessage": "",
"responseExact": false,
"responseJson": false,
"action": [
{
"type": "action.tag",
"value": "lead_caliente"
}
]
}
3. Accion para API/Webhook (JSON)
{
"intent": "registrar_lead",
"reference": "Registro automatico de lead en sistema externo",
"tags": ["lead", "crm"],
"enabled": true,
"responseMessage": "Registro completado exitosamente",
"responseExact": false,
"responseJson": true,
"action": [
{
"type": "action.tag",
"value": "lead_registrado"
}
]
}
4. Accion de Evento con Campos Requeridos
{
"intent": "agendar_reunion",
"reference": "El usuario quiere agendar una reunion o cita",
"tags": ["cita", "calendario"],
"enabled": true,
"requiredFields": [
{
"name": "fecha",
"description": "Fecha y hora de la reunion",
"promptHint": "Para cuando te gustaria agendar la reunion?",
"type": "datetime"
},
{
"name": "nombre_cliente",
"description": "Nombre del cliente",
"type": "string"
}
],
"responseMessage": "Listo {{nombre_cliente}}, tu reunion ha sido agendada para el {{fecha}}.",
"responseExact": true,
"action": [
{
"type": "action.event.add",
"value": "reunion"
},
{
"type": "action.tag",
"value": "reunion_agendada"
}
]
}
Asignacion de Agentes
El agente de IA puede asignar un agente humano al contacto, esto se podra visualizar en la vista de contactos, en el campo de Agente Asignado.
{
"type": "action.asign",
"value": "agente@empresa.com"
}
Asignacion de Etiquetas
El agente de IA puede asignar una etiqueta al contacto, esto se podra visualizar en la vista de contactos, en el campo de Etiquetas.
{
"type": "action.tag",
"value": "nombre_etiqueta"
}
Asignacion de Fases
El agente de IA puede asignar una fase al contacto, esto se podra visualizar en la vista de contactos, en el campo de Fase.
{
"type": "action.stage",
"value": "nombre_fase"
}
Asignacion de Segmentacion
El agente de IA puede asignar una segmentacion al contacto, esto se podra visualizar en la vista de contactos, en el campo de Segmentacion.
{
"type": "action.segmentation",
"value": "nombre_segmentacion"
}
Marcar como Resuelto
El agente de IA puede marcar la conversacion como resuelta.
{
"type": "action.solved",
"value": "true"
}
Apagar el Agente de IA
El Agente de IA puede apagarse con la accion de Shutdown, esto se podra visualizar en la vista de contactos, en el campo de Agente Activo.
{
"type": "action.agentShutDown",
"value": "true"
}
Importante saber que esta opcion si se apaga ya no contestara el agente hasta que se vuelva a encender de forma manual.
