Agent

class negmas.situated.Agent(name: Optional[str] = None, type_postfix: str = '', ufun: Optional[negmas.utilities.UtilityFunction] = None)[source]

Bases: negmas.situated.Entity, negmas.events.EventSink, negmas.helpers.ConfigReader, negmas.events.Notifier, negmas.common.Rational, abc.ABC

Base class for all agents that can run within a World and engage in situated negotiations

Attributes Summary

accepted_negotiation_requests

A list of negotiation requests sent to this agent that are already accepted by it.

awi

Gets the Agent-world interface.

initialized

Was the agent initialized (i.e.

negotiation_requests

A list of the negotiation requests sent by this agent that are not yet accepted or rejected.

requested_negotiations

The negotiations currently requested by the agent.

running_negotiations

The negotiations currently requested by the agent.

unsigned_contracts

All contracts that are not yet signed.

Methods Summary

create_negotiation_request(issues, partners, …)

Creates a new NegotiationRequestInfo record and returns its ID

init()

Called to initialize the agent after the world is initialized.

on_contract_breached(contract, breaches, …)

Called after complete processing of a contract that involved a breach.

on_contract_cancelled(contract, rejectors)

Called whenever at least a partner did not sign the contract

on_contract_cancelled_(contract, rejectors)

Called whenever at least a partner did not sign the contract

on_contract_executed(contract)

Called after successful contract execution for which the agent is one of the partners.

on_contract_signed(contract)

Called whenever a contract is signed by all partners

on_contract_signed_(contract)

Called whenever a contract is signed by all partners

on_contracts_finalized(signed, cancelled, …)

Called for all contracts in a single step to inform the agent about which were finally signed and which were rejected by any agents (including itself)

on_event(event, sender)

on_neg_request_accepted(req_id, mechanism)

Called when a requested negotiation is accepted

on_neg_request_accepted_(req_id, mechanism)

Called when a requested negotiation is accepted

on_neg_request_rejected(req_id, by)

Called when a requested negotiation is rejected

on_neg_request_rejected_(req_id, by)

Called when a requested negotiation is rejected

on_negotiation_failure(partners, annotation, …)

Called whenever a negotiation ends without agreement

on_negotiation_failure_(partners, …)

Called whenever a negotiation ends without agreement

on_negotiation_success(contract, mechanism)

Called whenever a negotiation ends with agreement

on_negotiation_success_(contract, mechanism)

Called whenever a negotiation ends with agreement

on_simulation_step_ended()

Will be called at the end of the simulation step after everything else

on_simulation_step_started()

Will be called at the beginning of the simulation step before everything else (except init)

respond_to_negotiation_request_(initiator, …)

Called when a negotiation request is received

respond_to_renegotiation_request(contract, …)

Called to respond to a renegotiation request

set_renegotiation_agenda(contract, breaches)

Received by partners in ascending order of their total breach levels in order to set the renegotiation agenda when contract execution fails

sign_all_contracts(contracts)

Called to sign all contracts concluded in a single step by this agent

sign_contract(contract)

Called after the signing delay from contract conclusion to sign the contract.

step()

Called by the simulator at every simulation step

Attributes Documentation

accepted_negotiation_requests

A list of negotiation requests sent to this agent that are already accepted by it.

Remarks:
  • These negotiations did not start yet as they are still not accepted by all partners. Once that happens, they will be moved to running_negotiations

awi

Gets the Agent-world interface.

initialized

Was the agent initialized (i.e. was init_() called)

negotiation_requests

A list of the negotiation requests sent by this agent that are not yet accepted or rejected.

Remarks:
  • These negotiations did not start yet as they are still not accepted by all partners. Once that happens, they will be moved to running_negotiations

requested_negotiations

The negotiations currently requested by the agent.

Returns

A list of negotiation request information objects (NegotiationRequestInfo)

running_negotiations

The negotiations currently requested by the agent.

Returns

A list of negotiation information objects (RunningNegotiationInfo)

unsigned_contracts

All contracts that are not yet signed.

Methods Documentation

create_negotiation_request(issues: List[negmas.outcomes.Issue], partners: List[str], annotation: Optional[Dict[str, Any]], negotiator: Optional[negmas.negotiators.Negotiator], extra: Optional[Dict[str, Any]])str[source]

Creates a new NegotiationRequestInfo record and returns its ID

Parameters
  • issues – negotiation issues

  • partners – partners

  • annotation – annotation

  • negotiator – the negotiator to use

  • extra – any extra information

Returns

A unique identifier for this negotiation info structure

abstract init()[source]

Called to initialize the agent after the world is initialized. the AWI is accessible at this point.

abstract on_contract_breached(contract: negmas.situated.Contract, breaches: List[negmas.situated.Breach], resolution: Optional[negmas.situated.Contract])None[source]

Called after complete processing of a contract that involved a breach.

Parameters
  • contract – The contract

  • breaches – All breaches committed (even if they were resolved)

  • resolution – The resolution contract if re-negotiation was successful. None if not.

on_contract_cancelled(contract: negmas.situated.Contract, rejectors: List[str])None[source]

Called whenever at least a partner did not sign the contract

on_contract_cancelled_(contract: negmas.situated.Contract, rejectors: List[str])None[source]

Called whenever at least a partner did not sign the contract

abstract on_contract_executed(contract: negmas.situated.Contract)None[source]

Called after successful contract execution for which the agent is one of the partners.

on_contract_signed(contract: negmas.situated.Contract)None[source]

Called whenever a contract is signed by all partners

on_contract_signed_(contract: negmas.situated.Contract)None[source]

Called whenever a contract is signed by all partners

on_contracts_finalized(signed: List[negmas.situated.Contract], cancelled: List[negmas.situated.Contract], rejectors: List[List[str]])None[source]

Called for all contracts in a single step to inform the agent about which were finally signed and which were rejected by any agents (including itself)

Parameters
  • signed – A list of signed contracts. These are binding

  • cancelled – A list of cancelled contracts. These are not binding

  • rejectors – A list of lists where each of the internal lists gives the rejectors of one of the cancelled contracts. Notice that it is possible that this list is empty which means that the contract other than being rejected by any agents (if that was possible in the specific world).

Remarks:

The default implementation is to call on_contract_signed for singed contracts and on_contract_cancelled for cancelled contracts

on_event(event: negmas.events.Event, sender: negmas.events.EventSource)[source]
abstract on_neg_request_accepted(req_id: str, mechanism: negmas.common.AgentMechanismInterface)[source]

Called when a requested negotiation is accepted

on_neg_request_accepted_(req_id: str, mechanism: negmas.common.AgentMechanismInterface)[source]

Called when a requested negotiation is accepted

abstract on_neg_request_rejected(req_id: str, by: Optional[List[str]])[source]

Called when a requested negotiation is rejected

Parameters
  • req_id – The request ID passed to _request_negotiation

  • by – A list of agents that refused to participate or None if the failure was for another reason

on_neg_request_rejected_(req_id: str, by: Optional[List[str]])[source]

Called when a requested negotiation is rejected

Parameters
  • req_id – The request ID passed to _request_negotiation

  • by – A list of agents that refused to participate or None if the failure was for another reason

abstract on_negotiation_failure(partners: List[str], annotation: Dict[str, Any], mechanism: negmas.common.AgentMechanismInterface, state: negmas.common.MechanismState)None[source]

Called whenever a negotiation ends without agreement

on_negotiation_failure_(partners: List[str], annotation: Dict[str, Any], mechanism: negmas.common.AgentMechanismInterface, state: negmas.common.MechanismState)None[source]

Called whenever a negotiation ends without agreement

abstract on_negotiation_success(contract: negmas.situated.Contract, mechanism: negmas.common.AgentMechanismInterface)None[source]

Called whenever a negotiation ends with agreement

on_negotiation_success_(contract: negmas.situated.Contract, mechanism: negmas.common.AgentMechanismInterface)None[source]

Called whenever a negotiation ends with agreement

on_simulation_step_ended()[source]

Will be called at the end of the simulation step after everything else

on_simulation_step_started()[source]

Will be called at the beginning of the simulation step before everything else (except init)

respond_to_negotiation_request_(initiator: str, partners: List[str], issues: List[negmas.outcomes.Issue], annotation: Dict[str, Any], mechanism: negmas.common.AgentMechanismInterface, role: Optional[str], req_id: Optional[str])Optional[negmas.negotiators.Negotiator][source]

Called when a negotiation request is received

abstract respond_to_renegotiation_request(contract: negmas.situated.Contract, breaches: List[negmas.situated.Breach], agenda: negmas.situated.RenegotiationRequest)Optional[negmas.negotiators.Negotiator][source]

Called to respond to a renegotiation request

Parameters
  • agenda

  • contract

  • breaches

Returns:

abstract set_renegotiation_agenda(contract: negmas.situated.Contract, breaches: List[negmas.situated.Breach])Optional[negmas.situated.RenegotiationRequest][source]

Received by partners in ascending order of their total breach levels in order to set the renegotiation agenda when contract execution fails

Parameters
  • contract – The contract being breached

  • breaches – All breaches on contract

Returns

Renegotiation agenda (issues to negotiate about to avoid reporting the breaches).

sign_all_contracts(contracts: List[negmas.situated.Contract])Union[None, str, Dict[str, Optional[str]], List[Optional[str]]][source]

Called to sign all contracts concluded in a single step by this agent

Parameters

contracts – A list of contracts to sign/ refuse to sign

Returns

  • None to indicate refusing to sign all contracts.

  • str (specifically, the agent ID) to indicate signing ALL contracts.

  • List[Optional[str]] A list with a value for each input contract where None means refusal to sign that contract and a string (agent ID) indicates acceptance to sign it. Note that in this case, the number of values in the returned list must match that of the contacts (and they should obviously correspond to the contracts).

  • Dict[str, Optional[str]] A mapping from contract ID to either a None for rejection to sign or a string (for acceptance to sign). Contracts with IDs not in the keys will assumed not to be signed.

Return type

You can return any of the following

Remarks:

  • default implementation calls sign_contract for each contract returning the results

sign_contract(contract: negmas.situated.Contract)Optional[str][source]

Called after the signing delay from contract conclusion to sign the contract. Contracts become binding only after they are signed.

abstract step()[source]

Called by the simulator at every simulation step