Cougaar FAQ

This FAQ covers high-level Cougaar questions, such as "What is Cougaar?", high-level technical questions, and licensing issues.

A: Cougaar is a Java-based architecture for the construction of highly scalable distributed agent-based applications. Cougaar is the product of a multi-year DARPA research project to develop an open-source agent-based architecture that supports applications ranging from small-scale systems to large-scale highly-survivable distributed systems. Cougaar includes an advanced core architecture and a variety of of components that simplify the development, visualization, and management of complex distributed applications.

Q: What does COUGAAR stand for?

A: COUGAAR is an acronym for "Cognitive Agent Architecture," due to the Cougaar planning domain's model of Tasks, Workflows, Expansion, and Aggregation. This is a legacy definition, since the architecture has been refactored to a comprehensive agent-based middleware that also supports non-planning applications.

Q: What is the history of Cougaar?

A: Cougaar started in 1996 as ALP, "The Advanced Logistics Project," which was a DARPA funded project to model military logistics using distributed agent technologies. BBN was the primary contractor and continues as a key Cougaar developer.

In 2001 ALP transitioned to a new DARPA project, Ultra*Log, to enhance the scalability, security, and survivability of the underlying agent system. Cougaar was the underlying architecture of Ultra*Log and contains most of the logistics domain code. Ultra*Log concluded at the end of 2004, at which time Cougaar became a purely open source project, though it may continue under one or more defense-sponsored projects.

The open source community has adopted Cougaar in non-military applications ranging from embedded sensor webs to business intelligence applications. Some uses were presented at Open Cougaar 2004.

The open source community has a Support project, where you may learn more about our support plans.

Q: Who uses Cougaar?

A: The primary client of Cougaar has been the US military, but the architecture is component-based and has been used by the open source community for other agent-based applications, including commercial applications.

Please see our project site for the latest news on open source project activity and download statistics.

Q: Where can I find Cougaar source code?

A: Cougaar is an open source project. Release builds and source code are available on our website: http://www.cougaar.org. A CVS tree, ANT compilation scripts, and nightly builds are also available on the same site.

Q: Does Cougaar have a project site?

A: Yes, Cougaar has a SourceForge-style project site that is open to Cougaar developers: http://cougaar.org. Cougaar projects have their own bug tracking system, mailing list, and CVS repository.

All Cougaar projects hosted on "cougaar.org" are subject to the Cougaar Open Source License.

Q: How can I get involved in Cougaar?

A: Our mailing list (cougaar-developers@cougaar.org) is an open forum for general questions and specific technical discussion. CougaarForge, our project management site, hosts Cougaar projects.

Q: How can I add to or correct this FAQ or report issues with the Cougaar web site?

A: Please send email to support-csc-info@cougaar.org.

Getting Started (Newbies) FAQ

Q: How do I install Cougaar?

A: Release builds can be found on our website. As of July 2005, the current release is Cougaar 12.0. Builds are available as either a single ZIP file or a wizard-based installer.

Basic Getting Started guidelines are availabe in our Getting Started guide.

Installation and configuration documentation is included in the Cougaar Developers' Guide.

Q: What are the system requirements to run Cougaar?

A: Cougaar requires Java 1.4.2 or later. Any machine capable of running Java 1.4.2 should suffice. The Cougaar architecture team develops on Windows 98/NT/XP, Linux, Mac OS X, and Java-1.4-capable PDAs.

There's also a micro-edition of Cougaar that runs on a Java KVM (CougaarME). This FAQ covers the JavaSE version of Cougaar.

Cougaar can be configured as a non-distributed system, so network connectivity is not required.

Q: What are some commonly reported problems?

A: Please see the "Commonly Reported Problems" section in this FAQ.

Q: How do I report bugs?

A: Please see our bug and enhancement tracking site.

You can also ask our developer community mailing list.

Q: Where can I find tutorials on writing Cougaar applications?

