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

> Organize agent networks in Neuro-SAN Studio by placing HOCON files in registries and updating manifest.hocon. Discover how FileSystemAgentNetworkPersistor streamlines this process.

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

---

**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:

```hocon
{
    "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:

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

```

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

```diff
--- 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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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:

```python
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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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.