Skip to content

Migration Guide

This guide helps users adapt to breaking changes introduced during the v0.X development cycle, such as:

  • Changes to APIs, behavior, or configuration that require user action
  • Deprecated or removed features
  • Recommended steps for upgrading between versions

We provide migration notes for each v0.X release to make upgrades easier during this early phase of development. After v1.0, this guide will be retired. All future changes—including breaking changes and deprecations—will be documented in the project changelog.

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

Academy v0.3

Handle actions are blocking by default

Previously, invoking an action on a Handle returned a Future to the result. This resulted in verbose syntax when the result was immediately needed: 

future = await handle.get_count()
result = await future
# or
result = await (await handle.get_count())

Now, action requests block and return the final result of the action: 

result = await handle.get_count()
Code that wants to submit the request and later block on it can create a Task. 
task = asyncio.create_task(handle.get_count())
# ... do other work ...
await task
print(task.result())
Using tasks is especially useful when launching multiple long-running actions concurrently and waiting for them in a flexible manner. For example, instead of waiting for each action sequentially, you can start them all at once and then wait for them to complete using asyncio.wait() or asyncio.as_completed().

Academy v0.2

Academy is now async-first

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:

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:

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:

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: