Minimal Academy Example

The simplest possible Academy agent setup: two agents that communicate.

Code: View on GitHub

What It Does

Demonstrates Academy basics with just two agents:

  1. RequesterAgent: Sends a calculation request to the Calculator
  2. CalculatorAgent: Performs the calculation, returns the result

This is the “Hello World” of Academy - understand this before moving to complex pipelines.

Running the Example

cd Capabilities/local-agents/AgentsAcademyBasic
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.py

Custom expression:

python main.py --expression "2 ** 10"

Example Output

==================================================
MINIMAL ACADEMY EXAMPLE
==================================================
Expression: 42 * 17
--------------------------------------------------
16:57:51 [academy.basic] Launched Calculator: ...
16:57:51 [academy.basic] Launched Requester: ...
16:57:51 [academy.basic] Requester: Calculator handle received
16:57:51 [academy.basic] Requester sending: 42 * 17
16:57:51 [academy.basic] Calculator received: 42 * 17
16:57:51 [academy.basic] Calculator computed: 42 * 17 = 714
16:57:51 [academy.basic] Requester received: 42 * 17 = 714
--------------------------------------------------
RESULT: 42 * 17 = 714
==================================================

Architecture

+-------------+                  +---------------+
|  Requester  |                  |  Calculator   |
|             |                  |               |
|  request_   |  --- call -----> |  calculate()  |
|  calculation|                  |       |       |
|      |      |                  |       v       |
|      v      |  <-- return ---  |    eval()     |
|   result    |                  |               |
+-------------+                  +---------------+
      ^                                  |
      |                                  |
      +---- Academy Message Exchange ----+

Key Concepts

1. Agents are Classes

from academy.agent import Agent, action

class CalculatorAgent(Agent):
    @action
    async def calculate(self, expression: str) -> str:
        result = eval(expression, {"__builtins__": {}}, {})
        return f"{expression} = {result}"

2. Actions are Async Methods

The @action decorator marks methods that can be called remotely:

@action
async def calculate(self, expression: str) -> str:
    # This can be called by other agents or the main process
    return f"Result: {eval(expression)}"

3. Manager Launches Agents

async with await Manager.from_exchange_factory(
    factory=LocalExchangeFactory(),
) as manager:
    calculator = await manager.launch(CalculatorAgent)

4. Handles Enable Communication

manager.launch() returns a Handle (proxy) for the agent. Handles can be passed to other agents:

# Main process passes calculator handle to requester
await requester.set_calculator(calculator)

# Inside RequesterAgent, store and use the handle
@action
async def set_calculator(self, calculator: Handle) -> None:
    self._calculator = calculator

@action
async def request_calculation(self, expression: str) -> str:
    # Call calculator via its handle
    result = await self._calculator.calculate(expression)
    return result

5. Local vs Remote Exchange

Same code works with both!

Comparison: Academy vs LangGraph

Aspect Academy LangGraph
Agent model Independent processes/actors Functions in a graph
Communication Message passing via Handles Shared state
Scaling Distributed by design Single process (typically)
Best for Multi-system, HPC, federation LLM reasoning chains

Next Steps

After understanding this example, explore these in order:

Example What You’ll Learn
AgentsRemoteTools Coordinator calling tools on remote agents
AgentsHybrid Combining Academy with LangGraph for LLM reasoning
AgentsPersistent Checkpoint and resume workflows
AgentsFederated Cross-institutional collaboration
AgentsAcademy 5-agent pipeline with agent-to-agent messaging

Also see:

Requirements