A: Tutorials and code examples are available on our website's tutorial project. We also conduct Cougaar training classes -- see the website for a schedule and registration details.

High-level Technical FAQ

This section of the FAQ covers high-level technical questions. Please see our documentation page for additional technical documentation.

Q: What is an Agent?

A: Cougaar defines an Agent as a software entity which autonomously communicates with other software Agents to achieve domain-specific functionality. Multiple agents often collaborate as peers in a Peer-to-Peer (P2P) distributed network. The complexity of each agent can range from simple embedded sensors to a highly complex artificial intelligence application.

Cougaar is a framework for developing distributed multi-agent applications. The Cougaar architecture includes components to support agent-to-agent messaging, naming, mobility, blackboards, external UIs, and additional (pluggable) capabilities. Developer write components, also called "plugins", which are loaded into agents to define their behavior. The Cougaar Component Model allows the developer to configure Cougaar to match both their domain and system requirements / constraints.

Additional information on agent-based computing can be found at http://www.multiagent.com and http://agents.umbc.edu

Q: What is a Blackboard?

A: A Blackboard is an agent-local memory store that supports publish/subscribe semantics. Components within the agent can add/change/remove objects from the blackboard and subscribe to local add/change/remove notification. Agent domains monitor the local blackboard and can send messages to other agents and alter the blackboard when the local agent receives messages.

The primary benefit of an agent blackboard is that it abstracts the message transport from the plugins. The Cougaar infrastructure provides the blackboard and message transport, which frees developers to concentrate on the domain-specific issues of their application.

Another benefit of the publish/subscribe pattern is that it encourages developers to write components that publish actions and asynchronously wake when the answer arrives, instead of wiring components together with blocking method-call APIs. The publish/subscribe pattern offers greater parallelism and scalability.

Cougaar blackboards are agent-local to assure scalability. A globally shared blackboard (e.g. JavaSpaces or JMS) is a single point of failure and a considerable performance bottleneck.

Cougaar blackboards also support automatic persistence, rehydration, and dynamic reconciliation. Persistence can be configured in an optimized "lazy" mode, where periodic blackboard "delta" snapshots are captured to reduce persistence I/O overhead. Rehydration allows a restarted agent to resume its state from the most recent perisistence snapshot. Dynamic reconciliation allows an agent to recover from partial or full persistence state loss by scanning the blackboards of agents that it has communicated with in the past.

Q: What is the Cougaar Component Model?

A: The Cougaar Component Model is a service-based framework that is used to connect components together at runtime. Cougaar agents use the Cougaar Component Model to dynamically load components and advertise new service capabilities.

The Cougaar Component Model is similar to Java Beans, in that the Cougaar Component Model defines a component hierarchy and service APIs. Cougaar's Component Model features no Swing UI dependencies, reduced thread locking, better service management, and adds service binders.

The Cougaar Component Model supports pluggable components that can be added and removed at runtime. Components specify a point in a containment hierarchy. Service APIs are advertised through Service Brokers, and Components can obtain these Services at runtime. Binders are pluggable Service proxies which can be placed in between the Services and the Components to add security and manage Service usage. Additional details are provided in the Cougaar Architecture Document.

The Cougaar Component Model can also be used in non-agent applications as a highly generic pluggable service-based framework.

Q: Which Message Transport protocols are supported?

A: The Cougaar architecture includes a Message Transport with pluggable "Link Protocols". The standard protocols are:

Loopback in-memory transport (for intra-node traffic)

Additional Ultra*Log protocols include plain TCP Sockets, UDP, SMTP, and NNTP. Third-party developers can write new link protocols and plugin them into Cougaar.

Components can also advertise services for additional I/O access, such as a JDBC service or JXTA service.

Q: How do Cougaar agents find one another?

