# How to Implement the AAOSA Protocol for Adaptive Agent Communication

> Implement the AAOSA protocol for adaptive agent communication by leveraging Hugging Face Hub for policy definitions and dynamic agent network assembly within Neuro-San Studio. Learn how to deploy sub-agents and manage dynamic r...

- Repository: [Cognizant AI Lab/neuro-san-studio](https://github.com/cognizant-ai-lab/neuro-san-studio)
- Tags: how-to-guide
- Published: 2026-02-27

---

**The Neuro-San Studio repository implements the AAOSA (Adaptive Agent Orchestration and Sub-Agent) protocol by storing reusable policy definitions in `registries/aaosa.hocon` and injecting them into agent networks via the `DeployableAgentNetworkAssembler` class, enabling dynamic relevance determination, sub-agent delegation, and structured JSON responses.**

The **AAOSA protocol** standardizes how agents decide whether to handle requests, invoke downstream agents, or seek clarification. In the `cognizant-ai-lab/neuro-san-studio` repository, this protocol is implemented through a modular three-layer architecture that separates policy definitions from network assembly logic. This architecture allows developers to implement the AAOSA protocol for adaptive agent communication across both programmatically assembled networks and declarative HOCON configurations.

## Core Architecture of the AAOSA Implementation

The implementation consists of three distinct layers that work together to inject AAOSA capabilities into any agent network.

### The Definition Layer: registries/aaosa.hocon

The file `registries/aaosa.hocon` serves as the central data store for all AAOSA artifacts. This **pure data** file contains no agent or tool definitions—only substitution keys that other components can reference:

- **`aaosa_instructions`**: A multi-line natural-language policy that guides agents on when to *determine* relevance, *call* downstream agents, request clarification, and *fulfill* requests.
- **`aaosa_call`**: A JSON-schema-styled function description that agents expose to other agents for delegation.
- **`aaosa_command`**: A templated JSON response format that each agent must return, depending on the selected `mode` ("Determine", "Fulfill", or "Follow up").

> Source: [`registries/aaosa.hocon`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/registries/aaosa.hocon)

### The Assembler Layer: DeployableAgentNetworkAssembler

The **`DeployableAgentNetworkAssembler`** class in [`coded_tools/agent_network_designer/deployable_agent_network_assembler.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_designer/deployable_agent_network_assembler.py) extends the generic `AgentNetworkAssembler` to load and inject AAOSA definitions. During initialization (lines 49-51), it loads the AAOSA definitions into `self.aaosa_defs`.

When assembling a network via `assemble_agent_network`, the `filter_agent` method prepares two replacement dictionaries:

```python
string_replacements: dict[str, str] = {
    "aaosa_command": self.aaosa_defs.get("aaosa_command"),
    "aaosa_instructions": self.aaosa_defs.get("aaosa_instructions"),
}
value_replacements: dict[str, Any] = {
    "aaosa_call": self.aaosa_defs.get("aaosa_call"),
}

```

These maps are processed by **CommonDefs** filters from the `neuro_san` package (`StringCommonDefsConfigFilter` and `DictionaryCommonDefsConfigFilter`), which perform search-and-replace operations on the in-memory agent specifications. This effectively injects the AAOSA instructions, function description, and command template into each agent's configuration.

> Source: [`DeployableAgentNetworkAssembler`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_designer/deployable_agent_network_assembler.py)

### The Template Layer: HOCON Assemblers and Constants

For developers working with text-based configurations, the **`HoconAgentNetworkAssembler`** in [`coded_tools/agent_network_designer/hocon_agent_network_assembler.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_designer/hocon_agent_network_assembler.py) provides template strings containing placeholders like `${aaosa_instructions}`, `${aaosa_call}`, and `${aaosa_command}`. These templates explicitly include the AAOSA registry via `include "registries/aaosa.hocon"`, allowing the HOCON renderer to substitute values during file generation.

Additionally, [`apps/wwaw/hocon_constants.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/apps/wwaw/hocon_constants.py) provides pre-packaged HOCON snippets via the **`HOCON_TEMPLATES`** dictionary, enabling quick copy-paste integration of AAOSA-enabled blocks into custom network files.

> Source: [`hocon_agent_network_assembler`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_designer/hocon_agent_network_assembler.py)  
> Source: [`wwaw/hocon_constants`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/apps/wwaw/hocon_constants.py)

## End-to-End Implementation Workflow

To implement the AAOSA protocol in your agent network, follow this execution flow:

1. **Define or modify your network** using either Python dictionaries or HOCON configuration files.
2. **Instantiate** `DeployableAgentNetworkAssembler(demo_mode=False)` to load the AAOSA definitions into memory.
3. **Invoke** `assemble_agent_network(network_def, top_agent_name, network_name, sample_queries)` to process the network.
4. **Filter each agent** through `filter_agent`, which merges AAOSA strings and values into agent-specific replacement dictionaries.
5. **Apply CommonDefs filters** to inject `aaosa_instructions` into each agent's `instructions` field, `aaosa_call` under `tools`, and `aaosa_command` as the response template.
6. **Deploy the network**, where agents follow the AAOSA flow: **Determine** relevance (signaling `Relevant`/`Strength`), **Call** downstream agents as needed, and **Fulfill** or **Follow up** with JSON responses matching the `aaosa_command` template.

## Practical Code Examples

### Loading AAOSA Definitions Programmatically

Import the assembler and inspect the loaded policy definitions:

```python
from coded_tools.agent_network_designer.deployable_agent_network_assembler import DeployableAgentNetworkAssembler

assembler = DeployableAgentNetworkAssembler(demo_mode=False)
print(assembler.aaosa_defs["aaosa_instructions"][:120])  # Preview first 120 characters

```

> Source: [`DeployableAgentNetworkAssembler.__init__`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_designer/deployable_agent_network_assembler.py#L35-L51)

### Assembling a Network with AAOSA Injection

Create a network dictionary and process it through the assembler to inject AAOSA capabilities:

```python
network_def = {
    "top_agent": {"tools": ["search_tool"], "instructions": "Handle user queries."},
    "sub_agent": {"tools": ["summarizer"], "instructions": "Summarize documents."},
}

assembled = assembler.assemble_agent_network(
    network_def,
    top_agent_name="top_agent",
    agent_network_name="my_network",
    sample_queries=["What is the weather today?"],
)

# Verify AAOSA instructions were injected

print(assembled["tools"][0]["instructions"])  # Contains aaosa_instructions text

```

> Source: [`DeployableAgentNetworkAssembler.assemble_agent_network`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_designer/deployable_agent_network_assembler.py#L54-L84)

### HOCON Template with AAOSA Placeholders

Reference the AAOSA registry directly in your HOCON configuration files:

```hocon
include "registries/aaosa.hocon"

agent "top_agent" {
    description "Top level agent"
    instructions ${aaosa_instructions}
    function ${aaosa_call}
    command ${aaosa_command}
}

```

> Source: [`hocon_agent_network_assembler` template](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_designer/hocon_agent_network_assembler.py#L27-L36)

### Quick Integration Using WWAW Constants

Access pre-formatted HOCON blocks for rapid implementation:

```python
from apps.wwaw.hocon_constants import HOCON_TEMPLATES

print(HOCON_TEMPLATES["aaosa_instructions"])  # Ready-to-paste HOCON block

```

> Source: [[`apps/wwaw/hocon_constants.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/apps/wwaw/hocon_constants.py)](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/apps/wwaw/hocon_constants.py#L38-L80)

## Key Files in the AAOSA Implementation

The protocol implementation spans several critical files:

- **`registries/aaosa.hocon`**: Central data store for `aaosa_instructions`, function schema, and command templates.
- **[`coded_tools/agent_network_designer/deployable_agent_network_assembler.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_designer/deployable_agent_network_assembler.py)**: Loads AAOSA definitions and injects them via CommonDefs filters during in-memory assembly.
- **[`coded_tools/agent_network_designer/hocon_agent_network_assembler.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_designer/hocon_agent_network_assembler.py)**: Generates HOCON text with AAOSA placeholders for file-based network definitions.
- **[`apps/wwaw/hocon_constants.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/apps/wwaw/hocon_constants.py)**: Pre-packaged HOCON snippets for quick AAOSA integration.
- **[`coded_tools/get_agent_network_definition.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/get_agent_network_definition.py)**: Utility for extracting core network definitions while stripping AAOSA-specific instructions.

## Summary

- The **AAOSA protocol** is defined as pure data in `registries/aaosa.hocon`, enabling protocol consistency across all agents.
- **`DeployableAgentNetworkAssembler`** automates injection using **CommonDefs filters** from the `neuro_san` package, processing both string and dictionary replacements.
- Three core substitution keys drive adaptive behavior: `aaosa_instructions` (policy), `aaosa_call` (delegation interface), and `aaosa_command` (response structure).
- Developers can implement the protocol **programmatically** via Python dictionaries or **declaratively** through HOCON templates that include the AAOSA registry.
- The protocol supports three operational modes—**Determine**, **Fulfill**, and **Follow up**—that enable autonomous agent orchestration and relevance assessment.

## Frequently Asked Questions

### What is the AAOSA protocol and how does it enable adaptive agent communication?

The AAOSA (Adaptive Agent Orchestration and Sub-Agent) protocol is a standardized framework that allows agents to dynamically determine whether they should handle a request, delegate to sub-agents, or seek clarification. According to the `cognizant-ai-lab/neuro-san-studio` source code, it implements adaptive agent communication by providing structured instruction templates (`aaosa_instructions`), function definitions (`aaosa_call`), and command formats (`aaosa_command`) that all agents in a network use to coordinate autonomously.

### How does the DeployableAgentNetworkAssembler inject AAOSA definitions into agent specifications?

The assembler loads AAOSA definitions during initialization (lines 49-51 of [`deployable_agent_network_assembler.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/deployable_agent_network_assembler.py)) and stores them in `self.aaosa_defs`. During the `assemble_agent_network` process, the `filter_agent` method creates replacement dictionaries for both strings (`aaosa_instructions`, `aaosa_command`) and values (`aaosa_call`). These are processed by `StringCommonDefsConfigFilter` and `DictionaryCommonDefsConfigFilter` from the `neuro_san` package, which perform search-and-replace operations on the in-memory agent specifications before deployment.

### Can I implement the AAOSA protocol in existing HOCON-based agent networks?

Yes. You can implement the AAOSA protocol in HOCON-based networks by including `registries/aaosa.hocon` in your configuration and using placeholders like `${aaosa_instructions}`, `${aaosa_call}`, and `${aaosa_command}` in your agent definitions. Alternatively, import `HOCON_TEMPLATES` from `apps.wwaw.hocon_constants` to access pre-formatted AAOSA blocks that can be pasted directly into existing network files.

### What are the three operational modes defined in the AAOSA command structure?

The AAOSA command template defines three operational modes that guide agent behavior: **Determine** (assess relevance and signal strength via `Relevant`/`Strength` fields), **Call** (invoke downstream agents as needed), and **Fulfill/Follow up** (return a final JSON response or request clarification). These modes are embedded in the `aaosa_command` template stored in `registries/aaosa.hocon` and injected into each agent's response format during network assembly.