🔱 PlantUML - AML Edition

Version 1.2026.01-AML | Date: January 2026

Abstract

As Multi-Agent Systems (MAS) increase in complexity, the need for robust, versionable, and communicable modeling techniques becomes paramount. The Agent Modeling Language (AML) provides a comprehensive semi-formal visual notation for MAS specification, yet traditional graphical tools often struggle with modern DevOps workflows. This white paper presents a framework for implementing AML within PlantUML, a widely adopted text-to-diagram engine. This implementation covers the core AML v0.9 specification and incorporates advanced mechanisms from the 2007 AML monograph (Cervenka & Trencansky), including mobility, context-based modeling, and behavior decomposition. By mapping AML's rich metamodel to a textual surface language, this project provides a toolchain that is both expressive for architects and ergonomic for developers, enabling seamless integration into continuous integration pipelines.

1. Introduction

The design and documentation of Multi-Agent Systems (MAS) require specialized abstractions to capture the unique properties of agents, such as autonomy, sociality, and mental attitudes. While the Unified Modeling Language (UML) serves as a foundation, it lacks first-class support for agent-oriented concepts. The Agent Modeling Language (AML) was developed to bridge this gap, offering a consistent set of extensions for structural, social, mental, and behavioral viewpoints.

However, the adoption of MAS modeling is often hindered by the limitations of "heavyweight" graphical CASE tools. These tools frequently produce binary artifacts that are difficult to version-control, compare, or integrate into automated documentation workflows. This paper proposes a "lightweight" alternative: a text-based implementation of AML using PlantUML. This approach allows architects to write models in a concise domain-specific language that compiles into high-quality diagrams, facilitating "Modeling as Code" (MaC) practices.

2. Background and Motivation

2.1 The Agent Modeling Language (AML)

AML, as specified by Whitestein Technologies (2004) and expanded by Cervenka & Trencansky (2007), is a comprehensive modeling language designed for MAS engineering. It organizes system descriptions into several interdependent views:

• Structural: Entity types (agents, resources, environments).
• Social: Roles, organizations, and social relationships.
• Mental: Internal states including beliefs, goals, and plans.
• Behavioral: Services, protocols, and capabilities.

2.2 Textual Modeling and PlantUML

PlantUML has emerged as a standard for textual diagramming, utilizing a simple syntax to generate UML-compliant diagrams. Its support for preprocessing macros and custom stereotypes makes it an ideal engine for hosting higher-level modeling languages like AML. By leveraging PlantUML, AML models can be stored as plain text, allowing for efficient branching, merging, and automated rendering within CI/CD environments.

3. The AML for PlantUML Framework

The framework provides a complete environment for AML modeling, structured around a core profile and specialized modules.

3.1 Design Principles

1. Metamodel Fidelity: Ensure a 1-to-1 mapping between AML concepts and the generated PlantUML artifacts.
2. Textual Ergonomics: Use native domain-specific keywords to express complex agent-oriented concepts concisely, allowing the modeler to focus on semantics.
3. Modularity: Provide a layered architecture where optional modules (e.g., Ontology, Sequence) can be enabled as needed.
4. Visual Consistency: Implement a standardized color palette and iconographic representation based on AML conventions.

3.2 Architecture

The framework is deeply integrated into the PlantUML core engine, providing native parsing for AML constructs. It consists of specialized diagramming engines:

• AML Class Engine: Supports structural and social modeling using native keywords.
• AML Sequence Engine: Handles communicative acts and interaction protocols.
• AML State Engine: Provides specialized support for lifecycles and state machines.
• AML Activity Engine: Implements behavioral modeling with native actions.
• AML Description Engine: Supports high-level component-based descriptions.

4. Multi-Perspective Modeling

4.1 Structural and Social Viewpoints

The framework supports the full hierarchy of AML entity types. Agents, resources, and environments are represented with distinct visual styles. Social dynamics are captured through role-playing associations and organizational structures.

@startaml
agent SearchAgent {
  capabilities: String[*]
  --
  executeSearch()
}
role Worker {
  status: String
  --
  performTask()
}
SearchAgent plays Worker
@endaml

4.2 Mental Attitudes and Cognitive Architectures

AML's mental model is implemented through dedicated keywords for beliefs, goals, and plans. These elements can be linked via causal relationships such as achieved-by or input-to, allowing for the modeling of complex BDI (Belief-Desire-Intention) architectures.

4.3 Behavioral and Interaction Protocols

Interactions are modeled using an enhanced sequence diagram syntax. The framework provides a palette of FIPA-compliant performatives (e.g., request, inform, propose), which are automatically color-coded to improve readability.

@startaml
agent Manager
agent Worker
Manager requests "task_1" from Worker
Worker informs "done" to Manager
@endaml

4.4 Advanced Modeling Mechanisms (Cervenka & Trencansky, 2007)

This implementation includes the sophisticated mechanisms introduced in the 2007 monograph:

• Deployment and Mobility: Modeling of AgentExecutionEnvironments and the movement (Move, Clone) of agents between nodes.
• Context-Based Modeling: Situation-dependent model structuring using Context packages.
• Behavior Decomposition: Refinement of agent behavior into Capabilities and reusable BehaviorFragments.

5. Implementation and Verification

5.1 Native Syntax Integration

This implementation provides first-class native syntax support by extending the PlantUML core parser. This allows for a "macro-free" modeling experience where AML concepts are expressed using domain-specific keywords. The implementation has recently undergone a major refactoring to move core logic into the io.plantaml namespace, improving modularity and preparing for advanced LSP (Language Server Protocol) integrations.

5.2 Verification and Compliance

The framework has been verified against a suite of over 50 comprehensive examples covering all aspects of the AML specification. We maintain a detailed Compliance Matrix that tracks the implementation status of every AML concept. Continuous validation is performed via PowerShell scripts (Check-AmlExamples.ps1) that run the diagrams through the PlantUML compiler to ensure syntactic correctness.

6. Adoption and Integration

The textual nature of AML for PlantUML simplifies its integration into the software development lifecycle:

• Version Control: Models are stored in Git, enabling code reviews for architectural changes.
• Automated Documentation: Diagrams are rendered during the build process and embedded into project documentation.
• IDE Support: Real-time previews and intelligent language support are available through specialized plugins for IntelliJ IDEA and VS Code.

7. Conclusion

AML for PlantUML offers a powerful, "Developer-First" approach to multi-agent system modeling. By combining the theoretical rigor of AML with the practical efficiency of PlantUML, we provide a toolchain that supports the entire MAS engineering lifecycle—from high-level architectural design to detailed behavioral specification.

References

• Cervenka, R., & Trencansky, I. (2007). The Agent Modeling Language (AML): A Comprehensive Approach to Modeling Multi-Agent Systems. Birkhäuser Basel.
• Whitestein Technologies AG. (2004). Agent Modeling Language (AML) — Language Specification, Version 0.9.
• PlantUML. (2026). Open-source tool that uses simple textual description to draw UML diagrams.