NegMAS: Negotiation Multi-Agent System

NegMAS is a Python library for developing autonomous negotiation agents embedded in simulation environments. It supports bilateral and multilateral negotiations, multiple negotiation protocols, and complex multi-agent simulations with interconnected negotiations.

Documentation: https://negmas.readthedocs.io/

Installation

pip install negmas

For additional features:

# With Genius bridge support (Java-based agents)
pip install negmas[genius]

# With visualization support
pip install negmas[plots]

# All optional dependencies
pip install negmas[all]

Quick Start

Run a simple negotiation in 10 lines:

from negmas import SAOMechanism, TimeBasedConcedingNegotiator, make_issue
from negmas.preferences import LinearAdditiveUtilityFunction as LUFun

# Define what we're negotiating about
issues = [make_issue(name="price", values=100)]

# Create negotiation session (Stacked Alternating Offers)
session = SAOMechanism(issues=issues, n_steps=50)

# Add buyer (prefers low price) and seller (prefers high price)
session.add(
    TimeBasedConcedingNegotiator(name="buyer"),
    ufun=LUFun.random(issues, reserved_value=0.0),
)
session.add(
    TimeBasedConcedingNegotiator(name="seller"),
    ufun=LUFun.random(issues, reserved_value=0.0),
)

# Run and get result
result = session.run()
print(f"Agreement: {result.agreement}, Rounds: {result.step}")

Multi-issue negotiation with custom preferences:

from negmas import SAOMechanism, AspirationNegotiator, make_issue
from negmas.preferences import LinearAdditiveUtilityFunction

# Create a 2-issue negotiation domain
issues = [
    make_issue(name="price", values=10),
    make_issue(name="quantity", values=5),
]

# Define utility functions
buyer_ufun = LinearAdditiveUtilityFunction(
    values={
        "price": lambda x: 1.0 - x / 10.0,  # lower price = better
        "quantity": lambda x: x / 5.0,  # more quantity = better
    },
    issues=issues,
)
seller_ufun = LinearAdditiveUtilityFunction(
    values={
        "price": lambda x: x / 10.0,  # higher price = better
        "quantity": lambda x: 1.0 - x / 5.0,  # less quantity = better
    },
    issues=issues,
)

# Run negotiation
session = SAOMechanism(issues=issues, n_steps=100)
session.add(AspirationNegotiator(name="buyer"), ufun=buyer_ufun)
session.add(AspirationNegotiator(name="seller"), ufun=seller_ufun)
session.run()

# Visualize
session.plot()

Command Line Interface

NegMAS includes a negotiate CLI for quick experimentation:

# Run with default negotiators
negotiate -s 50

# Specify negotiators and steps
negotiate -n AspirationNegotiator -n NaiveTitForTatNegotiator -s 100

# Use Python-native Genius agents (no Java required)
negotiate -n GBoulware -n GConceder -s 50

# Use custom BOA components
negotiate -n "boa:offering=GTimeDependentOffering(e=0.2),acceptance=GACNext" -n AspirationNegotiator

# Save results and plot
negotiate -s 100 --save-path ./results

See negotiate --help for all options, or the CLI documentation.

Architecture Overview

NegMAS is built around four core concepts:

┌─────────────────────────────────────────────────────────────────┐
│                           WORLD                                 │
│  (Simulation environment where agents interact)                 │
│                                                                 │
│   ┌─────────┐     ┌─────────┐         ┌─────────────────────┐  │
│   │  Agent  │     │  Agent  │   ...   │  BulletinBoard      │  │
│   │         │     │         │         │  (Public info)      │  │
│   └────┬────┘     └────┬────┘         └─────────────────────┘  │
│        │               │                                        │
│        │ creates       │ creates                                │
│        ▼               ▼                                        │
│   ┌─────────────────────────────────────────────────────────┐  │
│   │                    MECHANISM                             │  │
│   │  (Negotiation protocol: SAO, SingleText, Auction, etc.) │  │
│   │                                                          │  │
│   │   ┌────────────┐  ┌────────────┐  ┌────────────┐        │  │
│   │   │ Negotiator │  │ Negotiator │  │ Negotiator │        │  │
│   │   │  + UFun    │  │  + UFun    │  │  + UFun    │        │  │
│   │   └────────────┘  └────────────┘  └────────────┘        │  │
│   └─────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Core Components:

1. Outcome Space (outcomes module) - Issues: Variables being negotiated (price, quantity, delivery date, etc.) - Outcomes: Specific assignments of values to issues - Supports discrete, continuous, and categorical issues
2. Preferences (preferences module) - UtilityFunction: Maps outcomes to utility values - Built-in types: LinearAdditiveUtilityFunction, MappingUtilityFunction, NonLinearAggregationUtilityFunction, and more - Supports probabilistic and dynamic utility functions
3. Negotiators (negotiators, sao modules) - Implement negotiation strategies - Built-in: AspirationNegotiator, TitForTatNegotiator, NaiveTitForTatNegotiator, BoulwareTBNegotiator, etc. - Easy to create custom negotiators
4. Mechanisms (mechanisms, sao modules) - Implement negotiation protocols - SAOMechanism: Stacked Alternating Offers (most common) - Also: Single-text protocols, auction mechanisms, etc.

For Situated Negotiations (World Simulations):

5. Worlds (situated module) - Simulate environments where agents negotiate - Agents can run multiple concurrent negotiations - Example: Supply chain simulations (SCML)
6. Controllers (sao.controllers module) - Coordinate multiple negotiators - Useful when negotiations are interdependent

Key Features

