https://github.com/yasserfarouk/negmas
Negotiation Multi-Agent System (A negotiation library designed for situated negotiations within business-like simulations)
https://github.com/yasserfarouk/negmas
artificial-intelligence economics-models machine-learning multi-agent negotiation
Last synced: 3 months ago
JSON representation
Negotiation Multi-Agent System (A negotiation library designed for situated negotiations within business-like simulations)
- Host: GitHub
- URL: https://github.com/yasserfarouk/negmas
- Owner: yasserfarouk
- License: other
- Created: 2019-02-01T03:40:57.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2026-01-10T10:36:58.000Z (5 months ago)
- Last Synced: 2026-01-11T00:59:17.136Z (5 months ago)
- Topics: artificial-intelligence, economics-models, machine-learning, multi-agent, negotiation
- Language: Jupyter Notebook
- Size: 103 MB
- Stars: 76
- Watchers: 5
- Forks: 23
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- Changelog: HISTORY.rst
- Contributing: CONTRIBUTING.rst
- License: LICENSE
- Authors: AUTHORS.rst
Awesome Lists containing this project
README
NegMAS: Negotiation Multi-Agent System
======================================
.. start-badges
.. image:: https://img.shields.io/pypi/pyversions/negmas.svg
:target: https://pypi.python.org/pypi/negmas
:alt: Python
.. image:: https://img.shields.io/pypi/status/negmas.svg
:target: https://pypi.python.org/pypi/negmas
:alt: Pypi
.. image:: https://img.shields.io/pypi/l/negmas.svg
:target: https://pypi.python.org/pypi/negmas
:alt: License
.. image:: https://img.shields.io/pypi/dm/negmas.svg
:target: https://pypi.python.org/pypi/negmas
:alt: Downloads
.. image:: https://img.shields.io/codacy/grade/1b204fe0a69e41a298a175ea225d7b81.svg
:target: https://app.codacy.com/project/yasserfarouk/negmas/dashboard
:alt: Code Quality
.. image:: https://img.shields.io/pypi/v/negmas.svg
:target: https://pypi.python.org/pypi/negmas
:alt: Pypi
.. image:: https://github.com/yasserfarouk/negmas/workflows/CI/badge.svg
:target: https://www.github.com/yasserfarouk/negmas
:alt: Build Status
.. image:: https://codecov.io/gh/yasserfarouk/negmas/branch/master/graph/badge.svg
:target: https://codecov.io/gh/yasserfarouk/negmas
:alt: Coverage Status
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/ambv/black
:alt: Coding style black
.. image:: https://static.pepy.tech/personalized-badge/negmas?period=total&units=international_system&left_color=black&right_color=blue&left_text=Downloads
:target: https://pepy.tech/projects/negmas
.. end-badges
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
------------
.. code-block:: bash
pip install negmas
For additional features:
.. code-block:: bash
# 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:**
.. code-block:: python
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=issues, reserved_value=0.0),
)
session.add(
TimeBasedConcedingNegotiator(name="seller"),
ufun=LUFun.random(issues=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:**
.. code-block:: python
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:
.. code-block:: bash
# 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:
.. code-block:: text
┌─────────────────────────────────────────────────────────────────┐
│ 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
---------------------------
NegMAS offers two approaches to creating custom negotiators:
1. **Inheritance**: Subclass a base negotiator and override methods
2. **Composition**: Combine multiple negotiators using ``MetaNegotiator``
Inheritance (Traditional Approach)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Subclass a base negotiator and implement the required methods:
.. code-block:: python
from negmas.sao import SAONegotiator, ResponseType
class MyNegotiator(SAONegotiator):
"""A simple negotiator using inheritance."""
def propose(self, state, dest=None):
# Propose a random outcome above reservation value
return self.nmi.random_outcome()
def respond(self, state, source=None):
offer = state.current_offer
# Accept any offer with utility > 0.8
if offer is not None and self.ufun(offer) > 0.8:
return ResponseType.ACCEPT_OFFER
return ResponseType.REJECT_OFFER
**Using the negotiator:**
.. code-block:: python
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()
Composition (Ensemble Approach)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use ``SAOAggMetaNegotiator`` to combine multiple negotiators and aggregate their decisions:
.. code-block:: python
from negmas.sao import SAOMechanism, ResponseType
from negmas.sao.negotiators import (
SAOAggMetaNegotiator,
BoulwareTBNegotiator,
NaiveTitForTatNegotiator,
)
class MajorityVoteNegotiator(SAOAggMetaNegotiator):
"""An ensemble negotiator that uses majority voting."""
def aggregate_proposals(self, state, proposals, dest=None):
# Use the proposal from the first negotiator that offers something
for neg, proposal in proposals:
if proposal is not None:
return proposal
return None
def aggregate_responses(self, state, responses, offer, source=None):
# Majority vote: accept if more than half accept
accept_count = sum(1 for _, r in responses if r == ResponseType.ACCEPT_OFFER)
if accept_count > len(responses) / 2:
return ResponseType.ACCEPT_OFFER
return ResponseType.REJECT_OFFER
# Create an ensemble of different strategies
ensemble = MajorityVoteNegotiator(
negotiators=[
BoulwareTBNegotiator(), # Tough strategy
NaiveTitForTatNegotiator(), # Reactive strategy
BoulwareTBNegotiator(), # Another tough vote
],
name="ensemble",
)
# Use in a negotiation
session = SAOMechanism(issues=issues, n_steps=100)
session.add(ensemble, ufun=my_ufun)
session.add(AspirationNegotiator(name="opponent"), ufun=opponent_ufun)
session.run()
The ensemble approach is useful for:
- **Voting strategies**: Combine multiple negotiators via majority/weighted voting
- **Dynamic delegation**: Switch between strategies at runtime
- **A/B testing**: Compare strategies within the same negotiation
Composition (BOA Components)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use ``BOANegotiator`` to build negotiators from reusable components following
the Bidding-Opponent modeling-Acceptance (BOA) pattern:
.. code-block:: python
from negmas.gb.negotiators.modular import BOANegotiator
from negmas.gb.components import (
GSmithFrequencyModel, # Opponent modeling
GACTime, # Acceptance strategy
GTimeDependentOffering, # Offering strategy
)
# Create a BOA negotiator with Genius-style components
negotiator = BOANegotiator(
offering=GTimeDependentOffering(e=0.2), # Boulware-style offering
acceptance=GACTime(t=0.95), # Accept after 95% of time
model=GSmithFrequencyModel(), # Opponent frequency model
name="my_boa_agent",
)
The BOA approach is useful for:
- **Mix-and-match**: Combine different strategies from the Genius library
- **Research**: Easily swap components to compare different strategies
- **Extensibility**: Create custom components that integrate with existing ones
Creating Custom Protocols
-------------------------
.. code-block:: python
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:
.. code-block:: python
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:
.. code-block:: bibtex
@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:
.. image:: https://raw.githubusercontent.com/yasserfarouk/negmas/main/docs/figs/ecosystem.png
:alt: NegMAS Ecosystem
:align: center
:width: 100%
**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 `_):
**Core NegMAS Research** (by the NegMAS authors)
- Mohammad, Y. (2025). `Tackling the Protocol Problem in Automated Negotiation `_. AAMAS. *Cited by 1*
- Florijn et al. (2025). `A Survey on One-to-Many Negotiation `_. IJCAI. *Cited by 1*
- Mohammad, Y. et al. (2024). `Automated Negotiation in Supply Chains: A Generalist Environment for RL/MARL `_. PRIMA. *Cited by 1*
- Mohammad, Y. (2023). `Generalized Bargaining Protocols `_. AI 2023. *Cited by 3*
- Mohammad, Y. (2023). `Optimal Time-based Strategy for Automated Negotiation `_. Applied Intelligence. *Cited by 9*
- Mohammad, Y. (2023). `Evaluating Automated Negotiations `_. IEEE WI-IAT. *Cited by 2*
- Mohammad, Y. (2021). `Concurrent Local Negotiations with a Global Utility Function `_. AAMAS Journal. *Cited by 14*
- Mohammad, Y. (2020). `Optimal Deterministic Time-based Policy in Automated Negotiation `_. PRIMA. *Cited by 4*
- Mohammad, Y., Nakadai, S. (2019). `Optimal Value of Information Based Elicitation `_. AAMAS.
- Mohammad, Y., Nakadai, S. (2018). `FastVOI: Efficient Utility Elicitation `_. PRIMA.
- Mohammad, Y. et al. (2019). `Supply Chain Management World `_. PRIMA. *Cited by 38*
**Competition & Benchmarks**
- Aydoğan et al. (2025). `ANAC 2024 Challenges and Results `_. AAMAS. *Cited by 2*
- Aydoğan et al. (2020). `Challenges and Main Results of ANAC 2019 `_. EUMAS/AT. *Cited by 51*
**Negotiation Strategies**
- Sengupta et al. (2021). `RL-Based Negotiating Agent Framework `_. IJCAI *Cited by 48*
- Higa et al. (2023). `Reward-based Negotiating Agent Strategies `_. AAAI. *Cited by 16*
**Applications**
- Inotsume et al. (2020). `Path Negotiation for Multirobot Vehicles `_. IROS. *Cited by 17*
*Last updated: February 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 `_.