Skip to content
Navigation

Architecture Overview

Exo is a modern multi-agent framework built as a ground-up rewrite of AWorld (96,500 LOC). It is organized as a UV workspace monorepo with 13 focused packages under packages/, each with a single re...

Exo is a modern multi-agent framework built as a ground-up rewrite of AWorld (96,500 LOC). It is organized as a UV workspace monorepo with 13 focused packages under packages/, each with a single responsibility and minimal dependencies.

Design Philosophy

Exo’s design draws from the best ideas across existing frameworks while avoiding their pitfalls:

  • Simplicity from AWorld’s lessons — AWorld grew to 96k lines with deep inheritance, stringly-typed routing, and duplicated sync/async classes. Exo starts clean with a ~200 line-per-file cap and flat composition.
  • Async-first — All internal functions are async def. A single run.sync() bridge covers synchronous callers. No sync/async class duplication.
  • Type-safe — Full pyright strict-mode compliance. Typed message classes replace stringly-typed routing. Pydantic v2 models for all configuration and data.
  • Composable — One Agent class, one Swarm orchestrator, one Registry[T] pattern. Behavior changes through composition (tools, hooks, modes), not inheritance hierarchies.

Package Overview

code
exo (workspace root)
|
+-- packages/
    |
    +-- exo-core       Core types, Agent, Tool, Swarm, Runner, Hooks, Events
    +-- exo-models     LLM provider abstractions (OpenAI, Anthropic)
    +-- exo-context    Context engine: state, prompt building, neurons, processors
    +-- exo-memory     Short-term and long-term memory backends
    +-- exo-mcp        Model Context Protocol client + server decorator
    +-- exo-sandbox    Local and Kubernetes sandboxed execution
    +-- exo-trace      OpenTelemetry-based tracing and instrumentation
    +-- exo-eval       Evaluation framework: scorers, reflection, evaluator
    +-- exo-a2a        Agent-to-Agent protocol for remote delegation
    +-- exo-cli        Command-line interface
    +-- exo-server     HTTP server for serving agents
    +-- exo-train      Training: trajectory collection, dataset, trainers
    +-- exo            Meta-package that re-exports everything

Dependency DAG

The dependency structure is strictly layered. exo-core sits at the bottom with zero heavy dependencies (only pydantic). Every other package depends on exo-core, but packages at the same level do not depend on each other.

code
                        exo (meta)
                            |
     +----------+-----------+-----------+----------+
     |          |           |           |          |
  exo-   exo-   exo-   exo-   exo-
  cli        server     train      a2a        eval
     |          |           |           |          |
     +----------+-----------+-----------+----------+
                            |
     +----------+-----------+-----------+----------+
     |          |           |           |          |
  exo-   exo-   exo-   exo-   exo-
  models     context    memory     mcp        sandbox
     |          |           |           |          |
     +----------+-----------+-----------+----------+
                            |
                      exo-core
                      (pydantic only)

Core Concepts

ConceptModuleDescription
Agentexo.agentAutonomous LLM-powered unit with tools, handoffs, and hooks
Toolexo.toolFunction or class that an agent can call via LLM tool-use
Swarmexo.swarmMulti-agent orchestration: workflow, handoff, or team mode
Runnerexo.runnerEntry points: run(), run.sync(), run.stream()
Hookexo.hooksLifecycle interception at PRE/POST_LLM_CALL, PRE/POST_TOOL_CALL
EventBusexo.eventsDecoupled async pub/sub for framework-level events
Registryexo.registryGeneric Registry[T] for agents, tools, models, neurons
Contextexo.contextHierarchical state, prompt building, RAG, workspace

What Users Import

Most applications need only the top-level imports:

python
from exo import Agent, Swarm, Tool, tool, run

For advanced usage:

python
from exo.types import UserMessage, AssistantMessage, RunResult, StreamEvent
from exo.config import AgentConfig, ModelConfig
from exo.hooks import Hook, HookPoint
from exo.models import ModelProvider, get_provider
from exo.context import Context, ContextConfig, PromptBuilder

Further Reading