A: Cougaar includes distributed naming support for finding other Cougaar agents. The current implementation includes an in-band "White Pages", which is a DNS-styled distributed registry of agent protocol addresses, and a "Yellow Pages", which is a UDDI-based repository for dynamic service discovery. Additional discovery protocols can be added by using pluggable Cougaar components (e.g. JNDI or JXTA).

Q: Does Cougaar support HTTP interactions?

A: Yes, Cougaar includes a component-based Servlet server, an embedded variant of Tomcat. Components can obtain the "ServletService" and register an HTTP path within that agent. For example, a component within agent "Test" can register the path "/x", which will be accessable as "http://localhost:8800/$Test/x". The Cougaar naming service redirects requests to the node running the specified agent. The port and HTTP/HTTPS configuration can be configured within Cougaar and Tomcat XML files.

Servlets are often preferred over popup UIs, such as Swing, to ensure scalability and agent mobility. External browsers and Swing-based UI applications are typically used to monitor agent progress.

Q: What is a Cougaar Domain?

A: A Cougaar Domain is a suite of pluggable components that support an application developer. A Domain includes data structures, blackboard messaging "Logic Providers", and utility components.

The "root" domain is always loaded by the Cougaar architecture. The root domain implements a minimal "Relay" API for agent-to-agent message transport.

Additional domains can be developed and plugged into the Cougaar Architecture, such as the planning domain.

Q: Does Cougaar support planning and execution?

A: Yes, Cougaar includes a "planning" domain and support libraries.

The planning-specific data structures include tasks, workflows, schedules, multi-point scoring functions, and other objects. Property-based assets are also supported, which allows a developer to define physical assets by dynamic properties (e.g. "can move on water") instead of a fixed hierarchical taxonomy (e.g. "is a boat"). The domain includes blackboard support that helps automate the behavior of these data structures, such as recursive deletion of subtasks when a parent task is deleted.

Utility components include rule-based workflow expanders/aggregators, GA-based schedule optimizers, and inventory models.

Plan execution is supported by the advance of a simulated global "planning" clock. Components can schedule alarms to wake them in either planning-time or wallclock-time. The planning-time can either be advanced by a simple global broadcast or developer-defined per-agent components that are backed by a more complex mechanism.

Q: Does Cougaar support KQML, ACL, or other high-level knowledge representations?

A: Not directly -- Cougaar is an architecture that uses Java-based message representation. The contents of the message are defined by pluggable Cougaar domain components. Cougaar includes domain support for planning and logistics, including a rich language of tasks, relationship schedules, and physical-asset property groups.

Cougaar as a project has focused on highly-scalable architecture capibilities and pluggable component-based design. Compliance with standards-based APIs for high-level knowledge representations and domain specific languages has been a low priority.

Please see the notes below on FIPA agent standards.

Q: What is the Cougaar Bootstrapper?

A: The Cougaar Bootstrapper is an executable JAR that is used instead of the Java "-classpath".

The Bootstrapper scans the $COUGAAR_INSTALL_PATH's "lib/" and "sys/" subdirectories for all ".jar" files and loads them as if they were specified in the Java "-classpath". By convention the lib directory contains Cougaar JAR files, and the sys directory contains third-party JAR files. Developers can add new JAR files to the lib and sys directories. Another option is to specify the system property -Dorg.cougaar.class.path=PATH, which acts in a similar fashion as Java's "-classpath".

Typical usage is illustrated in the Cougaar startup script (bin/Node):

  java \
    -Dorg.cougaar.install.path=$COUGAAR_INSTALL_PATH \
    [additional -D properties] \
    -jar $COUGAAR_INSTALL_PATH/lib/bootstrap.jar \
    org.cougaar.core.node.Node \                     # or any other class
    [additional command-line arguments]

Of course, you can configure Cougaar to not use the bootstrapper and instead specify all the required jars in the Java "-classpath". This tends to be annoying if you have lots of JAR files.

The bootstrapper is a generic utility that is used by Cougaar Agents and several non-Cougaar UIs.

Q: Where can I find additional technical documentation?

