Ontology-based Agentic Negotiation Protocol
Principled multi-party negotiation, formalized as an open protocol.
Live negotiation: agents discover interests, generate options, and converge on a settlement in real time
OANP is an open protocol and simulation framework for multi-party negotiation using autonomous agents. Agents negotiate using Harvard Negotiation Project principles, focusing on interests rather than positions, formalized through domain ontologies.
Define parties, interests, BATNAs, and issues in a YAML file. OANP runs a principled negotiation with autonomous agents, streams moves in real time, and delivers a settlement or analysis of why agreement was not reached.
|
Typed protocol with 10 move types, 9 negotiation phases, configurable mediator architectures (facilitative / evaluative / arbitrative), and full metrics: Pareto efficiency, Nash product, integrative index, BATNA surplus. |
12 built-in scenarios from salary negotiation to the Iran nuclear deal. Define any domain in YAML. Plug in OpenAI, Anthropic, or any compatible endpoint. MIT licensed. |
Important
We're looking for real-world use cases. If you work in arbitration, commercial law, insurance, procurement, licensing, family law, or any domain involving structured negotiation, we want to hear from you. What disputes would you test this on? What would make it useful for your practice?
Reach out at cem@talp.ai with your scenario, industry, or research question.
- Interest-first — agents reason about why parties want things, not just what they demand
- BATNA-safe — no party accepts a deal worse than their best alternative
- Integrative — the protocol incentivizes expanding the pie, not splitting it
- Observable — every move is typed, timestamped, traceable
- Ontology-grounded — shared semantic representation, not prompt engineering
Note
OANP's approach is validated by the MIT AI Negotiation Competition (2025, ~180,000 negotiations) which found that agents adhering to Harvard principles consistently outperform positional bargaining agents.
# 1. Clone and configure
git clone https://github.com/cemphlvn/OANP.git && cd OANP
cp .env.example .env # add your OpenAI or Anthropic API key
# 2. Install
npm run setup:all # installs Node + Python deps
# 3. Run a negotiation
python simulate.py scenarios/salary-negotiation.yamlMore options
# Use a specific model
python simulate.py scenarios/salary-negotiation.yaml --model claude-sonnet-4-6
# JSON output for analysis
python simulate.py scenarios/salary-negotiation.yaml --output json --out-file results/run.json
# Generate a scenario from natural language
python simulate.py --generate "Two co-founders splitting equity after one wants to leave"
# Interactive scenario builder
python simulate.py --create
# Start the web UI (frontend + backend)
npm run dev| Service | URL |
|---|---|
| Frontend | http://localhost:3000 |
| Backend API | http://localhost:8123 |
| API Docs | http://localhost:8123/docs |
OANP ships with 12 scenarios spanning employment, commercial, legal, and geopolitical domains:
| Scenario | Domain | Parties |
|---|---|---|
| Salary Negotiation | Employment | Candidate vs Employer |
| Landlord-Tenant | Dispute Resolution | Tenant vs Landlord |
| B2B SaaS Contract | Commercial | Buyer vs Vendor |
| Custody Dispute | Family Law | Mother vs Father |
| Union Strike | Labor | Union vs Hospital |
| Pharma Patent | Healthcare | Biotech vs Patient Advocacy |
| Startup Acquisition | M&A | Founder vs BigTech |
| AI Safety: Ship or Stop | Governance | Safety Lead vs Product Lead |
| US-China Trade | Geopolitics | US Trade Rep vs China Commerce |
| 1998 NBA Lockout | Sports Labor | NBA Owners vs Players |
| Apple vs Samsung | IP Litigation | Apple CEO vs Samsung CEO |
| Iran Nuclear Deal | Diplomacy | US (P5+1) vs Iran |
# Create your own
cp scenarios/salary-negotiation.yaml scenarios/my-scenario.yamlEvery negotiation action is a discrete, auditable event with full reasoning.
|
|
| Samsung counter-offers with $799M settlement | Apple rejects, then accepts after mediator intervention |
1998 NBA Lockout scenario: agents reach agreement on salary cap, revenue split, and minimum player salary
US-China trade negotiation: social welfare, Nash product, integrative index, Pareto efficiency, move breakdown, and critique
Live: US Trade Representative vs China Commerce Ministry negotiating AI chip export controls
flowchart TD
A["Scenario (YAML)"] --> B["Discovery"]
B --> C["Generation"]
C --> D["Bargaining"]
D --> E["Convergence"]
E --> F{"Outcome"}
F -->|Agreement| G["Settlement"]
F -->|No Agreement| H["Impasse"]
subgraph Engine["Negotiation Engine"]
direction LR
N1["Negotiator A\n(private state)"]
M["Mediator\n(configurable)"]
N2["Negotiator B\n(private state)"]
N1 <--> M <--> N2
end
A ~~~ Engine
G --> U["Utility · Pareto · Nash · Integrative Index"]
style A fill:#f5f5f5,stroke:#333,color:#000
style G fill:#d4edda,stroke:#28a745,color:#000
style H fill:#f8d7da,stroke:#dc3545,color:#000
style M fill:#fff3cd,stroke:#ffc107,color:#000
style Engine fill:#f8f9fa,stroke:#dee2e6,color:#000
Architecture details
Protocol types (src/protocol/types.py) define the formal type system: NegotiationState, Move, Interest, BATNA, OptionPackage, ObjectiveCriterion. This is the single source of truth.
Agents (src/agents/) are LLM-powered:
negotiator.py— party agent with Harvard principles encoded in the system prompt, theory-of-mind before each movemediator.py— configurable neutral facilitator (facilitative / evaluative / arbitrative)scorer.py— LLM utility scorer with satisfaction anchors and pairwise BATNA comparisonanalyst.py— post-hoc metrics (social welfare, Pareto efficiency, Nash product, integrative index)bci.py— Bayesian opponent model (Chang & Fujita 2026) — estimates opponent utility from observed bids using parametric interrelationvalidator.py— structural safety layer preventing illegal moves and BATNA violations
Information boundaries (src/protocol/views.py) enforce what each actor can see. This is structural, not a prompt instruction.
Engine (src/agents/graph.py) orchestrates negotiation as a LangGraph state machine with Command-based routing.
OANP/
├── simulate.py # CLI runner
├── scenarios/ # YAML negotiation scenarios
├── paper/ # Research paper
├── tests/ # Test suite
└── src/
├── protocol/ # Core types, scenario loader, state views
├── agents/ # Negotiator, mediator, scorer, analyst, engine
├── ontology/ # Graphiti knowledge graph (optional)
└── backend/ # FastAPI + WebSocket server
| Layer | Technology |
|---|---|
| Backend | FastAPI, WebSocket |
| Agents | LangGraph, LangChain |
| Memory | Graphiti + Neo4j (planned) |
| LLMs | OpenAI, Anthropic, or any OpenAI-compatible endpoint |
| Frontend | Vue 3, Vite, D3.js |
Tip
All code dependencies are MIT or Apache 2.0. You need an LLM API key to run negotiations.
OANP is grounded in research across automated negotiation, legal informatics, and multi-agent systems. See the paper for full positioning and references.
Key influences:
- Fisher & Ury, Getting to Yes (1981) — principled negotiation
- Rahwan et al. (2003) — interest-based negotiation in multi-agent systems
- MIT AI Negotiation Competition (2025) — empirical validation at 180K negotiations
- Singapore Convention on Mediation (2019) — cross-border enforceability
- Protocol v0.1 with typed moves and 9 negotiation phases
- LLM utility scorer with satisfaction anchors
- 12 scenarios from employment to diplomacy
- Configurable mediator (facilitative / evaluative / arbitrative)
- Bayesian opponent modeling (BCI) with real-time belief streaming
- Simulation benchmarks across mediator configs, models, and domains
- Knowledge graph memory (Graphiti/Neo4j wire-in for cross-session learning)
- N-party negotiation with coalition formation
- Human-in-the-loop (negotiate alongside agents in the web UI)
See CONTRIBUTING.md. Key areas: new scenarios, agent strategies, ontology templates, frontend.
MIT — see LICENSE.