How to Implement the AAOSA Protocol for Adaptive Agent Communication

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

The Assembler Layer: DeployableAgentNetworkAssembler

The DeployableAgentNetworkAssembler class in 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:

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

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 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 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
Source: wwaw/hocon_constants

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:

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__

Assembling a Network with AAOSA Injection

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

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

HOCON Template with AAOSA Placeholders

Reference the AAOSA registry directly in your HOCON configuration files:

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

Quick Integration Using WWAW Constants

Access pre-formatted HOCON blocks for rapid implementation:

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#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: Loads AAOSA definitions and injects them via CommonDefs filters during in-memory assembly.
• 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: Pre-packaged HOCON snippets for quick AAOSA integration.
• 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}