A: Please visit our documentation page for:

The latest version of this FAQ
The Cougaar White Paper
The Cougaar Architecture Document
The Cougaar Developers' Guide
Journal papers and more...

Mail archives can be found here.

The latest Cougaar Javadoc is available online, along with the release notes.

Our project site hosts the tutorials and workshop slides.

The Cougaar Support Committee page lists papers presented at Open Cougaar 2004.

Cougaar and other Technologies

Q: How is Cougaar different than other Agent / P2P technologies?

A: Cougaar is a highly configurable architecture with many capabilities, which makes it difficult to sum up. Here are some characteristics that we find unique:

The Cougaar Component Model allows a Cougaar agent to be tailored from minimal single-host embedded applications to highly distributed heavy-weight applications. The service-based framework allows developers to add new components without altering the architecture APIs.

Cougaar is a stable architecture that is currently on version 12.0.

The Cougaar architecture is built with scalability in mind. Under the Ultra*Log project, Cougaar agent societies of over 200 agents running on 30 machines have coordinated to develop complex military logistics plans.

Cougaar adds the concept of agent-local blackboards, which abstracts the message transport from the application developer.

Q: What is the future plan for Cougaar?

A: DARPA has funded Cougaar as a research project in agent-based systems. These capabilities have been of primary interest:

Scalability to 1000+ agents over 100+ hosts

Survivability to attack (robustness, security, adaptivity)

Utilization of degraded network capabilities and other resources

Distributed debugging and runtime management

Design patterns for highly distributed agent systems

Relevance to future military logistics planning systems

As of then end of 2004, Cougaar remains an open source project and may continue to be sponsored under one or more defense projects.

The open source community has influenced Cougaar's design to be more composable and domain-neutral. For example, the open source community has enhanced the Cougaar planning domain to better handle planning constraints. For ideas on future plans, see our Roadmap Wiki page. For details on the support committee operations, see the Support Committee Project page.

Additional projects have focused on embedding Cougaar as network-aware middleware. This has guided Cougaar to develop minimal footprint configurations and enhanced message transport capabilities.

Q: How does Cougaar compare with JXTA?

A: JXTA is a Peer-to-Peer framework for distributed applications. JXTA supports peer group communications and dynamic discovery protocols.

Cougaar features agent communities, which act as simple group-based communications. Service discovery within Cougaar uses a UDDI YellowPages. In the future Cougaar might explore LAN discovery protocols (such as JINI) and enhanced peer-based group communications. For now JXTA can be embedded within Cougaar as a pluggable component.

As you may have noticed, our FAQ follows a similar outline to the JXTA FAQ.

Q: How does Cougaar compare with JINI?

A: JINI is a framework for advertising services on the local network and a discovery mechanism for systems to obtain and lease those services. RIO is an architecture that simplifies JINI development and deployment.

Cougaar agents uses distributed naming to find other agents, similar to the Internet DNS and UDDI. In contrast, JINI utilizes on LAN-local discovery protocols, where each JINI peer is scoped to the local network.

Cougaar agents must define their services using agent-specific messages, which are free to define leasing structures and domain-specific service negotiation. JINI defines services as RMI Objects and has a built-in intra-agent service model.

Q: How does Cougaar compare with Aglets?

A: Aglets is the IBM framework for mobile agent applications. The primary job of Aglet agents is to "roam the Internet" and execute on remote hosts.

Cougaar also supports agent mobility, primarily for load balancing, but this isn't the focal point of the Cougaar architecture. The Cougaar Component Model and blackboard offer greater support for complex agents.

Q: How does Cougaar compare with FIPA and JSR 87?

A: FIPA defines an interaction standard for heterogeneous agent systems. JSR 87 is the Java Specification Request to define a "javax.agent" API that corresponds to the FIPA specification. Popular FIPA-compliant architectures include FIPA-OS and Jade.

