Cougaar Quick Start Guide

Introduction

This document will help the novice Cougaar user get Cougaar installed, and get a simple Cougaar application running. From there, users will turn to the Tutorials for learning about the workings of Cougaar, the Cougaar Developers Guide for details on developing components, and the Javadoc and source for Cougaar.

What is Cougaar?

The Cognitive Agent Architecture (Cougaar) is a Java-based architecture for the construction of large-scale distributed agent-based applications. It is a product of two consecutive, multi-year DARPA research programs into large-scale agent systems spanning eight years of effort.

Cougaar provides developers with a framework to implement large-scale distributed agent applications with minimal consideration for the underlying architecture and infrastructure. The Cougaar architecture uses the latest in agent-oriented component-based design and has a long list of powerful features.

For more information on Cougaar, see our open source site, and in particular the FAQ

Installing Cougaar

For instructions on installing Cougaar, see the Install Guide.

Configuring Cougaar

Cougaar societies are made of Nodes (JVMs), which contain Agents, which in turn contain components. All of this configuration data is preferably specified in an XML file. (Note that some existing societies may still use the deprecated CSMART database or “INI” files.)

The current method for configuring a Cougaar society is through the use of XML configuration files. The configuration file performs the mapping of Components to Agents, Agents to Nodes and Nodes to Hosts.

As an example, the basic installation of Cougaar contains a simple XML society configuration; Pizza Party located in pizza/configs/pizzaparty that can be run without modification. See pizza/docs/Readme.html for details.

Running Cougaar

To run Cougaar, you simply use the “Cougaar[.bat]” script. It takes as an argument, the name of the XML file specifying your society, and the name of the Node to run. See the script’s help for details. Note in particular that you may specify various VM parameters on the command line, or in your society.xml. Note in particular that COUGAAR_DEV_PATH should point to your custom developed classes that over-ride or replace Cougaar classes. Do not use the CLASSPATH environment variable.

For example, to run the Pizza society on a Windows machine, do:

$ cd %COUGAAR_INSTALL_PATH%\pizza\configs\pizzaparty
$ %COUGAAR_INSTALL_PATH%\bin\Cougaar.bat SDPizzaNode1.xml
COUGAAR 11.4 built on Tue Dec 07 07:04:16 GMT 2004
Repository: HEAD on Tue Dec 07 07:00:08 GMT 2004
VM: JDK 1.4.2_06-b03 (mixed mode)
OS: Windows 2000 (5.0)
16:52:11,680 SHOUT - XMLComponentInitializerServiceProvider - Initializing node "SDPizzaNode1" from XML file "SDPizzaNode1.xml"
...

(Note that the periods shown above indicate the node has “quiesced”, as described below in Monitoring a Society.)
Then start the second node in another window:

$ cd %COUGAAR_INSTALL_PATH%\pizza\configs\pizzaparty
$ %COUGAAR_INSTALL_PATH%\bin\Cougaar.bat SDPizzaNode2.xml
COUGAAR 11.4 built on Tue Dec 07 07:04:16 GMT 2004
Repository: HEAD on Tue Dec 07 07:00:08 GMT 2004
VM: JDK 1.4.2_06-b03 (mixed mode)
OS: Windows 2000 (5.0)
16:52:11,680 SHOUT - XMLComponentInitializerServiceProvider - Initializing node "SDPizzaNode2" from XML file "SDPizzaNode2.xml"
...

Monitoring a Cougaar Society

Once a cougaar society is created and run, there are various methods that can be used to monitor progress of the society.

When a node is started, various status messages are displayed in the console window indicating the current state of the society. The following is a summary of each of these message tokens:

‘+’ A message has been received from another Agent
‘-’ A message has been sent to another Agent
‘.’ Node activity has “quiesced,” meaning that no messages have been sent or received and no Plugins have been invoked in the last 5 seconds.
‘P’ Persistence information has been saved
‘R’ Rescind messages have been received from another Agent
‘!’ This indicates that no name server has been contacted. If these messages continue, check that your alpreg.ini files are identical and point to a machine with a running Node.

Cougaar also contains an embedded servlet engine and some useful society monitoring servlets. These can be viewed, while the society is running, at http://localhost:8800. Two useful monitoring servlets are: /agents (to list the running agents on a Node) and /tasks (to display the objects on the Blackboard of an Agent).

Another formerly useful, but now deprecated, tool that provides the ability to graph the society and task flows is the CSMART Society Monitor. For more information on using this tool, see the CSMART Install document.

Next Steps

Now that you have installed Cougaar, and run your first Cougaar society, you are ready for more complex societies.

For example, you could split up the Pizza configuration across more Nodes / hosts. Or change the set of components loaded in the agent.

Learning More

To learn more about Cougaar agents and societies, and examples on creating your own agents, see the Tutorial List

For more advanced discussions of developing Cougaar components, see the Cougaar Developer Guide v11.4. Some of the details have changed since v11.4, but overall architecture is still accurate.

There is a community of Cougaar developers, so there are a number of resources available to help you solve your problems:

Bibliography

2007

Wright, Todd

Cougaar Design Case Study: Mandelbrot GUI Application (Presentation)

.

2004

BBN,

Cougaar Architecture v11.4 (Techreport)

2004.

Team, Cougaar

Cougaar Developers' Guide v11.4 (Techreport)

2004.

Wright, Aaron Helsinger, Michael Thome, Todd

Cougaar: A Scalable, Distributed Multi-Agent Architecture (Article)

2004.