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 negmasFor 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=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:
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 ./resultsSee 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:
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
Preferences (preferences module) - UtilityFunction: Maps outcomes to utility values - Built-in types: LinearAdditiveUtilityFunction, MappingUtilityFunction, NonLinearAggregationUtilityFunction, and more - Supports probabilistic and dynamic utility functions
Negotiators (negotiators, sao modules) - Implement negotiation strategies - Built-in: AspirationNegotiator, TitForTatNegotiator, NaiveTitForTatNegotiator, BoulwareTBNegotiator, etc. - Easy to create custom negotiators
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):
Worlds (situated module) - Simulate environments where agents negotiate - Agents can run multiple concurrent negotiations - Example: Supply chain simulations (SCML)
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:
Inheritance: Subclass a base negotiator and override methods
Composition: Combine multiple negotiators using MetaNegotiator
Inheritance (Traditional Approach)
Subclass a base negotiator and implement the required methods:
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_OFFERUsing 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()Composition (Ensemble Approach)
Use SAOAggMetaNegotiator to combine multiple negotiators and aggregate their decisions:
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:
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
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 scmlCitation
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
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
tournaments.analysis module: AI assisted in implementing the post-tournament game-theoretic and statistical analysis package (EGTA-based evaluation, Sequential Elimination Ranking, replicator dynamics, and pairwise significance/normality testing)
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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file negmas-0.16.0.tar.gz.
File metadata
- Download URL: negmas-0.16.0.tar.gz
- Upload date:
- Size: 1.0 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c4bde84532fff62748f468f85704e7a2be0fd85808dccfd0b912548df0209e21
|
|
| MD5 |
79ecf47b52453f756ec7de4f885c351f
|
|
| BLAKE2b-256 |
72611c12d915e5bed01e346566cf39913c080c3bbcbd861a87f4d522b258190c
|
File details
Details for the file negmas-0.16.0-py3-none-any.whl.
File metadata
- Download URL: negmas-0.16.0-py3-none-any.whl
- Upload date:
- Size: 1.1 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
cb5c2b14156a4aabec78df68136b99833ae0eb4075ed8f7525fff2322e72e42d
|
|
| MD5 |
b11c453c3ddb494c515f0ad70551e1c3
|
|
| BLAKE2b-256 |
ab8a77c1c00af857e9bca45e3c4327499c7b6507ef7d477c1d5e9c852a8d014f
|