Cougaar currently implements neither API, although this could be implemented if there was sufficient demand. The "javax.agent" API is fairly simple. To date, Cougaar developers have been content to stay within the bounds of Cougaar agents and non-agent systems (e.g. JDBC). Discussion is welcome on our mailing list.

The Cougaar message transport and domains are pluggable components, so it's possible to replace these components with alternate implementations or write a translation bridge.

Q: How does Cougaar compare with Grid Computing?

A: Grid Computing is a branch of peer-to-peer computing that utilizes spare cycles on distributed machines (i.e. "compute farms"). A classic example is the SETI@Home project. There are many grid architectures (Sun, IBM, OGSA, etc) that offer vastly different capabilities, from lightweight number-crunching engines to enterprise solutions.

Cougaar, as a flexable peer-to-peer architecture, could be used as a grid engine. The primary difference between Cougaar and most grid engines is that Cougaar developers often write autonomous, heterogeneous agents instead of anonymous computing clients.

A Cougaar-to-OSGA bridge should be possible and would make an interesting project.

Commonly Reported Problems

These questions are often seen on our mailing list:

Q: What is the $COUGAAR_INSTALL_PATH?

A: The $COUGAAR_INSTALL_PATH is an environment variable that specifies the path of your Cougaar installation. It corresponds to the -Dorg.cougaar.install.path Java system property. This system property is used to configure the Cougaar Bootstrapper and ConfigFinder

Q: Cougaar throws a UnsupportedClassVersionError when started

A: Cougaar requires Java 1.4 or later. An earlier Java version will throw an UnsupportedClassVersionError with a message such as (Unsupported major.minor version 48.0).

Q: Cougaar throws a NoClassDefFoundError in my test

A: This is often caused by misuse of the Cougaar Bootstapper verses the Java "-classpath". New jars must be added to the $COUGAAR_INSTALL_PATH/lib or $COUGAAR_INSTALL_PATH/sys directories, or a -Dorg.cougaar.class.path Java system property can be used. See the notes on the Cougaar Bootstrapper.

Q: Cougaar throws a FileNotFoundException when looking for my node ".xml"

A: Try running from the directory containing the configuration files.

Cougaar has a ConfigFinder class that is used to find the ".xml" files. The default path is:

    $CWD;$HOME/.alp;$COUGAAR_INSTALL_PATH/configs/common

Developers can override this path by setting the -Dorg.cougaar.config.path Java system property.

Q: Cougaar prints weird "SHOUT [DOTS] - ++-.-+-" output

A: This is a normal progress indicator. Each character represents an action by the agent:

  +  An agent sent a message
  -  An agent received a message
  .  A "dot" is printed every 5 seconds (lots of dots probably means the node is idle)
  P  The blackboard was scheduled to persist (does nothing if persistence is disabled)
  R  A planning task was rescinded

A new line is started when either the line exceeds 50 characters or logging output is printed. See the Cougaar Developers' Guide for additional details and configuration options.

Q: The message transport prints endless "!"s instead of sending messages

A: All Cougaar nodes must specify the name server's host and port address, either in the -Dorg.cougaar.core.name.server=host:port Java system property or in the $COUGAAR_INSTALL_PATH/configs/common/alpreg.ini configuration file. The "!" standard output indicates that the local node can't access the Cougaar name server.

Sometimes this is caused by IP hostname confusion, where one machine will respond to 'hostname' with "localhost.localdomain" instead of the correct host name. Try sending a ping from one machine to the next, to verify that the host names are correct and that network firewalls are not blocking the agents. Debug output can be generated from within Cougaar by enabling the -Dorg.cougaar.nameserver.verbosity=2 Java system property.

If the above fails, you can specify the IP address instead of the host name.

Q: Where can I find additional help?

A: The Cougaar Technical FAQ covers additional trouble-shooting. The tutorials will help new users. And there are many other documents. Bugs and enhancement requests are tracked on our bug tracking site. You can also send email to our mailing list.