Migrating to v0.2

Academy v0.2 makes numerous breaking changes. This page highlights the most important changes to help you migrate your code from v0.1 to v0.2.

Please refer to our Versioning Policy for more details on when we make breaking changes.

Academy is now async

Academy is now an async-first library. The asyncio model is better aligned with the highly asynchronous programming model of Academy. Agent actions and control loops are now executed in the event loop of the main thread, rather than in separate threads. All exchanges and the manager are async now.

Renamed Components

Entities are now referred to as agents and users (previously, clients). Agents are now derived from Agent (previously, Behavior) and run using a Runtime (previously, Agent).

Summary:

• academy.agent.Agent is renamed academy.runtime.Runtime.
• academy.behavior.Behavior is renamed academy.agent.Agent.
• academy.identifier.ClientId is renamed academy.identifier.UserId.

Changes to Agents

All special methods provided by Agent are named agent_.*. For example, the startup and shutdown callbacks have been renamed:

• Agent.on_setup is renamed Agent.agent_on_startup
• Agent.on_shutdown is renamed Agent.agent_on_shutdown

Runtime context is now available via additional methods.

Changes to Exchanges

The Exchange and Mailbox protocols have been merged into a single ExchangeClient which comes in two forms:

• AgentExchangeClient
• UserExchangeClient

Thus, an ExchangeClient has a 1:1 relationship with the mailbox of a single entity. Each ExchangeClient is initialized using a ExchangeTransport. This protocol defines low-level client interaction with the exchange. Some of the exchange operations have have been changed:

• register_client() has been removed
• send() no longer takes a dest parameter
• status() has been added

Exchange clients are created using a factory pattern:

• ExchangeFactory.create_agent_client()
• ExchangeFactory.create_user_client()

All exchange implementations have been updated to provide a custom transport and factory implementation. The "thread" exchange has been renamed to "local" now that Academy is async.

All exchange related errors derive from ExchangeError. MailboxClosedError is renamed MailboxTerminatedError with derived types for AgentTerminatedError and UserTerminatedError.

Changes to the Manager and Launchers

The Launcher protocol and implementations have been removed, with their functionality incorporated directly into the Manager.

Summary:

• Manager is now initialized with one or more Executors.
• Added the Manager.from_exchange_factory() class method.
• Manager.set_default_launcher() and Manager.add_launcher() are renamed set_default_executor() and add_executor(), respectively.
• Manager exposes get_handle() and register_agent().
• Manager.launch() now optionally takes an Agent type and args/kwargs and will defer agent initialization to on worker.
• Manager.wait() now takes an iterable of agent IDs or handles.