How to Organize and Reorganize Agent Networks in Neuro-SAN Studio

You organize agent networks in Neuro-SAN Studio by arranging HOCON definition files within the registries/ directory and updating the manifest.hocon file to reflect the relative paths, while the FileSystemAgentNetworkPersistor utility automates both file placement and manifest synchronization.

The cognizant-ai-lab/neuro-san-studio repository uses a declarative approach to manage agent networks, where every network is defined as a HOCON file. To effectively organize and reorganize agent networks, you must understand how the server discovers these definitions through the registry structure and manifest file, and how programmatic tools can enforce consistency when moving or creating networks.

Understanding the Agent Network Registry Structure

The registries/ Directory

All agent network definitions live in the registries/ directory at the repository root. This folder serves as the single source of truth for available networks. You can create subfolders to logically group related networks, such as registries/industry/ for domain-specific agents or registries/experimental/ for prototypes.

The server resolves network paths relative to this root. For example, a file located at registries/basic/music_nerd.hocon is referenced in the manifest as "basic/music_nerd.hocon".

The manifest.hocon File

The registries/manifest.hocon file acts as the master index that tells the server which networks to load. Each entry maps a relative path (from registries/) to a boolean flag:

{
    "basic/music_nerd.hocon": true,
    "industry/airline_policy/airline_policy.hocon": true,
    "experimental/kwik_agent.hocon": false
}

Only entries set to true are loaded. If you move a HOCON file without updating this manifest, the server will fail to locate the network or load an outdated definition.

How to Organize Agent Networks with Subfolders

To organize and reorganize agent networks effectively, use subfolders to create logical boundaries:

1. Group by domain – Create folders like registries/industry/banking/ or registries/industry/healthcare/ to isolate domain-specific logic.
2. Separate by maturity – Use registries/production/ for stable networks and registries/experimental/ for work-in-progress agents.
3. Name files meaningfully – The filename (minus .hocon) becomes the network identifier in logs and tooling.

Example structure:

registries/
├── manifest.hocon
├── basic/
│   ├── music_nerd.hocon
│   └── advanced_calculator.hocon
├── industry/
│   ├── airline_policy/
│   │   └── airline_policy.hocon
│   └── banking_ops/
│       └── banking_ops.hocon
└── experimental/
    └── kwik_agent.hocon

How to Reorganize and Move Agent Networks

When you reorganize agent networks by moving files, you must synchronize the manifest to prevent loading errors.

Manual Reorganization Steps

1. Move the HOCON file using your filesystem or version control:

mv registries/basic/advanced_calculator.hocon registries/industry/calculator/advanced_calculator.hocon

2. Update the manifest entry to reflect the new relative path:

--- a/registries/manifest.hocon
+++ b/registries/manifest.hocon
@@
-    "basic/advanced_calculator.hocon": true,
+    "industry/calculator/advanced_calculator.hocon": true,

Using FileSystemAgentNetworkPersistor for Automated Reorganization

The FileSystemAgentNetworkPersistor class in coded_tools/agent_network_designer/file_system_agent_network_persistor.py automates the process of writing network files and updating the manifest. When you instantiate the persistor with a new path, it handles both file placement and manifest synchronization:

from coded_tools.agent_network_designer.file_system_agent_network_persistor import (
    FileSystemAgentNetworkPersistor,
)

persistor = FileSystemAgentNetworkPersistor(
    output_path="registries",
    generated_dir="generated",
    agent_network_name="industry/calculator/new_calc",  # Subfolder path

    hocon_content=my_hocon_string,
)

await persistor.persist()

The persistor checks for existing entries to prevent duplicates (if f'"{the_agent_network_name}.hocon"' in manifest_content) and atomically updates registries/manifest.hocon with the correct relative path.

Programmatically Managing Network Organization

For large-scale reorganization, the apps/wwaw/build_wwaw.py example demonstrates how to generate extensive agent networks and ensure they are properly registered. This "world-wide-agentic-web" app creates network definitions and uses the persistor to place them in subfolders while maintaining manifest integrity.

When organizing networks programmatically:

1. Define the folder structure in your generation script
2. Use FileSystemAgentNetworkPersistor with paths containing subfolders (e.g., "industry/banking/fraud_detection")
3. Commit both the new HOCON files and the updated manifest.hocon to version control

Summary

• Store definitions in registries/ using HOCON format, with subfolders for logical grouping.
• Control loading via registries/manifest.hocon, where each key is the relative path from registries/ to the HOCON file.
• Move files by updating both the filesystem location and the manifest entry to prevent server errors.
• Automate organization using FileSystemAgentNetworkPersistor in coded_tools/agent_network_designer/file_system_agent_network_persistor.py to handle file placement and manifest updates atomically.
• Version control the entire registries/ directory to track organizational changes alongside code.

Frequently Asked Questions

What happens if I move a HOCON file without updating the manifest?

The server will fail to locate the agent network at startup. Because the manifest entry still points to the old relative path, the system cannot resolve the network definition, resulting in a loading error or the network being unavailable for invocation.

Can I nest subfolders multiple levels deep in registries/?

Yes. The manifest uses the relative path from registries/, so you can create structures like registries/industry/banking/fraud/detection.hocon. The server resolves the full path correctly as long as the manifest key matches the actual file location.

How does the FileSystemAgentNetworkPersistor prevent duplicate manifest entries?

The persistor checks the existing content of manifest.hocon for the specific network filename string before appending. If the entry already exists (even under a different path), it skips the update to prevent duplicate keys that would cause HOCON parsing errors.

Should I commit the manifest.hocon changes to version control?

Yes. The manifest is the authoritative index of available networks. When you organize or reorganize agent networks, commit both the moved HOCON files and the updated manifest to ensure that deployments and other developers have the correct network configuration.

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