Welcome to Zoe!¶

Agents¶

The zoe.conf file contains a list of agents with their corresponding ports and a list of agents related to a specific topic. For more information check the Agents section of this documentation.

Some agents, such as the Twitter agent, may include additional configuration files. In this case, twitter.conf contains the credentials required by the Twitter agent. These credentials can be obtained from the Twitter profile.

The zam directory is part of the Zoe Agent Manager, in charge of installing and managing agents. For more information, check the Agent installation section.

Environment¶

The environment.sh script sets several variables such as the server host, twitter credentials, jabber information, etc. It has the following content:

# 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"

You should never give Zoe your own twitter/jabber credentials. Create a new account if you intend to use them.

• By default, the Jabber and GMail accounts use the same credentials due to the Google Talk (Hangouts) service using Jabber. You can use other Jabber service and email provider if you wish so.

Users¶

The zoe-users.conf file follows this structure:

[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

Each user is identified using the [subject USER] tag and has the following attributes:

• name: The user’s name (e.g. Zoe).
• twitter: The user’s twitter username (e.g. gul_zoe).
• preferred: The preferred way for Zoe to communicate with the user. Available values are twitter, jabber, mail.
• jabber: The user’s jabber address. Note that if you are using Google Hangouts, the jabber addresses have the format abcdefghijklmnopqrstuwxyz1@public.talk.google.com. If you don’t know this address, you may try speaking with Zoe through Jabber and getting the address from the logs.
• mail: The user’s mail address.
• alias: The user’s alias.

Some agents may use groups to send mails to several users at the same time or check for user permissions. Define a new group by using the scructure [group GROUPNAME] and adding its users to the members attribute.

Structure¶

Agents usually consist of 1-2 files, although this is completely up to the agent’s developer. Most of the agents are written in Python, but libraries are available for writting agents in languages such as Bash, Java, Python, etc.

The main script is placed in the agents/AGENT_NAME directory. The agent can also include natural language commands for executing actions on demand without the need of using the command-line to manually send the message to the server. This way, an user can speak with Zoe through, for instance, Jabber. These natural language commands are placed in the cmdproc/ directory.

Message structure¶

Agents interchange messages through the server message bus. These message strings have a key-value structure of the form:

key1=val1&key2=val2&key3=val3...

For instance, the broadcast agent can send a message to a specific user. The message string to do so would look like this:

dst=broadcast&tag=send&msg=Hello World!&to=john

Now, analyzing the message:

• dst: Agent that is supposed to receive this message.
• tag: Action to perform. There can be several tag entries in the message.
• msg: Message to send to the user.
• to: User to send the message to. This name is checked against the user list to see what John’s address and preferred contact method are.

The message string will vary depending on each agent, but most of them will have common parts such as dst and tag.

Sending messages to the server¶

Apart from the agents interchanging messages, it is also possible to manually send a message to the server in order to have an agent execute some action. Taking the previous broadcast agent example, the message could be sent like so:

$ echo -n "dst=broadcast&tag=send&msg=Hello World!&to=john" | nc ZOE_HOST ZOE_PORT

Now, the logs/broadcast.log file would have an entry for the received message and the action executed (or any errors while doing so).

Manual installation¶

Installing an agent manually requires that you download the code and place it in the Zoe installation according to the agent developer’s instructions. Usually, it will just be a matter of copying and pasting files and maybe modifying some configurations. When the server is started the next time, the new agent should be up and running.

Using the agent manager¶

The Zoe startup kit should include an agent named zam. This is the Zoe Agent Manager, which aims to facilitate the installation and management of agents in your Zoe instance. If the Zoe Agent Manager is not installed, you can easily install it manually by downloading the source and following the provided instructions.

The manager uses git repositories to fetch and install agents. For instance, the dummy agent has the following git source URL:

https://github.com/rmed/dummy_agent.git

If you were to tell the manager to install this agent, you could send this message to the server:

$ echo -n "dst=zam&tag=install&name=dummy&source=https://github.com/rmed/dummy_agent.git" | nc ZOE_HOST ZOE_PORT

Or, if you prefer using natural language and Jabber:

Zoe, install agent "dummy" from "https://github.com/rmed/dummy_agent.git"

For more information on the manager and all the commands it has, please check the zam wiki.