Agents

Agent Base Class

class econsimulacra.agents.base.Agent(agent_id, agent_name, env_service_dic, prng=None, config=None)

Bases: ABC, Generic[ObsT]

Agent class.

Once you define the agent class inheriting this agent ABC class, environment automatically generate agents using the class you define. act(self, obs: ObsT) method is the only method that must be implemented in the agent class you define, and it will be called by environment at each step to get the action of the agent.

Parameters:

• agent_id (int)

• agent_name (str)

• env_service_dic (dict[str, Any])

• prng (Random | None)

• config (dict[str, Any] | None)

get_self_name()

Get the name of the agent.

Return type:

str

self_assign_name(config)

Assign a name to the agent based on the configuration.

If “name” is not provided in the config, the agent name will be the default name assigned by environment.

Parameters:

config (dict[str, Any])

Return type:

None

get_inventory()

Get the inventory of the agent.

Return type:

dict[str, float | int]

get_item_amount(item_name)

Get the amount of a specific item in the agent’s inventory.

Parameters:

item_name (str)

Return type:

float | int

abstractmethod async act(obs)

Perform an action based on the observation (abstract method).

Parameters:

obs (ObsT)

Return type:

dict[str, Any]

exchange_goods(get_item_name=None, get_item_amount=None, give_item_name=None, give_item_amount=None)

Exchange goods in the agent’s inventory.

Parameters:

• get_item_name (Optional[str]) – the name of the item to get (optional).

• get_item_amount (Optional[float | int]) – the amount of the item to get (optional, must be provided if get_item_name is provided).

• give_item_name (Optional[str]) – the name of the item to give (optional).

• give_item_amount (Optional[float | int]) – the amount of the item to give (optional, must be provided if give_item_name is provided).

Return type:

None

provide_info4all_agents()

provide information for all agents.

Returns:

a list of information keys that the agent can provide for all agents.

Return type:

list[str]

Note

Usually called by observation providers registered in econsimulacra.environment.base._build_observation_registry. Currently, the following built-in observation provider is supported: econsimulacra.environment.base._obs_others_pos If another agent is requesting “others_pos” information (i.e., “others_pos” is in the self.request_obses of the another agent), the agent can provide its position information to them by adding “self_pos” in self.info4all_agents.

provide_info4co_located_agents()

provide information for those agents who are co-located.

Returns:

a list of information keys that the agent can provide for those agents who are co-located.

Return type:

list[str]

Note

Usually called by observation providers registered in econsimulacra.environment.base._build_observation4co_located_agents_registry. Currently, the following built-in observation provider is supported: econsimulacra.environment.base._obs_others_inventory If another agent who is co-located with the agent is requesting “others_inventory” informaation (i.e., “others_inventory” is in the self.request_obses of the another agent), the agent can provide its inventory information to them by adding “inventory” in self.info4co_located_agents.

provide_info4allowed_agents()

provide information for those agents who are allowed.

Returns:

a list of information keys that the agent can provide for those agents who are is_rich_info_allowed.

Return type:

list[str]

Note

Usually called by observation providers registered in econsimulacra.environment.base._build_observation4allowed_agents_registry. Currently, built-in observation provider is not supported, but users can implement their own observation provider and register it in econsimulacra.environment.base._build_observation4allowed_agents_registry to provide rich information for those agents who are is_rich_info_allowed.

request_obs()

Request observations from the environment.

Returns:

a list of observation keys that the agent is requesting from the environment.

Return type:

list[str]

See also

econsimulacra.environment.base.get_observations

LLM Agent

class econsimulacra.agents.llm_agent.LLMAgent(agent_id, agent_name, env_service_dic, prng=None, config=None)

Bases: Agent[dict[str, Any]]

LLM agent that uses a language model to generate actions based on observations.

The LLMAgent relies on the environment services to provide an LLM client, a prompt builder, and optionally a persona builder. The agent constructs prompts based on the current observation and persona (if applicable), sends the prompt to the LLM client, and returns the generated response as its action.

Parameters:

• agent_id (int)

• agent_name (str)

• env_service_dic (dict[str, Any])

• prng (Random | None)

• config (dict[str, Any] | None)

self_assign_name(config)

Assign name to the agent, potentially using the persona builder if available.

Parameters:

config (dict) – Configuration dictionary for the agent. This may include a “personaConfig” key with configuration for the persona builder.

See also

econsimulacra.llm_services.personas.base.PersonaBuilder

async act(obs)

Generate an action based on the current observation.

Parameters:

obs (dict) – The current observation for the agent. The structure of this dictionary depends on the environment.

Returns:

The action generated by the agent based on the current observation.

The generated action is applied in the environment.

Return type:

dict

Note

This method constructs a prompt by combining the persona prompt (if a persona builder is available) and the observation prompt (constructed by the prompt builder). It then sends the prompt to the LLM client to generate a response.

Government Agent

class econsimulacra.agents.government.Government(agent_id, agent_name, env_service_dic, prng=None, config=None)

Bases: Agent[dict[str, Any]]

Rule-based government agent.

This class only posts tweets based on a predefined schedule and does not interact with other agents or the environment in any other way. The policy must be defined separately by the user as “events”.

Parameters:

• agent_id (int)

• agent_name (str)

• env_service_dic (dict[str, Any])

• prng (Random | None)

• config (dict[str, Any] | None)

self_assign_name(config)

Assign the agent’s name from the config.

To easily determine the name of the government agent, we require that the config contains a “name” field without adding agent_id.

Parameters:

config (dict[str, Any])

Return type:

None

time_to_tweet(current_time)

Return the scheduled tweet.

Parameters:

current_time (str | int)

Return type:

str

async act(obs)

Post a tweet if there is one scheduled for the current time step.

Parameters:

obs (dict[str, Any])

Return type:

dict[str, Any]

Auto-Reactor Agent

class econsimulacra.agents.auto_reacter.AutoReactLLMAgent(agent_id, agent_name, env_service_dic, prng=None, config=None)

Bases: LLMAgent

An LLMAgent that automatically reacts to all incoming orders and proposals.

This wrapper enforces deterministic acceptance of transactional intents (i.e., incoming_orders and incoming_proposals) posterior to, or independently of, the LLM-generated decision. The primary objective is to eliminate non-responsive or economically irrational behaviors (e.g., ignoring valid orders) that often arise from stochastic LLM outputs in supply-side agents such as retailers and restaurants.

In socio-economic EconSimulacra, supply-side agents are expected to process transactions reliably. However, vanilla LLMAgents may omit reactions due to prompt misalignment or token truncation. This wrapper guarantees that all valid incoming transactional requests are accepted, thereby preserving simulation consistency and preventing deadlocks in the market mechanism.

Parameters:

• agent_id (int)

• agent_name (str)

• env_service_dic (dict[str, Any])

• prng (Random | None)

• config (dict[str, Any] | None)

async act(obs)

Automatically react to all incoming orders and proposals.

Get the LLM-generated response and then overwrite the reactions field to ensure that all incoming transactional intents are accepted.

Parameters:

obs (dict[str, Any]) – The observation dictionary containing the current state of the agent, including any incoming orders and proposals.

Returns:

A dictionary representing the agent’s action,

with the reactions field modified to accept all incoming transactional intents.

Return type:

dict

judge_reaction(incoming_transactional_intent, current_inventory, is_order)

Judge whether to react to an incoming transactional intent based on the current inventory.

Parameters:

• incoming_transactional_intent (dict[str, Any]) – A dictionary representing the incoming order or proposal that the agent is evaluating.

• current_inventory (dict[str, float | int]) – A dictionary representing the agent’s current inventory before reacting to the intent.

• is_order (bool) – A boolean indicating whether the incoming transactional intent is an order (True) or a proposal (False).

Returns:

True if the agent should react to the incoming transactional intent,

False otherwise.

Return type:

bool

Note

Always True as long as the agent has sufficient inventory to fulfill the intent.