隆Bienvenid@ a Zoe!露
Introducci贸n露
驴Qu茅 es Zoe?露
Zoe es una asistente virtual para la organizaci贸n sin 谩nimo de lucro del Grupo de Usuarios de Linux UC3M (GUL UC3M). Su objetivo es el de realizar tareas repetitivas y que consumen mucho tiempo de forma as铆ncrona, desacoplada y perezosa.
驴C贸mo funciona?露
Zoe tiene dos componentes principales: el servidor de Zoe, y un grupo de agentes, peque帽os programas que realizan algunas peque帽as y bien definidas tareas tales como captura de estad铆sticas de los sistemas de la organizaci贸n, env铆o de emails, generaci贸n de informes y control de alarmas.
El servidor implementa un bus de mensajes que los agentes utilizan para intercambiar mensajes de forma as铆ncrona. Zoe tambi茅n puede recibir comandos de los administradores del sistema para realizar tareas bajo demanda.
Licencia露
El servidor Zoe se publica bajo la licencia MIT. Sin embargo, la licencia de los agentes puede variar dependiendo del desarrollador del agente.
Empezando露
Esta secci贸n te ayudar谩 a empezar con el kit de iniciaci贸n de Zoe.
Requisitos露
OS X o Linux (BSD tambi茅n deber铆a servir, aunque no ha sido probado)
- Bash
- Java 1.7
- Python 3
- Perl 5
Estructura de directorios露
El kit de iniciaci贸n de Zoe tiene la siguiente estructura:
agents/
cmdproc/
etc/
lib/
bash/
java/
perl/
python-dependencies/
python/
logs/
mailproc/
server/
var/
zoe.sh
agents/: Agentes instalados
cmdproc/: Comandos de administrador en lenguaje natural
etc/: Archivos de configuraci贸n
lib/: Librer铆as y dependencias de agentes por lenguaje
logs/: Archivos de registro de los agentes
mailproc/: Acciones a ejecutar al recibir emails
server/: Binarios del servidor de Zoe
var/: Bases de datos y archivos temporales generados por los agentes
zoe.sh: Script de Zoe
Instalaci贸n露
Descarga el c贸digo del kit de iniciaci贸n de Zoe y ponlo en el directorio desde el que quieras ejecutar Zoe, como por ejemplo /home/zoe. Navega hasta el directorio y haz los siguientes scripts ejecutables:
$ chmod +x zoe.sh
$ chmod +x etc/environment.sh
Configuraci贸n露
Los archivos de configuraci贸n de Zoe se encuentran en el directorio etc/. Estos son los archivos base que se encuentran en el directorio:
zam/
environment.sh
twitter.conf
zoe-users.conf
zoe.conf
Agentes露
El archivo zoe.conf contiene una lista de agentes con sus correspondientes puertos y una lista de agentes relacionados con un tema espec铆fico. Para m谩s informaci贸n, visita la secci贸n de Agentes de esta documentaci贸n
Algunos agentes, como el agente de Twitter, pueden incluir archivos de configuraci贸n adicionales. En este caso, twitter.conf contiene las credenciales requeridas por el agente de Twitter. Estas credenciales se pueden obtener desde el perfil de Twitter.
El directorio zam es parte del Gestor de Agentes de Zoe, encargado de instalar y gestionar agentes. Para m谩s informaci贸n, visita la secci贸n de instalaci贸n de Agentes.
Entorno露
El script environment.sh establece variables tales como el host del servidor, credenciales de twitter, informaci贸n de jabber, etc. Tiene el siguiente contenido:
# Typical values
export ZOE_SERVER_HOST=localhost
export ZOE_SERVER_PORT=30000
# Parameters for Google Talk
export zoe_jabber_host="talk.google.com"
export zoe_jabber_port="5222"
export zoe_jabber_user="..."
export zoe_jabber_password=""
# Parameters for a GMail account
export zoe_mail_smtp="smtp.gmail.com"
export zoe_mail_smtp_port="587"
export zoe_mail_pop3="pop.gmail.com"
export zoe_mail_pop3_port="995"
export zoe_mail_enable_dkim="false"
export zoe_mail_user="$zoe_jabber_user"
export zoe_mail_password="$zoe_jabber_password"
Nunca des a Zoe tus propias credenciales de twitter/jabber. Crea una nueva cuenta si pretendes usarlos.
Por defecto, las cuentas de Jabber y GMail usan las mismas credenciales debido a que el servicio de Google Talk (Hangouts) utiliza Jabber. Puedes utilizar otros servicios de Jabber y correo electr贸nico si lo deseas.
Usuarios露
El archivo zoe-users.conf sigue esta estructura:
[subject admin]
name = Admin
twitter = your twitter name without @
preferred = twitter
jabber = your_jabber_id@wherever.com
mail = your_email@address.com
alias = god master
[group admins]
members = admin
[group broadcast]
members = admin
Cada usuario est谩 identificado por la etiqueta [subject USUARIO] y tiene los siguientes atributos:
name: El nombre del usuario (ej. Zoe).
twitter: El nombre de usuario de twitter (ej. gul_zoe).
preferred: La forma de comunicaci贸n con Zoe preferida por el usuario. Los posibles valores son twitter, jabber, mail.
jabber: La direcci贸n de jabber del usuario. Si utilizas Google Hangouts, las direcciones de jabber siguen un formato abcdefghijklmnopqrstuwxyz1@public.talk.google.com. Si no sabes cu谩l es la direcci贸n, puedes intentar hablar con Zoe por Jabber y obtener la direcci贸n de los registros.
mail: La direcci贸n de correo del usuario.
alias: El alias del usuario.
Algunos agentes pueden utilizar grupos para env铆ar correos a varios usuarios al mismo tiempo o comprobar permisos. Se puede definir un nuevo grupo usando la estructura [group NOMBRE DE GRUPO] y a帽adiendo a sus usuarios en el atributo``members``.
Primera ejecuci贸n露
Desde una terminal, navega al directorio ra铆z de Zoe (ej. /home/zoe) y ejecuta:
Carga la configuraci贸n de Zoe:
$ . etc/environment.sh
Ejecuta Zoe:
$ ./zoe.sh start
Ver谩s que la terminal muestra los agentes que se han iniciado. Puedes comprobar el estado de estos agentes ejecutando:
$ ./zoe.sh status
Si hay agentes muertos, quiz谩 quieras comprobar sus archivos de registro (en el directorio log/). La mayor铆a de los errores suelen deberse a errores de configuraci贸n.
Eso es todo, ahora tienes una instancia de Zoe funcional y ejecut谩ndose en tu m谩quina. Puedes detener el servidor mediante:
$ ./zoe.sh stop
Lo cu谩l detendr谩 tambi茅n todos los agentes en ejecuci贸n.
Agentes露
En esta secci贸n encontrar谩s informaci贸n relacionada con los agentes.
驴Qu茅 es un agente?露
Los agentes son peque帽os programas a los que Zoe tiene acceso para poder realizar diferentes acciones. Cada agente se encarga de tareas espec铆ficas y se comunican entre ellos mediante el bus de mensajes del servidor. El servidor crea sockets para cada agente din谩micamente o usando el archivo etc/zoe.conf, que contiene el puerto de cada agente y una lista de agentes relacionados con un tema espec铆fico.
Estructura露
Los agentes suelen consistir en 1-2 archivos, aunque esto depende enteramente del desarrollador. La mayor铆a de agentes est谩n escritos en Python, pero hay disponibles librer铆as para escribir agentes en lenguajes como Bash, Java, Python, etc.
El script principal se coloca en el directorio agents/NOMBRE_AGENTE. El agente tambi茅n puede incluir comandos de lenguaje natural para ejecutar acciones bajo demanda sin la necesidad de usar la l铆nea de comandos para mandar el mensaje al servidor manualmente. De esta forma, se puede hablar con Zoe mediante, por ejemplo, Jabber. Estos comandos de lenguaje natural se colocan en el directorio cmdproc/.
Mensajes露
Estructura de mensajes露
Los agentes intercambian mensajes mediante el bus de mensajes del servidor. Estos mensajes tienen una estructura clave-valor de la forma:
key1=val1&key2=val2&key3=val3...
Por ejemplo, el agente broadcast puede enviar un mensaje a un usuario espec铆fico. La cadena para hacerlo ser铆a algo parecido a esto:
dst=broadcast&tag=send&msg=Hello World!&to=john
Analizando el mensaje:
dst: Agente al que va destinado el mensaje.
tag: Acci贸n a realizar. Puede haber varios tag en el mensaje.
msg: Mensaje que mandar al usuario.
to: Usuario al que mandar el mensaje. El nombre se comprueba con la lista de usuarios para ver cu谩l es la direcci贸n de John y su m茅todo de contacto preferido.
La cadena puede variar dependiendo de cada agente, pero la mayor铆a tendr谩n partes comunes como dst y tag.
Enviando mensajes al servidor露
Aparte del intercambio de mensajes de los agentes, tambi茅n se puede enviar un mensaje al servidor manualmente para que un agente ejecute alguna acci贸n. Tomando el anterior ejemplo del agente broadcast, el mensaje se podr铆a enviar como:
$ echo -n "dst=broadcast&tag=send&msg=Hello World!&to=john" | nc ZOE_HOST ZOE_PORT
Ahora, el archivo logs/broadcast.log tendr铆a una entrada con el mensaje recibido y la acci贸n realizada (o cualquier error mientras se llevaba a cabo).
Instalando nuevos agentes露
Hay dos formas de instalar un nuevo agente en una instancia de Zoe.
Instalaci贸n manual露
Para instalar un agente manualmente hay que descargar el c贸digo y colocar los archivos en la instalaci贸n de Zoe siguiendo las instrucciones del desarrollador. Normalmente ser谩 una mera cuesti贸n de copiar y pegar archivos y quiz谩 modificar alguna configuraci贸n. La pr贸xima vez que se inicie el servidor, el agente deber铆a funcionar.
Usando el gestor de agentes露
El kit de iniciaci贸n de Zoe deber铆a incluir un agente llamado zam. Se trata del Gestor de Agentes de Zoe, cuyo fin es el de facilitar la instalaci贸n y gesti贸n de agentes en la instancia de Zoe. Si el gestor de agentes no est谩 instalado, puedes instalarlo f谩cilmente de forma manual descargando el c贸digo y siguiendo las instrucciones.
El gestor utiliza repositorios git para obtener e instalar agentes. Por ejemplo, el agente dummy tiene la siguiente URL de git:
https://github.com/rmed/dummy_agent.git
Si se quisiera decirle al gestor que instalara este agente, se podr铆a mandar el siguiente mensaje al servidor:
$ echo -n "dst=zam&tag=install&name=dummy&source=https://github.com/rmed/dummy_agent.git" | nc ZOE_HOST ZOE_PORT
O si prefieres usar lenguaje natural y Jabber:
Zoe, install agent "dummy" from "https://github.com/rmed/dummy_agent.git"
Para m谩s informaci贸n sobre el gestor y todos los comandos disponibles, por favor 茅chale un vistazo a la wiki de zam.