• Multiple Protocols: SAO (Alternating Offers), Single-Text, Auctions, and custom protocols
• Rich Utility Functions: Linear, nonlinear, constraint-based, probabilistic, dynamic
• Bilateral & Multilateral: Support for 2+ party negotiations
• Concurrent Negotiations: Agents can participate in multiple negotiations simultaneously
• World Simulations: Build complex multi-agent simulations with situated negotiations
• Genius Integration: Run Java-based Genius agents via the built-in bridge
• Visualization: Built-in plotting for negotiation analysis
• Extensible: Easy to add new protocols, negotiators, and utility functions

Creating Custom Negotiators

Minimal SAO negotiator:

from negmas.sao import SAONegotiator, SAOResponse, ResponseType


class MyNegotiator(SAONegotiator):
    def __call__(self, state, offer=None):
        # Accept any offer with utility > 0.8
        if offer is not None and self.ufun(offer) > 0.8:
            return SAOResponse(ResponseType.ACCEPT_OFFER, offer)
        # Otherwise, propose a random outcome
        return SAOResponse(ResponseType.REJECT_OFFER, self.nmi.random_outcome())

Using the negotiator:

session = SAOMechanism(issues=issues, n_steps=100)
session.add(MyNegotiator(name="custom"), ufun=my_ufun)
session.add(AspirationNegotiator(name="opponent"), ufun=opponent_ufun)
session.run()

Creating Custom Protocols

from negmas import Mechanism, MechanismStepResult


class MyProtocol(Mechanism):
    def __call__(self, state, action=None):
        # Implement one round of your protocol
        # Return MechanismStepResult with updated state
        ...
        return MechanismStepResult(state=state)

Running World Simulations

For complex scenarios with multiple agents and concurrent negotiations:

from negmas.situated import World, Agent


class MyAgent(Agent):
    def step(self):
        # Called each simulation step
        # Request negotiations, respond to events, etc.
        pass


# See SCML package for a complete example
# pip install scml

Citation

If you use NegMAS in your research, please cite:

@inproceedings{mohammad2021negmas,
  title={NegMAS: A Platform for Automated Negotiations},
  author={Mohammad, Yasser and Nakadai, Shinji and Greenwald, Amy},
  booktitle={PRIMA 2020: Principles and Practice of Multi-Agent Systems},
  pages={343--351},
  year={2021},
  publisher={Springer},
  doi={10.1007/978-3-030-69322-0_23}
}

Reference:

Mohammad, Y., Nakadai, S., Greenwald, A. (2021). NegMAS: A Platform for Automated Negotiations. In: PRIMA 2020. LNCS, vol 12568. Springer. https://doi.org/10.1007/978-3-030-69322-0_23

The NegMAS Ecosystem

NegMAS is the core of a broader ecosystem for automated negotiation research:

Competition Frameworks

• anl - Automated Negotiation League (ANAC negotiation track)
• scml - Supply Chain Management League

Agent Repositories

• anl-agents - ANL competition agents
• scml-agents - SCML competition agents

Bridges & Extensions

• negmas-geniusweb-bridge - Run GeniusWeb agents
• negmas-llm - LLM-powered negotiation agents
• negmas-elicit - Preference elicitation during negotiation
• geniusbridge - Java Genius bridge

Visualization & Tools

• negmas-app - Applications and interfaces for NegMAS
• scml-vis - SCML visualization
• jnegmas - Java interface (not maintained)

Specialized Tools

• negmas-elicit - Preference Elicitation during Negotiation Methods

More Resources

• Tutorials: https://negmas.readthedocs.io/en/latest/tutorials.html
• API Reference: https://negmas.readthedocs.io/en/latest/api.html
• YouTube Playlist: https://www.youtube.com/playlist?list=PLqvs51K2Mb8IJe5Yz5jmYrRAwvIpGU2nF
• Publications: https://negmas.readthedocs.io/en/latest/publications.html

Papers Using NegMAS

Selected papers (see full list):

Competition & Benchmarks

• Aydoğan et al. (2020). Challenges and Main Results of ANAC 2019. EUMAS/AT. Cited by 51
• Mohammad et al. (2019). Supply Chain Management World. PRIMA. Cited by 38

Negotiation Strategies

• Sengupta et al. (2021). RL-Based Negotiating Agent Framework. arXiv. Cited by 48
• Higa et al. (2023). Reward-based Negotiating Agent Strategies. AAAI. Cited by 16

Preference Elicitation

• Mohammad, Y., Nakadai, S. (2019). Optimal Value of Information Based Elicitation. AAMAS.
• Mohammad, Y., Nakadai, S. (2018). FastVOI: Efficient Utility Elicitation. PRIMA.

Applications

• Inotsume et al. (2020). Path Negotiation for Multirobot Vehicles. IROS. Cited by 17

Last updated: January 2026

Contributing

Contributions are welcome! Please see the contributing guide.

License

NegMAS is released under the BSD 3-Clause License.

AI Assistance Disclosure

This project uses AI assistance for specific, limited tasks while remaining predominantly human-developed:

• Publications list: AI assisted in compiling and formatting the publications list
• Documentation polishing: AI assisted in proofreading and improving documentation clarity
• gb.components.genius module: AI assisted in reimplementing Genius BOA components in NegMAS
• Registry feature: AI assisted in developing the negotiator/mechanism registry system
• Some tests: AI assisted in writing tests, particularly for new features like the registry

All AI-assisted contributions are reviewed and approved by human maintainers. The core architecture, algorithms, and research direction of NegMAS are human-driven and will remain so.

Acknowledgements

NegMAS was developed at the NEC-AIST collaborative laboratory. It uses scenarios from ANAC 2010-2018 competitions obtained from the Genius Platform.