Skip to main content

​
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 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.).

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.
{
  "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 Accion

CampoTipoDescripcion
intentstringIdentificador unico de la intencion de la action. (por ejemplo, "conversar_humano").
referencestringFrase corta y descriptiva que ayuda a la IA a entender cuando debe activarse esta action.
tagsstring[]Etiquetas para complementar la reference con contexto adicional.
enabledbooleanIndica si la action esta activa (true) o no (false).
requiredFieldsarrayCampos que el agente debe recopilar del usuario antes de ejecutar la accion. Funciona igual que en los servicios.
responseMessagestringMensaje que el agente devuelve al usuario tras ejecutar la action. Soporta variables: {{variable}}, {variable}, @variable.
responseJsonbooleanSi la action debe devolver un JSON (true) o texto plano (false). Solo aplica en orquestador clasico.
responseExactbooleanSi el responseMessage se envia exactamente al usuario sin reformulacion del LLM. Solo aplica en modo Tool Calling. Default: false.
actionarrayArreglo de objetos con type y value que definen las acciones a ejecutar.

​
Tipos de Accion

TipoDescripcion
action.asignAsigna un agente humano al contacto. El value es el email del agente.
action.stageAsigna una fase/etapa al contacto.
action.agentShutDownApaga el agente de IA para el contacto. El value debe ser "true".
action.segmentationAsigna una segmentacion al contacto.
action.tagAsigna una etiqueta al contacto.
action.solvedMarca la conversacion como resuelta. El value debe ser "true".
action.event.addCrea un nuevo evento/cita en el calendario.
action.event.updateActualiza un evento existente.
action.event.deleteElimina un evento.
action.event.listLista los eventos disponibles.
action.event.confirmConfirma un evento pendiente.
action.event.cancelCancela 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.

​
Asignar un agente humano

 {
    "type": "action.asign",
    "value": "k@gmail.com"
}

​
Asignar una fase

 {
    "type": "action.stage",
    "value": "agendado"
}

​
Apagar un agente de IA

{
    "type": "action.agentShutDown",
    "value": "true"
}

​
Asignar una segmentacion

{
    "type": "action.segmentation",
    "value": "segmentacion1"
}

​
Asignar una etiqueta

{
    "type": "action.tag",
    "value": "pendiente"
}

​
Marcar como resuelto

{
    "type": "action.solved",
    "value": "true"
}

​
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": "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: 
{
  "responseExact": true,
  "responseMessage": "He transferido tu conversacion al equipo de soporte."
}
  • Ejecuta las acciones
  • Envia el responseMessage exacto al usuario (con variables sustituidas)
  • El LLM no reformula el mensaje
Con responseExact: false (default): 
{
  "responseExact": false,
  "responseMessage": ""
}
  • Ejecuta las acciones
  • El LLM genera una respuesta natural basada en el resultado
  • Mas inteligente y conversacional
Modo Clasico (useToolCalling: false): responseJson: false: 
{
  "responseJson": false,
  "responseMessage": "Solicitud procesada correctamente."
}
  • Ejecuta las acciones
  • Responde con mensaje fijo
  • Util para confirmaciones simples
responseJson: true: 
{
  "responseJson": true,
  "responseMessage": "Proceso completado"
}
  • Ejecuta las acciones
  • Responde con JSON estructurado
  • Ideal para integraciones con APIs/webhooks

​
TypeScript

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