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

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.

Each of the demos described on the Tutorials page (including the simplest, the Hello world demo) contains a simple XML society configuration. All the demos can be run without modifications, and each has a file docs/Readme.html that contains more details.

Running Cougaar

The recommended application to run for a quick start is the Hello World demo because of its simplicity.

As of release 12.7, there are two ways to run Cougaar as described in Running Cougaar. For new users familiar with Eclipse, the recommended method of running for a quick start is the Eclipse-based development mode; for those not familiar with Eclipse, the recommended method is the command-line-based deployment mode.

In Eclipse, after importing the Cougaar base code and the hello project containing the Hello World demo, the user need just run the launcher hello/eclipse/helloWorld.launch. Something similar to the following output should appear in the console window:

COUGAAR 12.7 built on (unknown time)
Repository: (unknown tag) on (unknown time)
VM: JDK 17.1-b03 (mixed mode)
OS: Windows 7 (6.1)
2012-07-11 10:43:28,465 SHOUT [XMLComponentInitializerServiceProvider] - Initializing node "Node1" from XML file "C:\Cougaar\workspace5\tutorials\hello\configs\HelloWorldSociety.xml"
2012-07-11 10:43:38,229 SHOUT [HelloWorldPlugin] - AgentA: Hello, World!

Windows command-line installation

Alternatively, from the command line, the user should do the following, assuming that the Cougaar base code is installed at C:\Cougaar and the application code is installed at C:\CougaarApps:

set COUGAAR_INSTALL_PATH=C:\Cougaar\
set COUGAAR_SOCIETY_PATH=C:\CougaarApps\hello
set COUGAAR_RUNTIME_PATH=C:\CougaarApps\hello\run
cd %COUGAAR_RUNTIME_PATH%
%COUGAAR_INSTALL_PATH%\bin\cougaar.bat %COUGAAR_SOCIETY_PATH%/configs\HelloWorldSociety.xml %COUGAAR_RUNTIME_PATH%/SingleNodeRuntime.xml

Linux/Mac command-line installation

Alternatively, from the command line, the user should do the following, assuming that the Cougaar base code is installed at /opt/cougaar and the application code is installed at /opt/CougaarApps:

export COUGAAR_INSTALL_PATH=/opt/Cougaar/
chmod a+x $COUGAAR_INSTALL_PATH/bin/cougaar	# necessary only once after installation
export COUGAAR_SOCIETY_PATH=/opt/CougaarApps/hello
export COUGAAR_RUNTIME_PATH=/opt/CougaarApps/hello/run
cd $COUGAAR_RUNTIME_PATH
$COUGAAR_INSTALL_PATH/bin/cougaar $COUGAAR_SOCIETY_PATH/configs/HelloWorldSociety.xml/ $COUGAAR_RUNTIME_PATH/SingleNodeRuntime.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

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: