Agent

class ambr.agent.Agent(model: BaseModel, agent_id: int)

Bases: BaseAgent

Base class for all agents in the simulation.

Note

Setting an attribute on a Python Agent instance (e.g. agent.wealth = 5) automatically queues a write to the underlying columnar DataFrame. This keeps the Python objects and the columnar store in sync — you can freely mix OOP-style attribute access with the view API (model.agents.wealth). Internal attributes (model, id, p, anything starting with _) are stored on the instance only.

__setattr__(name: str, value: Any) → None

Route non-internal attribute writes to the DataFrame.

• model, id, p — stored on the Python instance only.

• Private names (_ prefix) — stored on the Python instance only.

• Everything else — queued to the DataFrame via model._queue_write and stored on the instance for fast local access during the same step.

get_data() → DataFrame

Return this agent’s row as a 1-row DataFrame.

get_neighbors(condition: Expr | None = None) → DataFrame

Return all other agents, optionally filtered by condition.

record(name: str, value: Any)

Record a variable value for this agent.

setup()

Override in subclasses to initialize agent attributes.

update_data(data: Dict[str, Any])

Update this agent’s columns from a dict.

The Agent class represents individual entities in your simulation. Each agent has:

• A unique ID within the model

• Access to the model and its parameters

• Ability to store custom attributes

• Methods for interacting with other agents and the environment

Basic Usage

import ambr as am

class MyAgent(am.Agent):
    def __init__(self, model, agent_id):
        super().__init__(model, agent_id)
        self.wealth = 10
        self.age = 0

    def step(self):
        # Define agent behavior
        self.age += 1
        # ... other behaviors

# In your model's setup():
agent = MyAgent(self, agent_id)
self.add_agent(agent)

Custom Agent Classes

You can create custom agent classes by inheriting from BaseAgent:

from ambr.base import BaseAgent

class CustomAgent(BaseAgent):
    def __init__(self, model, agent_id):
        super().__init__(model, agent_id)
        self.custom_property = "value"

    def custom_method(self):
        # Your custom behavior
        pass

Agent Properties

Built-in Properties:

• id - Unique identifier for the agent

• model - Reference to the parent model

• p - Shortcut to model parameters (model.p)

Custom Properties:

You can add any custom properties to agents by setting them as attributes:

agent.wealth = 100
agent.position = (5, 10)
agent.state = "active"