Multi-Agent Negotiation Sabha

Role-conditioned AI agents negotiate, critique, and synthesize fair group decisions — with Gemini 3 as the reasoning core.

Overview

Multi-Agent Negotiation Sabha is a system that simulates multi-stakeholder negotiations using role-conditioned AI agents. Instead of a single LLM making decisions, multiple agents represent different stakeholders, propose solutions, critique each other, and negotiate through a structured debate loop. A neutral mediator synthesizes a compromise that respects all constraints.

Key Features

• Role-Conditioned Agents: Each stakeholder is represented by an AI agent with a persona and constraints
• Structured Negotiation: 2-round debate loop with proposals, critiques, and revisions
• Mediator Synthesis: Neutral mediator creates compromise plans balancing all interests
• Constraint Validation: Deterministic validator ensures hard constraints are respected
• Traceability: Full A2A-style message trace for auditability
• Visualization: Web UI showing negotiation flow, concessions, and metrics

Architecture

User Input → Constraint Extraction → Agent Instantiation → Debate Loop → Mediator → Validator → Final Plan

Components

1. Constraint Extractor: Parses natural language into structured constraints (budget, must-haves, rejections, preferences)
2. Agent System: Creates role-conditioned agents that generate proposals and critiques
3. Debate Loop: Manages 2-round negotiation with proposals, critiques, and revisions
4. Mediator: Synthesizes compromise plans optimizing for joint satisfaction
5. Validator: Enforces hard constraints and calculates Harmony Score

Setup

Prerequisites

• Docker and Docker Compose installed
• Gemini API key (Get one here)

Quick Start

1. Clone the repository:

git clone <repository-url>
cd sabha

2. Create a .env file in the project root:

cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

3. Build and start all services:

docker compose up --build

4. Access the application:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Docs: http://localhost:8000/docs

5. To stop all services:

docker compose down

Development Mode

For development with hot reload:

docker compose -f docker-compose.dev.yml up --build

Note: The first build may take a few minutes as it installs all dependencies. Subsequent starts will be much faster.

Usage

Basic Negotiation

1. Open the web interface at http://localhost:3000
2. Enter the negotiation context (e.g., "planning a weekend trip")
3. Add stakeholders with:
   • Name
   • Description/role
   • Constraints in natural language (e.g., "Budget max ₹5000, must have AC, reject camping")
4. Click "Start Negotiation"
5. View the final plan, negotiation trace, and concession analysis

Demo Scenarios

Pre-seeded demo scenarios are available in demo/demo_scenarios.json:

• Weekend Trip - Budget vs Comfort
• Flatmate Selection
• Family Vacation Planning

You can load these scenarios programmatically or manually enter them in the UI.

API Endpoints

POST /api/negotiate

Main negotiation endpoint. Takes stakeholder inputs and returns negotiation results.

Request:

{
  "context": "planning a weekend trip",
  "stakeholders": [
    {
      "name": "Rahul",
      "description": "Budget-conscious traveler",
      "constraints": "Budget max ₹5000, prefer budget hotels"
    }
  ]
}

Response:

{
  "final_plan": {...},
  "harmony_score": 0.85,
  "is_valid": true,
  "violations": [],
  "concessions": {...},
  "agents": [...],
  "messages": [...],
  "metrics": {...}
}

POST /api/simulate

Simulation endpoint for "what-if" scenarios. Re-runs negotiation with modified constraints.

GET /api/health

Health check endpoint.

Technical Details

A2A Message Schema

Messages follow a structured format:

{
  "headers": {
    "timestamp": "2026-01-01T12:00:00",
    "message_id": "msg_abc123",
    "round_number": 1,
    "sequence": 1
  },
  "from": "agent_123",
  "to": "all",
  "type": "proposal",
  "content": {...},
  "reasoning_trace": "Agent's reasoning..."
}

Constraint Model

{
  "budget_min": float | null,
  "budget_max": float | null,
  "must_have": [str],
  "reject": [str],
  "flexibility": "rigid" | "moderate" | "flexible",
  "preferences": [str]
}

Harmony Score

Harmony Score (0-1) represents joint satisfaction using harmonic mean of individual utility scores. Higher scores indicate better compromise.

Success Metrics

• ✅ Multi-round negotiation trace visible in UI
• ✅ Mediator produces non-trivial compromise
• ✅ Latency ≤5s per round
• ✅ Validator prevents hard constraint violations
• ✅ Clear visualization of concessions and message flow

Positioning

"We don't want a single AI to tell people what to do — we want AIs that argue like people, mediate like experts, and produce verifiable compromises. That's Multi-Agent Negotiation Sabha."

License

MIT License - see LICENSE file for details