This FAQ covers high-level Cougaar questions, such as “What is Cougaar?”, high-level technical questions, and licensing issues.
- What is Cougaar?
- What does Cougaar stand for?
- What is the history of Cougaar?
- Who uses Cougaar?
- Where can I find Cougaar source code?
- Does Cougaar have a project site?
- How can I get involved in Cougaar?
- How can I add to or correct this FAQ or report issues with the Cougaar web site?
- How do I install Cougaar?
- What are the system requirements to run Cougaar?
- What are some commonly reported problems?
- How do I report bugs?
- Where can I find tutorials on writing Cougaar applications?
- What is an Agent?
- What is a Blackboard?
- What is the Cougaar Component Model?
- Which Message Transport protocols are supported?
- How do Cougaar agents find one another?
- Does Cougaar support HTTP interactions?
- What is a Cougaar Domain?
- Does Cougaar support planning and execution?
- Does Cougaar support KQML, ACL, or other high-level knowledge representations?
- What is the Cougaar Bootstrapper?
- Where can I find additional technical documentation?
- How is Cougaar different from other Agent / P2P technologies?
- What is the future plan for Cougaar?
- How does Cougaar compare with JXTA?
- How does Cougaar compare with JINI?
- How does Cougaar compare with Aglets?
- How does Cougaar compare with FIPA and JSR 87?
- How does Cougaar compare with Grid Computing?
- How does it compare to Tomcat Servlet, Jetty Servlet, Spring-context, Java Beans, Camel-context, ActiveMQ?
- What is comparable to Spring’s pool of entities?
- How does it compare to Camel?
- How does it compare to Tibco?
- How does it compare to ServiceMix – an open source ESB from Apache?
- What is the $COUGAAR_INSTALL_PATH?
- Cougaar throws a UnsupportedClassVersionError when started
- Cougaar throws a NoClassDefFoundError in my test
- Cougaar throws a FileNotFoundException when looking for my node “.xml”
- Cougaar prints weird “SHOUT DOTS – ++-.-+-” output
- The message transport prints endless “!”s instead of sending messages
- What are some debugging steps?
- What is the javaiopatch and do I need it?
- Where can I find additional help?
- What is the license model for Cougaar?
- Is the Cougaar license model compatible with other open source licenses?
- Is there any cost to using Cougaar?
- Can I contribute code to Cougaar?
- Can I develop proprietary products using Cougaar?
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.
For additional details, please see our Cougaar Overview slides.
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.
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.
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.
A: Yes, Information on Cougaar projects can be found at Cougaar Projects.
All Cougaar projects hosted on “cougaar.org” are subject to the Cougaar Open Source License.
A: Our (community forum) is an open forum for general questions and specific technical discussion. Note: The forum only available to limited users currently.
A: Please post questions to community forum. Note: The forum only available to limited users currently.
A: Please see our Installation Guide.
A: Cougaar 12.6+ requires Java 1.6 or later. Cougaar 12.4 requires Java 1.5 or higher. Any machine capable of running those Java versions should suffice. Cougaar can take advantage of multiple cores and lots of RAM, but the requirements are highly dependent upon your application’s needs.
The Cougaar architecture team originally developed Cougaar on Windows 98/NT/XP, Linux, Mac OS X, and Java-1.4-capable PDAs. As of 2012, it uses CentOS 5.6+, Mac OS X 10.7, and Windows 7.
There was also a micro-edition of Cougaar that ran on a Java KVM, CougaarME, but it is not longer available. This FAQ covers the JavaSE version of Cougaar.
Cougaar can be configured as a non-distributed system, so network connectivity is not required.
A: Please see the “Commonly Reported Problems” section in this FAQ.
A: Email firstname.lastname@example.org
A: Tutorials and code examples are available on our website’s tutorial list. We have also conducted Cougaar training classes in the past.
This section of the FAQ covers high-level technical questions. Please see our documentation page for additional technical references.
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-Pee 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.
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 persistence 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.
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.
A: The Cougaar architecture includes a Message Transport with pluggable “Link Protocols”. The standard protocols are:
- Loopback in-memory transport (for intra-node traffic)
- SSL-encrypted RMI
- XMPP (Jabber)
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.
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. A deprecated (as of release 12.7) method is the “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).
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.
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.
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 called Vishnu (no link available), 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.
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.
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.
A: Please visit our documentation page.
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.7.
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.
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
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 Cougaar Roadmap 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.
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.
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.
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.
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).
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.
Q: How does it compare to Tomcat Servlet, Jetty Servlet, Spring-context, Java Beans, Camel-context, ActiveMQ?
A: Cougaar is a distributed framework on which domain specific “overlay systems” can be constructed. Cougaar is modularized using a component system that predates Spring, OSGI, NetBeans Modules. Cougaar has some SOA features that are not available in these frame works, such as service binders and the Aspect Pattern, that allow local instances to be composed with “cross cutting”. Also, Cougaar runtime is aware of its environment which makes it easier to write adaptive distributed code.
Cougaar has its own container framework that is NOT OSGI compliant, but has similar features.
The ESB/SOA world took a server oriented and message bus oriented direction. This design space is well covered, but in some sense Cougaar complements. Cougaar can hook into these frameworks either as a distributed data gathering system with intelligent preprocessing. Cougaar could also implement a dissemination system to get data to remote users. Lastly the ESB to ESB link could use Cougaar, but a lot of ESB work has been done in this space, so I would not recommend doing this unless the inter-ESB service needed to be Disruption Tolerant.
Cougaar should NOT be used in the central server. Existing tools have that design space covered.
Q: What is comparable to Spring’s pool of entities?
A: Cougaar has a similar feature, but for distributed societies of agents (group of components), in addition to configuring a single server. No one has integrated Cougaar to use the Spring framework, but this is doable and desirable.
Q: How does it compare to Camel?
A: The Cougaar Message Transport is the equivalent to Camel.
Cougaar does not have explicit process definitions. Cougaar tried to be more dynamic, robust, and adaptive, but in a much smaller context.
Cougaar MTS supports several transports (RMI, HTTP, JMS, DTN, Jabber, Mail, …) and could use Camel as a transport mechanism to interface Cougaar to an ESB. The existing Cougaar tutorials do not cover all of them.
A lot of work in Cougaar was done to decouple the application code from the environment code. This allows the agents to be situated in different environments with only configuration changes. Camel has the same goal but in a message bus oriented world-view.
Q: How does it compare to Tibco?
A: The TIBCO Enterprise Service Bus is very powerful but expensive.
BBN created a link protocol for Tibco. Tibco protocol is not open source. Cougaar uses the open source JMS as a message system as a inter-agent transport.
Q: How does it compare to ServiceMix – an open source ESB from Apache?
A: Again, Cougaar’s niche is to make distributed systems, in particular, intelligent data gathering and control. Service Mix is really good at central servers and we do not recommend using Cougaar as a central server.
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
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).
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.
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:
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 CougaarDeveloperGuide for additional details and configuration options.
A: All Cougaar nodes must specify the name server’s host and port address, either in the -Dorg.cougaar.core.name.server= host:portJava 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.
A: Some steps for debugging Cougaar applications are:
- Enable the debug features in the eclipse arguments or in the runtime config definition from the command line. Set the default node template:
- On a single node:
- For a lan configuration:
- On a single node:
- In a web browser bring up the servlets (note multiple running nodes on the same host will increment the port):
- click on “Local agents on node”
- click on “Node1″ to see system servlets
- To show stuck threads:
- To see the registered agents in the name service
- To see if agents are sending messages
- To see blackboard items in an agent
- select agent
- Open task servlet
- View Black board objects
- Change “Tasks” selector to “UniqueObjects”
- Press “Search”
- select agent
- To show stuck threads:
- To help with threading issues, swap in the trivial thread service for the full thread service (As of 3/16/2012, the Trivial Thread Service is not working; a bug report has been created). If you still get missing blackboard items, then it is a blackboard problem and not a thread service problem.
- Edit the XSL template file in TrimCougaar/configs/common/SimpleAgent.xsl
- Add a “new_template”, on based the single-debug template.
- In eclipse arguments, set the default node template to “new_template”
- Edit the XSL template file in TrimCougaar/configs/common/SimpleAgent.xsl
- Alternatively for thread issues, if you suspect there is a race condition, you can insert sleeps rather than increasing logging levels.
- A moderately common developer error is to incorrectly assume that all updates to objects happen in a single transaction. They can take multiple transactions, especially with multiple threads writing.
You might see in older Cougaar documentation or examples:
<!-- Use our JDK over-rides for persistence --> <vm_parameter>-Xbootclasspath/p:"$COUGAAR_INSTALL_PATH/lib/javaiopatch.jar"</vm_parameter>
This was a fix that allowed the complex objects in the planning package (tasks, allocations, etc.) to be persisted (and hence also to move with the agent). Unfortunately, that patch has not survived the changes made in recent versions of Cougaar, including the upgrade to Java 1.6. In the future, we hope to restore this capability, but for now it should not be used. Try removing that line in the society definition, or replace with:
<vm_parameter name="-Dorg.cougaar.core.persistence.verifyJavaIOPatch" value="false"/>
A: The Cougaar license was updated in Cougaar release 11.0 to closely mirror the OSI approved BSD License. The primary difference between the BSD License and the Cougaar License is the addition a DARPA acknowledgement and endorsement restriction. If you have any questions, please contact us.
A: Yes, and you are encouraged to do so. Our project site contains submission instructions.
A: Yes. Derivative works (modifications to Cougaar source code itself) must preserve the Cougaar License and be submitted back to our website. All other products can be proprietary, adopt the Cougaar license, or adopt any other license. Of course, see the license for a definitive answer.