ARE

Environment wrapper for Meta's Agent Research Environments (ARE).

Installation

pip install maseval[are]

Alternatively, install ARE directly:

pip install meta-agents-research-environments

API Reference

View source

AREEnvironment

Bases: Environment

Generic maseval Environment wrapping ARE's simulation infrastructure.

Two construction paths:

From a Scenario: AREEnvironment.from_scenario(scenario)
From apps: AREEnvironment.from_apps(apps=[...], duration=60, seed=42)

Both paths also accept run_oracle, notification_verbosity, filter_aui_tools, and callbacks.

The raw AREEnvironment(environment_data=...) constructor is available for subclasses that need full control over setup_state().

Lifecycle is user-controlled: call start() before run_agents(), stop() after. pause()/resume_with_offset() control simulation time.

init

__init__(
    environment_data: Dict[str, Any],
    callbacks: Optional[List[EnvironmentCallback]] = None,
    run_oracle: bool = False,
    notification_verbosity: str = "medium",
    filter_aui_tools: bool = False,
)

Initialize AREEnvironment.

PARAMETER	DESCRIPTION
`environment_data`	Dict. Must contain either: - `"scenario"`: ARE Scenario object, OR - `"apps"`: list of ARE App instances, plus required `"duration"` and `"seed"`, and optional `"events"`, `"start_time"`, `"time_increment_in_seconds"` TYPE: `Dict[str, Any]`
`callbacks`	Optional maseval EnvironmentCallbacks. TYPE: `Optional[List[EnvironmentCallback]]` DEFAULT: `None`
`run_oracle`	If True, run ARE oracle mode during setup to generate expected event log. Stored in traces for evaluation. TYPE: `bool` DEFAULT: `False`
`notification_verbosity`	ARE notification verbosity level. `"low"` = no environment notifications, `"medium"` = standard notifications, `"high"` = all notifications. TYPE: `str` DEFAULT: `'medium'`

cleanup

cleanup() -> None

Stop ARE simulation. Called by maseval after task completes.

create_tools

create_tools() -> Dict[str, AREToolWrapper]

Wrap all ARE app tools in AREToolWrapper.

RETURNS	DESCRIPTION
`Dict[str, AREToolWrapper]`	Dict mapping tool names to AREToolWrapper instances.

from_apps `classmethod`

from_apps(
    apps: List[Any],
    duration: int,
    seed: int,
    events: Optional[List[Any]] = None,
    start_time: float = 0,
    time_increment_in_seconds: int = 1,
    scenario_id: str = "custom",
    callbacks: Optional[List[EnvironmentCallback]] = None,
    run_oracle: bool = False,
    notification_verbosity: str = "medium",
    filter_aui_tools: bool = False,
) -> AREEnvironment

Create AREEnvironment from ARE app instances and explicit config.

PARAMETER	DESCRIPTION
`apps`	List of ARE App instances (e.g. `[CalendarApp(), ContactsApp()]`). TYPE: `List[Any]`
`duration`	Scenario duration in seconds. Required — no default. TYPE: `int`
`seed`	Random seed for reproducibility. Required — no default. TYPE: `int`
`events`	Optional list of ARE events to schedule. TYPE: `Optional[List[Any]]` DEFAULT: `None`
`start_time`	Simulation start time in seconds. TYPE: `float` DEFAULT: `0`
`time_increment_in_seconds`	Fixed tick interval (>= 1 second). TYPE: `int` DEFAULT: `1`
`scenario_id`	Identifier for the scenario. TYPE: `str` DEFAULT: `'custom'`
`callbacks`	Optional maseval EnvironmentCallbacks. TYPE: `Optional[List[EnvironmentCallback]]` DEFAULT: `None`
`run_oracle`	If True, run ARE oracle mode during setup. TYPE: `bool` DEFAULT: `False`
`notification_verbosity`	`"low"`, `"medium"`, or `"high"`. TYPE: `str` DEFAULT: `'medium'`
`filter_aui_tools`	If True, exclude AUI message-retrieval tools. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`AREEnvironment`	Configured AREEnvironment instance.

from_scenario `classmethod`

from_scenario(
    scenario: Any,
    callbacks: Optional[List[EnvironmentCallback]] = None,
    run_oracle: bool = False,
    notification_verbosity: str = "medium",
    filter_aui_tools: bool = False,
) -> AREEnvironment

Create AREEnvironment from a pre-built ARE Scenario.

PARAMETER	DESCRIPTION
`scenario`	ARE Scenario object (from `are.simulation.scenarios`). TYPE: `Any`
`callbacks`	Optional maseval EnvironmentCallbacks. TYPE: `Optional[List[EnvironmentCallback]]` DEFAULT: `None`
`run_oracle`	If True, run ARE oracle mode during setup. TYPE: `bool` DEFAULT: `False`
`notification_verbosity`	`"low"`, `"medium"`, or `"high"`. TYPE: `str` DEFAULT: `'medium'`
`filter_aui_tools`	If True, exclude AUI message-retrieval tools. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`AREEnvironment`	Configured AREEnvironment instance.

gather_config

gather_config() -> Dict[str, Any]

Gather environment configuration for reproducibility.

gather_traces

gather_traces() -> Dict[str, Any]

Collect traces from environment and all tools.

get_are_environment

get_are_environment() -> Optional[Environment]

Get the underlying ARE Environment instance.

get_notification_system

get_notification_system() -> Optional[
    VerboseNotificationSystem
]

Get the ARE notification system.

