Architecture
This page describes the full architecture of MAS-Aviary, covering the end-to-end flow from user request to Aviary optimization, the three organizational structures, the three operational handlers, and how they compose into eight valid coordination strategies.
Overview
The system follows a layered architecture where each layer has a single responsibility:
+--------+ +--------------+ +------------+ +---------+
| User | --> | Coordinator | --> | Strategy | --> | Handler |
+--------+ +--------------+ +------------+ +---------+
|
v
+---------+
| Agent |
+---------+
|
v
+-------------------+
| MCP Server (:8600)|
+-------------------+
|
v
+-------------------+
| Aviary / OpenMDAO|
+-------------------+
- Coordinator (
src.coordination.coordinator) Entry point. Loads configuration, selects the strategy and handler, manages the agent registry, and orchestrates the full run lifecycle.
- Strategy (
src.coordination.strategies) Defines how agents are organized: who talks to whom and in what structure. Three strategies are available (see below).
- Handler (
src.coordination.execution_handler) Defines how work proceeds: the operational pattern that controls iteration, routing, and completion. Three handlers are available.
- Agent (
src.agents) An LLM-backed entity that reasons about aircraft design parameters and invokes MCP tools.
- MCP Server
Exposes Aviary design-space tools over the Model Context Protocol on port 8600.
Organizational Structures (Strategies)
The organizational structure determines the communication topology among
agents. Each structure is implemented as a subclass of the base Strategy.
Sequential
+----------+ +----------+ +----------+ +----------+
| Agent A | --> | Agent B | --> | Agent C | --> | Agent D |
+----------+ +----------+ +----------+ +----------+
Stage 1 Stage 2 Stage 3 Stage 4
Agents execute one after another in a fixed pipeline order. Each agent receives the accumulated context from all prior stages and appends its own results before passing control to the next agent.
Module:
src.coordination.strategies.sequentialConfig:
config/aviary_sequential.yamlKey properties:
Deterministic execution order.
Each agent sees the full history of prior stages.
Pipeline template defines stage names and assigned agents.
Stage-level
max_stepslimits per-agent iterations.
Orchestrated
+----------------+
| Orchestrator |
+----------------+
/ | \
v v v
+--------+ +--------+ +--------+
| Agent A| | Agent B| | Agent C|
+--------+ +--------+ +--------+
A central orchestrator agent delegates tasks to specialist agents. The orchestrator decides which agent to invoke, what task to assign, and when the overall objective is met.
Module:
src.coordination.strategies.orchestratedConfig:
config/aviary_run.yaml(orchestrator section)Key properties:
Centralized decision-making via the orchestrator agent.
Dynamic task delegation – the orchestrator chooses agents at runtime.
Specialist agents have narrow, well-defined roles.
The orchestrator synthesizes partial results into a final answer.
Networked
+--------+ +--------+
| Agent A| <---> | Agent B|
+--------+ +--------+
^ \ / ^
| v v |
| +---------+ |
| |Blackboard| |
| +---------+ |
| ^ ^ |
v / \ v
+--------+ +--------+
| Agent C| <---> | Agent D|
+--------+ +--------+
Agents communicate through a shared Blackboard – a central data store where agents post findings, claim tasks, and read each other’s results. There is no fixed ordering; agents operate concurrently in workflow phases.
Module:
src.coordination.strategies.networkedConfig:
config/aviary_networked.yamlKey properties:
Decentralized, peer-to-peer communication via the blackboard.
Workflow proceeds in named phases (e.g.,
explore,refine,converge).Claiming mode controls whether agents compete for or share tasks.
Agents read and react to other agents’ blackboard entries.
Operational Handlers
Handlers define the operational pattern – how agents do their work within the structure defined by the strategy.
Iterative Feedback Handler
+-------+ +----------+ +----------+ +--------+
| Start | --> | Agent | --> | Evaluate | --> | Better |--+
+-------+ | executes | | result | | than | |
+----------+ +----------+ | prev? | |
^ +--------+ |
| No | |
+<--------------------------------+ |
Yes | |
v |
+--------+ |
| Done |<-+
+--------+
(max iters)
Each agent iterates on its task, receiving feedback from the evaluation of its prior attempt. The loop continues until the result meets acceptance criteria or the maximum iteration count is reached.
Module:
src.coordination.iterative_feedback_handlerConfig:
config/iterative_feedback.yamlKey components:
FeedbackExtraction– extracts actionable feedback from evaluation.CompletionCriteria– determines when an agent’s work is sufficient.TerminationChecker– enforces global stopping conditions.
Staged Pipeline Handler
+-----------+ +------------+ +-----------+ +----------+
| Stage 1 | --> | Gate 1 | --> | Stage 2 | --> | Gate 2 |
| (explore) | | (criteria) | | (refine) | | (criteria)|
+-----------+ +------------+ +-----------+ +----------+
|
v
+-----------+
| Stage 3 |
| (finalize)|
+-----------+
Work is divided into named stages, each with explicit completion criteria that act as quality gates. An agent (or group of agents) must satisfy the gate before the pipeline advances to the next stage.
Module:
src.coordination.staged_pipeline_handlerConfig:
config/aviary_staged_pipeline.yamlKey components:
StageDefinition– declares stage name, assigned agents, and goals.CompletionCriteria– per-stage quality gates.PipelineTemplate– ordered list of stages.
Graph-Routed Handler
+----------+ +----------+ +----------+
| State A | --T1---> | State B | --T2---> | State C |
+----------+ +----------+ +----------+
| | |
+------T3----------->-+------T4----------->-+
| |
+-------------------T5--------------------->+
T1..T5 = transitions (condition-guarded edges)
The handler models the optimization as a state machine. Each state maps to an agent action, and transitions are guarded by conditions evaluated against the current results. This allows non-linear, adaptive workflows where the next step depends on runtime data.
Module:
src.coordination.graph_routed_handlerConfig:
config/aviary_graph.yamlKey components:
GraphDefinition– declares states and transitions.ConditionEvaluator– evaluates transition guard expressions.ResourceManager– enforces per-state resource budgets (steps, time).
Strategy x Handler Combinations
Every organizational structure can be paired with every operational handler, producing eight valid combinations (one combination — Networked + Staged Pipeline — is excluded; see note below):
Structure \ Handler |
Iterative Feedback |
Staged Pipeline |
Graph-Routed |
|---|---|---|---|
Sequential |
sequential_iterative_feedback |
sequential_staged_pipeline |
sequential_graph_routed |
Orchestrated |
orchestrated_iterative_feedback |
orchestrated_staged_pipeline |
orchestrated_graph_routed |
Networked |
networked_iterative_feedback |
not valid |
networked_graph_routed |
Note
Networked + Staged Pipeline is not a valid combination. The Staged Pipeline handler assumes a fixed sequence of stages with deterministic agent-to-stage assignment, which conflicts with the Networked strategy’s peer-based role rotation and blackboard claiming model.
Each combination has a unique identifier (shown in the cells) used in
configuration files and the stat_batch_runner.py --combinations flag.
Blackboard Communication (Networked)
The blackboard is the shared memory substrate for the Networked strategy.
+-----------------------------------------------------------+
| Blackboard |
|-----------------------------------------------------------|
| Section | Writer | Content |
|----------------|----------|-------------------------------|
| parameters | Agent A | {"wing_area": 120.5, ...} |
| evaluation | Agent B | {"fuel_burned": 13200, ...} |
| proposals | Agent C | {"change": "increase AR",...} |
| consensus | All | {"agreed_params": {...}} |
+-----------------------------------------------------------+
Agents post entries tagged with their identity and a section name.
Agents read entries from other sections to inform their reasoning.
The claiming mode (
exclusiveorshared) controls whether a posted task can be picked up by one agent or many.The blackboard is persisted across workflow phases within a single run.
Orchestrator Delegation Flow
In the Orchestrated strategy, the orchestrator agent follows this decision loop:
+---------------------+
| Orchestrator starts |
+---------------------+
|
v
+---------------------+
| Assess current state |<--------------------------+
+---------------------+ |
| |
v |
+---------------------+ No |
| Objective met? |-------+ |
+---------------------+ | |
| Yes v |
v +------------------+ |
+--------+ | Select specialist | |
| Done | +------------------+ |
+--------+ | |
v |
+------------------+ |
| Delegate subtask | |
+------------------+ |
| |
v |
+------------------+ |
| Collect result |----------+
+------------------+
The orchestrator uses special tools (src.tools.orchestrator_tools) to
delegate work and collect results from specialist agents.
Sequential Pipeline Stages
In the Sequential strategy, the pipeline template defines an ordered list of stages. Each stage specifies:
Stage name – a human-readable label (e.g.,
initial_sizing).Assigned agent – which agent executes this stage.
Max steps – upper bound on LLM calls within the stage.
Input mapping – how prior-stage outputs feed into this stage.
Pipeline Template (example):
Stage 1: initial_sizing
Agent: sizing_agent
Max steps: 10
Inputs: user requirements
|
v
Stage 2: aerodynamic_analysis
Agent: aero_agent
Max steps: 15
Inputs: Stage 1 outputs
|
v
Stage 3: propulsion_optimization
Agent: propulsion_agent
Max steps: 15
Inputs: Stage 1 + Stage 2 outputs
|
v
Stage 4: final_evaluation
Agent: eval_agent
Max steps: 10
Inputs: All prior stage outputs
Agent Lifecycle and MCP Interaction
Each agent follows a consistent lifecycle regardless of the strategy or handler it operates under:
+--------------+ +----------------+ +---------------+
| 1. Receive | --> | 2. Reason | --> | 3. Select |
| task | | (LLM call) | | MCP tool |
+--------------+ +----------------+ +---------------+
|
v
+---------------+
| 4. Call MCP |
| server |
+---------------+
|
v
+---------------+
| 5. Process |
| result |
+---------------+
|
v
+---------------+
| 6. Report |
| back |
+---------------+
Step 1 – Receive task: The handler assigns a task description and any relevant context (prior results, feedback, blackboard state).
Step 2 – Reason: The agent’s LLM processes the task and context, producing a chain-of-thought plan.
Step 3 – Select MCP tool: Based on its reasoning, the agent selects one or more tools exposed by the Aviary MCP server.
Step 4 – Call MCP server: The agent invokes the tool via HTTP on
localhost:8600. The MCP connector (src.tools.mcp_connector) handles
serialization, retries, and error mapping.
Step 5 – Process result: The agent interprets the tool’s response (e.g., new metric values, parameter sensitivities) and updates its internal state.
Step 6 – Report back: The agent returns its results to the handler, which decides the next action (iterate, advance stage, transition state, or terminate).
The agent factory (src.agents.agent_factory) constructs agents with the
correct LLM model, system prompt, and tool set. The agent registry
(src.agents.agent_registry) tracks all active agents for the coordinator.