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.
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 http://www.cougaar.org, and in particular the FAQ: http://cougaar.org/docman/view.php/17/55/FAQ.html
For instructions on installing Cougaar, see the Install Guide.
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.
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"
...
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"
...
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 useful 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.
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.
To learn more about Cougaar agents and societies, and examples on creating your own agents, see: http://tutorials.cougaar.org/.
For more advanced discussions of developing Cougaar components, see the Cougaar Developers Guide, available on the Cougaar web site: http://cougaar.org/docman/?group_id=17.
There is a significant community of Cougaar developers, so there are a number of resources available to help you solve your problems.
· Bugs and Requests For Enhancements can be reported on the Cougaar Bugzilla web site at http://bugs.cougaar.org/
· Community support mailing lists. See http://www.cougaar.org/mail/ for information on subscribing and archives.
- Cougaar-developers@cougaar.org is a community support mailing list. Many developers of Cougaar applications and infrastructure read and post here.
- Cougaar-information@cougaar.org is a forum for announcing software updates, workshops, training sessions, and conferences.
- Cougaar-help@cougaar.org is for licensing issues, requests for high-level information and web-site comments.
· Frequently Asked Questions (FAQ). See http://cougaar.org/docman/view.php/17/55/FAQ.html.
· Conferences and Workshops. Post a request to cougaar-help@cougaar.org if you are interested in attending a Cougaar conference, workshop or training. Watch for course or workshop announcements on the Cougaar web site, at http://cougaar.org.