get_oracle_traces

get_oracle_traces() -> Optional[Dict[str, Any]]

Get oracle event log if oracle mode was enabled.

RETURNS	DESCRIPTION
`Optional[Dict[str, Any]]`	Oracle traces dict, or None if oracle was not run.

get_scenario

get_scenario() -> Optional[Scenario]

Get the ARE scenario object.

get_simulation_time

get_simulation_time() -> float

Get current simulation time in seconds since scenario start.

get_start_time

get_start_time() -> Optional[float]

Get the scenario start time.

get_tool

get_tool(name: str) -> Optional[Any]

Get a tool by name.

PARAMETER	DESCRIPTION
`name`	Tool name TYPE: `str`

RETURNS	DESCRIPTION
`Optional[Any]`	The tool, or None if not found

get_tools

get_tools() -> Dict[str, Any]

Get all tools as a dict.

get_turn_notifications

get_turn_notifications() -> Tuple[List[str], bool, bool]

Drain pending notifications, re-queuing environment notifications.

Like poll_notifications but instead of formatting environment notifications into strings, it re-queues them back onto the message queue so they remain available for later processing, and returns boolean flags indicating their presence.

RETURNS	DESCRIPTION
`List[str]`	Tuple of `(user_messages, has_env_notifications, has_stop)`.
`bool`	`user_messages`: Messages from simulated users.
`bool`	`has_env_notifications`: True if any environment notifications were seen.
`Tuple[List[str], bool, bool]`	`has_stop`: True when simulation has ended.

pause

pause() -> None

Pause simulation time progression.

RAISES	DESCRIPTION
`RuntimeError`	If the ARE environment is not initialized.

poll_notifications

poll_notifications() -> Tuple[List[str], List[str], bool]

Drain pending notifications from ARE's notification queue.

RETURNS	DESCRIPTION
`List[str]`	Tuple of `(user_messages, env_notifications, has_stop_signal)`.
`List[str]`	`user_messages`: Messages from simulated users.
`bool`	`env_notifications`: System events (new email, calendar reminder, etc.).
`Tuple[List[str], List[str], bool]`	`has_stop_signal`: True when simulation has ended.

Agent adapters should call this between agent steps and inject the messages into the agent's context.

resume_with_offset

resume_with_offset(offset: float) -> None

Resume simulation with a time offset.

PARAMETER	DESCRIPTION
`offset`	Seconds to advance simulation clock before resuming. TYPE: `float`

RAISES	DESCRIPTION
`RuntimeError`	If the ARE environment is not initialized.

setup_state

setup_state(
    environment_data: Dict[str, Any],
) -> Dict[str, Any]

Initialize ARE environment from environment data.

PARAMETER	DESCRIPTION
`environment_data`	Dict with `"scenario"` or `"apps"` key. TYPE: `Dict[str, Any]`

RETURNS	DESCRIPTION
`Dict[str, Any]`	State dict with scenario metadata.

RAISES	DESCRIPTION
`ValueError`	If environment_data contains neither `"scenario"` nor `"apps"`.

start

start() -> None

Start the ARE simulation event loop.

RAISES	DESCRIPTION
`RuntimeError`	If the ARE environment is not initialized.

stop

stop() -> None

Stop the ARE simulation event loop.

RAISES	DESCRIPTION
`RuntimeError`	If the ARE environment is not initialized.

AREToolWrapper

Bases: TraceableMixin, ConfigurableMixin

Framework-agnostic wrapper for ARE tools with maseval tracing.

Wraps an ARE Tool and exposes its metadata (name, description, inputs, output_type) so that agent adapters can construct framework-native tools.

Example for smolagents::

class MySmolagentsTool(smolagents.Tool):
    skip_forward_signature_validation = True

    def __init__(self, wrapper: AREToolWrapper):
        self.wrapper = wrapper
        self.name = wrapper.name
        self.description = wrapper.description
        self.inputs = wrapper.inputs
        self.output_type = wrapper.output_type
        super().__init__()

    def forward(self, **kwargs) -> str:
        return self.wrapper(**kwargs)

call

__call__(**kwargs: Any) -> Any

Execute the ARE tool with tracing.

PARAMETER	DESCRIPTION
`**kwargs`	Tool arguments matching the inputs schema. TYPE: `Any` DEFAULT: `{}`

RETURNS	DESCRIPTION
`Any`	Tool output (type varies per tool).

init

__init__(are_tool: Any, environment: AREEnvironment)

Initialize the tool wrapper.

PARAMETER	DESCRIPTION
`are_tool`	ARE Tool instance to wrap. TYPE: `Any`
`environment`	The AREEnvironment this tool belongs to. TYPE: `AREEnvironment`

gather_config

gather_config() -> Dict[str, Any]

Gather configuration from this tool.

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dictionary with tool name, description, and schema.

gather_traces

gather_traces() -> Dict[str, Any]

Gather execution traces from this tool.

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dictionary with tool name, invocation history, and counts.

ARE

Installation

API Reference

AREEnvironment

__init__

cleanup

create_tools

from_apps classmethod

from_scenario classmethod

gather_config

gather_traces

get_are_environment

get_notification_system

get_oracle_traces

get_scenario

get_simulation_time

get_start_time

get_tool

get_tools

get_turn_notifications

pause

poll_notifications

resume_with_offset

setup_state

start

stop

AREToolWrapper

__call__

__init__

gather_config

gather_traces

init

from_apps `classmethod`

from_scenario `classmethod`

call

init