Opponents¶
Two kinds of agents
HANI2 has two kinds of agents. The opponent agent negotiates against the participant; it is
chosen with --opponents, HANI2_OPPONENTS, ?opponents= and opponents in env.json. The
support agent helps the participant; it is chosen with --support-agent (see
Support agent). Participants see the opponent agent as their partner.
The older names --agents, HANI2_AGENTS, ?agents= and agents still work.
Every negotiation pairs the participant with one automated opponent (the partner). HANI2 picks it from a pool of agent specs when the negotiation starts. This page explains how specs are written, how the pool is chosen and what HANI2 does to the opponent before it plays.
Agent specs¶
An agent spec is a string that names a negotiator class. HANI2 resolves it as follows.
| Spec | Resolves to | Example |
|---|---|---|
| A bare name (no dot) | A class in negmas.sao |
BoulwareTBNegotiator, AspirationNegotiator |
LLM... |
An LLM negotiator from negmas-llm | LLMHybridNegotiator |
...WithTextNegotiator |
A template-based talking negotiator from negmas-llm | HybridWithTextNegotiator |
helpers.<Class> |
A classic negotiator bundled with HANI2 (hani2.helpers.negotiators) |
helpers.AgentK |
genius.<Class> |
A Genius agent wrapper (negmas.genius.gnegotiators) |
genius.Atlas3 |
file:<path>.<Class> |
A class loaded from a Python file | file:agents/mine.MyNegotiator |
| A dotted path | Any importable class | my_package.agents.MyNegotiator |
Notes on the less obvious forms:
file:paths are relative to the server's working directory unless they are absolute (file:/home/me/neg.MyNegotiator). Leave out the.pyextension; the part after the last dot is the class name. Both/and\work as separators.- A dotted path must be importable by the server process. Put your package on
PYTHONPATHor install it into the same environment. genius.*agents need a running Genius bridge, as described in the negmas documentation.
The negmas-llm negotiators that HANI2 knows by name are:
- LLM negotiators:
LLMHybridNegotiator,LLMBoulwareTBNegotiator,LLMConcederTBNegotiator,LLMLinearTBNegotiator. - Template-based talking negotiators:
HybridWithTextNegotiator,BoulwareWithTextNegotiator,ConcederWithTextNegotiator,LinearWithTextNegotiator.
Group tokens¶
A spec that starts with : expands to a list of specs. Tokens are case-insensitive.
| Token | Expands to |
|---|---|
:llm |
The four LLM* negotiators above. They call a language model on every turn. |
:template |
The four *WithTextNegotiator negotiators. They send messages from templates, without a language model. |
:notext |
BoulwareTBNegotiator, ConcederTBNegotiator, LinearTBNegotiator, HybridNegotiator (offers only, no messages). |
:negmas |
Every SAO negotiator type that negmas registers. |
:classic |
The classic negotiators in hani2.helpers.negotiators: helpers.AverageTitForTat, helpers.HardHeaded, helpers.AgentK, helpers.Atlas3, helpers.CUHKAgent, helpers.AgentGG. |
:genius |
Every agent in negmas.genius.gnegotiators, as genius.<Class>. |
:custom |
The comma-separated specs in the HANI2_CUSTOM_AGENTS environment variable (these may contain group tokens too). |
:pan |
The classes in an external pan.py module (see below). Empty when no such module is found. |
Unknown tokens print a warning in the server log and expand to nothing. Lists are de-duplicated and keep their order, so :notext,BoulwareTBNegotiator has BoulwareTBNegotiator only once.
The :pan group¶
:pan is for deployments that keep a pool of personality-adjusted negotiators in a separate file called pan.py. HANI2 looks for that file in these directories, in order, and adds the first one that has it to sys.path:
- The directory in
HANI2_CODE_BASE. $SCMLWEB_CODE_BASE/python(default~/scmlweb/python).- The server's working directory.
python/under the working directory.
The module must define the lists HSHP, HSLP, LSHP and LSLP of negotiator classes. Each class becomes the spec pan.<ClassName>. If pan.py cannot be imported, the server prints a warning and the group is empty, so anything that falls back on an empty pool keeps working. The Prolific practice round uses :pan by default.
Group files¶
A bare spec (no : and no dot) can also name a group file. If <results>/groups/<key>.json exists, the spec <key> expands to the agents in it. <results> is ~/negmas/hani2/db by default, or <experiment>/results when an experiment is active (see Studies and results).
A group file has one of two shapes:
In the object form, every directory in syspath is appended to sys.path before the agents are imported, so you can drop unpacked agent packages anywhere on disk. HANI2 adds the syspath entries of all group files at server start-up, so an agent from a group file imports even in a session that never named the group. Group files may contain group tokens and other group keys. HANI2 only reads these files; other tools can write them.
A group file takes priority over a negmas class with the same bare name.
Choosing the pool¶
When a negotiation starts, HANI2 builds the pool from the first source in this list that yields at least one agent:
- The query string of the page:
?opponents=<specs>(comma-separated specs and tokens), else?group=<key>.?group=accepts a group-file key or a built-in token with or without the colon (?group=template,?group=:template). - The
--opponentsoption ofhani2(stored in theHANI2_OPPONENTSenvironment variable). - The per-session Partner types setting in the admin settings drawer.
- The
opponentslist inenv.json, also editable as Opponent agents in the admin console. - The default pool: the four template-based talking negotiators (
:template).
The default needs no language model, so a casual visitor never causes LLM costs.
# Everyone negotiates against conceder and boulware agents
hani2 --opponents BoulwareTBNegotiator,ConcederTBNegotiator
# Mix groups and single agents
hani2 --opponents ":notext,helpers.AgentK"
The partner is then chosen at random from the pool, with two exceptions:
- A study can fix the partner per round. The Prolific study does this for practice and counted rounds.
- In admin mode, the Opponent for the next negotiation field on the start screen overrides the random choice (see below).
The admin opponent picker¶
When a session is in admin mode, the start screen shows a field labelled Opponent for the next negotiation. It suggests every agent in the groups offered to admins (llm, template, notext, negmas, classic, genius), but you can type any spec. Leave it empty to draw from the pool. The choice stays in place for later negotiations in the same session until you clear it.
Admin sessions also show the partner's name in the interface. For other participants, the partner's type stays hidden unless the admin turns on Show the partner's type in the settings drawer. See Admin console and Authentication for how a session enters admin mode.
What HANI2 does to an opponent¶
hani2.agents.make_agent() builds the opponent. Besides instantiating the class, it does three things.
LLM model injection¶
Opponents that call a language model use the model configured in llm_settings.json (see Language models):
- For a spec that starts with
LLM, HANI2 passes bothmodelandprovider. - For any other subclass of negmas-llm's
LLMNegotiator, it passesmodel. - For subclasses of negmas-llm's
LLMMetaNegotiator(a numeric strategy wrapped by an LLM message layer), it passesmodelandprovider, but only when the constructor declares those parameters by name.
Without this step, LLM negotiators would fall back to negmas-llm's built-in default model.
Robustness wrappers¶
Two wrappers change the opponent's class at runtime:
- No accept without an offer. If the opponent tries to accept while no offer is on the table (for example on its first move, or after the participant sent a message without an offer), the accept becomes a plain "no counter-offer" response that keeps any message. The negotiation continues instead of breaking. Every opponent gets this wrapper.
- No ending in practice rounds. In a practice round, an attempt by the opponent to end the negotiation becomes a "no counter-offer" response, so a participant who is still learning the interface never sees the partner walk away. Real rounds keep the unwrapped behaviour.
The wrapped class names start with NoAcceptNone_ and NoEnd_. The agent_type column in results.csv keeps the spec you configured, not the wrapper name.
Verbose mode¶
hani2 --verbose sets HANI2_VERBOSE=1. HANI2 then tries to construct opponents with verbose=True, and falls back to the normal constructor if the class does not accept that argument.
Writing your own opponent¶
Any negmas SAONegotiator works. Save it in a file and use a file: spec, or put it in an importable package and use a dotted path:
from negmas.sao import AspirationNegotiator
class Stubborn(AspirationNegotiator):
"""Concedes very late."""
def __init__(self, *args, **kwargs):
kwargs.setdefault("aspiration_type", 10.0) # a high exponent concedes late
super().__init__(*args, **kwargs)
Opponents that send messages put the text in the data of their response under the text key, as the negmas-llm negotiators do. HANI2 shows that text in the negotiation history.