Anatomía de un Agente: Agentes Activos
A diferencia de los Agentes Pasivos que reaccionan a la interacción del usuario, los Agentes Activos están diseñados para iniciar acciones de forma proactiva. Actúan basados en reglas y condiciones predefinidas, como cambios de estado en un sistema o eventos programados, sin necesidad de que un usuario inicie la conversación.
Estructura General
La definición de un Agente Activo también se realiza en el archivo agent_definition.yaml, pero su estructura se centra en rules (reglas) y pre_processing (pre-procesamiento) en lugar de tools.
agents:
my_active_agent: # <--- Slug del agente activo
name: "Notificador de Estatus de Pedido"
description: "Un agente que notifica proactivamente a los clientes sobre el estado de sus pedidos."
rules:
status_aprobado:
display_name: "Estatus Aprobado"
template: "template_status_aprobado"
start_condition: "Cuando el estatus del pedido sea 'aprobado'"
source:
entrypoint: "main.StatusAprovado"
path: "rules/status_aprobado"
status_facturado:
display_name: "Estatus Facturado"
template: "template_status_facturado"
start_condition: "Cuando el estatus del pedido sea 'facturado'"
source:
entrypoint: "main.StatusFacturado"
path: "rules/status_facturado"
pre_processing:
source:
entrypoint: "processing.PreProcessor"
path: "pre_processors/processor"
result_examples_file: "result_example.json"
Definición de Reglas (rules)
La sección rules es un diccionario que define los disparadores (triggers) que activan las acciones del agente. Cada clave dentro de rules es un slug o ID único para cada regla.
rules:
status_aprobado: # <--- Este es el slug de la regla
display_name: "Estado Aprobado"
template: "template_status_aprovado"
start_condition: "Cuando el estado del pedido sea 'aprobado'"
source:
entrypoint: "main.StatusAprovado"
path: "rules/status_aprovado"
Propiedades de una Regla
display_name(string): El nombre legible para la regla que se mostrará en la interfaz de la plataforma.template(string): La plantilla de mensaje que se utilizará cuando esta regla se active.start_condition(string): Una descripción en lenguaje natural de la condición que debe cumplirse para que la regla se active.source(dict): Define el código Python que se ejecutará cuando la regla se dispare.entrypoint: El punto de entrada, en formatonombre_archivo.NombreDeLaClase(ej:main.StatusAprobado).path: La ruta al directorio que contiene el código de la regla.
Pre-procesamiento de Datos (pre_processing)
Esta sección (opcional pero muy potente) define un paso de lógica que se ejecuta antes de que se evalúen las reglas. Es útil para transformar, enriquecer o preparar datos.
pre_processing:
source:
entrypoint: "processing.PreProcessor"
path: "pre_processors/processor"
result_examples_file: "result_example.json"
Propiedades de pre_processing
source(dict): Define el código para la lógica de pre-procesamiento.entrypoint: La clase y método para el pre-procesamiento (ej:processing.PreProcessor).path: La ruta al directorio que contiene el código de pre-procesamiento.
result_examples_file(string) Requerido: Es la ruta a un archivo JSON que contiene ejemplos de la salida de datos del pre-procesamiento. Este archivo es crucial para que la plataforma entienda la estructura de datos que manejarán las reglas.
Formato del Archivo de Ejemplos (result_example.json)
El archivo de ejemplos de resultados debe ser un array de objetos JSON, donde cada objeto representa un posible escenario o caso de prueba.
[
{
"urn": "tel:+5511999998888",
"data": {
"pedido_id": "12345",
"status_actual": "aprobado",
"cliente_nombre": "Ana"
}
},
{
"urn": "tel:+5521888889999",
"data": {
"pedido_id": "67890",
"status_actual": "enviado",
"cliente_nombre": "Carlos",
"codigo_rastreo": "BR123456789"
}
}
]
urn: Un identificador único para el contacto (ej: un número de teléfono en formato E.164 o un ID de usuario).data: Un objeto que contiene los datos relevantes para ese ejemplo específico. La estructura de este objeto dependerá de las necesidades de tu agente.
Estructura de Carpetas Sugerida
Para mantener el proyecto organizado, se recomienda separar la lógica de las reglas y del pre-procesamiento en sus propias carpetas.
tu-proyecto/
├── rules/
│ ├── status_aprovado/
│ │ ├── main.py
│ │ └── requirements.txt
│ └── status_enviado/
│ ├── main.py
│ └── requirements.txt
├── pre_processors/
│ └── processor/
│ ├── processing.py
│ └── requirements.txt
├── agent_definition.yaml
└── result_example.json
