# How to Create and Configure Agent Networks Using HOCON Files in Neuro-San Studio

> Learn to create and configure agent networks with HOCON files in Neuro-San Studio. Orchestrate workflows with agent_network_designer for efficient agent network management.

- 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 create and configure agent networks in Neuro-San Studio by authoring a `.hocon` file in the `registries/` directory that includes the shared `llm_config.hocon`, defines an `agent_network_designer` tool to orchestrate the workflow, and references supporting tools like `agent_network_editor` and `persist_agent_network`; the designer automatically loops through network creation, instruction refinement, query generation, and persistence.**

Neuro-San Studio enables rapid prototyping of multi-agent systems through declarative configuration files written in **HOCON** (Human-Optimized Config Object Notation). This approach allows you to define complex agent networks, their interconnections, and behaviors without writing procedural code. In this guide, you'll learn how to leverage the repository's built-in designer tools to create and configure agent networks using HOCON files according to the patterns established in `cognizant-ai-lab/neuro-san-studio`.

## Understanding the HOCON-Based Architecture

The architecture relies on specialized tool agents defined in separate HOCON files that collaborate to build your network. Each component serves a distinct purpose in the network construction pipeline.

### Core Components

- **Agent Network Designer** – The front-end orchestrator defined in `registries/agent_network_designer.hocon` that manages the entire workflow including creation, HTML visualization, testing, and email distribution. It validates requirements and persists the final configuration.

- **Network Editor** – Defined in `registries/agent_network_editor.hocon`, this tool handles adding and removing agents, establishing up-chain and down-chain connections, and attaching toolbox, sub-network, or MCP tools.

- **Instructions Editor** – Located at `registries/agent_network_instructions_editor.hocon`, this component generates or updates the `instructions` field for every non-function agent in the network.

- **Query Generator** – The `registries/agent_network_query_generator.hocon` tool produces 3-4 realistic sample queries that demonstrate the capabilities of the created network.

- **HTML Generator** – A toolbox tool (declared in `toolbox/toolbox_info.hocon` under the `"agent_network_html_generator"` entry) that converts HOCON definitions into interactive HTML graphs using pyvis.

- **Persist Agent Network** – A coded tool embedded within the designer (`persist_agent_network`) that writes the final HOCON file to `registries/` and automatically adds the entry to `registries/manifest.hocon`.

- **LLM Config** – The `registries/llm_config.hocon` file serves as the single source of truth for model parameters, including the model name, temperature, and token limits.

### The Designer Workflow Loop

According to lines 71-76 of `registries/agent_network_designer.hocon`, the designer enforces a strict five-step workflow loop:

1. Load the current network using `get_agent_network_definition`.
2. Create or modify the structure via `agent_network_editor`.
3. Refine agent instructions using `agent_network_instructions_editor`.
4. Generate sample queries with `agent_network_query_generator`.
5. Persist the HOCON using `persist_agent_network`.

This loop iterates until the network satisfies user requirements, after which the designer invokes the HTML generator and optional email sender.

## Prerequisites and Configuration Structure

Before creating your first network, ensure your repository contains the centralized configuration files that serve as the foundation for all agent networks.

The `registries/llm_config.hocon` file acts as the single source of truth for model parameters. Every network HOCON file must include this configuration using the `include "registries/llm_config.hocon"` directive to ensure consistent LLM behavior across the studio. Additionally, the `registries/manifest.hocon` maintains the registry of all available agent networks, which the designer updates automatically when persisting new configurations.

## Step-by-Step Guide to Creating an Agent Network

Follow these steps to build a functional multi-agent system:

1. **Create a new HOCON file** in `registries/` (e.g., `my_network.hocon`).
2. **Add a metadata block** containing a description, tags, and sample queries.
3. **Include the shared LLM config** so the repository uses a single model file.
4. **Define the tool agents** inside the `"tools"` array, with `agent_network_designer` always as the first tool (the front-man).
5. **Write the workflow instructions** in the designer's `instructions` field, customizing the default loop if necessary.
6. **Execute the designer tool** to automatically generate, validate, and persist the network.

## HOCON Configuration Examples

### Minimal Network Definition

The following example creates a two-agent help-desk network with a front-line bot and a specialist agent:

```hocon
{
  "metadata": {
    "description": "Simple help-desk network for a SaaS product",
    "tags": ["helpdesk", "example"],
    "sample_queries": [
      "Reset a forgotten password",
      "Check my subscription status",
      "Escalate a billing issue"
    ]
  },

  // Load the global LLM configuration
  include "registries/llm_config.hocon",

  "max_iterations": 2000,
  "max_execution_seconds": 3000,

  "tools": [
    {
      "name": "agent_network_designer",
      "function": {
        "description": "Designs the help-desk network and persists it",
        "parameters": {
          "type": "object",
          "properties": {
            "agent_network_description": {
              "type": "string",
              "description": "User-provided description of the desired network"
            },
            "mode": {
              "type": "string",
              "description": "`create` for a new network, `modify` for an existing one"
            }
          },
          "required": ["agent_network_description", "mode"]
        }
      },
      "instructions": """
        You are the front-man for building a help-desk network.
        1) Call `agent_network_editor` with mode=create and description:
           {
             "agent_network_description": "A help-desk with a front-line bot and a specialist agent.",
             "mode": "create"
           }
        2) Run `agent_network_instructions_editor` to give each agent clear guidance.
        3) Generate sample queries with `agent_network_query_generator`.
        4) Persist the final HOCON using `persist_agent_network`.
        5) Create an HTML visualisation with `agent_network_html_generator`.
        6) (Optional) Email the files with `email_sender`.
      """
    },

    // The remaining tools are imported from the shared toolbox
    "agent_network_editor",
    "agent_network_instructions_editor",
    "agent_network_query_generator",
    "persist_agent_network",
    "agent_network_html_generator",
    "email_sender"
  ]
}

```

Save this file as `registries/helpdesk_network.hocon`.

### Running the Designer from the CLI

Execute the designer to instantiate your network:

```bash

# Inside the repo root

python -m run --tool /agent_network_designer \
    --input '{"agent_network_description":"Help-desk for SaaS product","mode":"create"}'

```

The command invokes the designer which will create the agents, generate instructions, produce sample queries, write `registries/helpdesk_network.hocon`, generate [`registries/helpdesk_network.html`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/registries/helpdesk_network.html), and optionally email both files if configured.

### Modifying Existing Networks

To add agents to an existing network, use `mode=modify` and specify the target file:

```bash
python -m run --tool /agent_network_designer \
    --input '{"agent_network_description":"Add a FAQ agent","mode":"modify","agent_network_hocon_file":"helpdesk_network.hocon"}'

```

The designer first loads the existing HOCON via `get_agent_network_definition`, then uses the editor to insert the new `faq_agent`, updates instructions, regenerates queries, and persists the updated files.

## Key Files and Their Roles

- **`registries/agent_network_designer.hocon`** – The orchestrator that manages the creation workflow.
- **`registries/agent_network_editor.hocon`** – Handles agent addition, removal, and connection logic.
- **`registries/agent_network_instructions_editor.hocon`** – Generates instructions for each non-function agent.
- **`registries/agent_network_query_generator.hocon`** – Creates sample queries demonstrating network capabilities.
- **`registries/llm_config.hocon`** – Centralized LLM settings included by all networks.
- **`toolbox/toolbox_info.hocon`** – Declares utility tools like `agent_network_html_generator` and `send_gmail_message_with_attachment`.
- **`registries/manifest.hocon`** – Registry of all available agent networks; updated automatically by the designer.

## Summary

- Agent networks in Neuro-San Studio are defined declaratively using HOCON files stored in `registries/`.
- The `agent_network_designer` tool orchestrates a five-step workflow loop (create/edit, instruct, query, validate, persist) as implemented in lines 71-76 of its configuration.
- Include `registries/llm_config.hocon` in every network definition to ensure consistent LLM configuration across the repository.
- Use `mode=create` for new networks and `mode=modify` to update existing HOCON files without starting from scratch.
- The designer automatically generates HTML visualizations using `agent_network_html_generator` and updates `manifest.hocon` upon completion.

## Frequently Asked Questions

### What is the role of the agent_network_designer.hocon file?

The `registries/agent_network_designer.hocon` file defines the front-end orchestrator that manages the entire network creation lifecycle. According to the source code, this tool validates user requirements, invokes the editor and generator sub-agents, and executes the `persist_agent_network` coded tool to write the final configuration to disk and update the manifest.

### How does the workflow loop enforce network creation quality?

The designer enforces a strict sequence defined in lines 71-76 of its HOCON definition: it first loads the current network definition via `get_agent_network_definition`, then modifies the structure through `agent_network_editor`, refines agent instructions via `agent_network_instructions_editor`, generates sample queries with `agent_network_query_generator`, and finally persists the HOCON. This loop repeats until the network satisfies all specified requirements.

### Can I customize the LLM parameters for specific agent networks?

While individual network files can override settings, the recommended practice is to modify the centralized `registries/llm_config.hocon` file, which all network definitions include via the `include` directive. This ensures consistent model behavior across the entire studio while maintaining a single source of truth for temperature, token limits, and model selection.

### How do I visualize the agent network structure after creation?

The designer automatically invokes `agent_network_html_generator` (defined in `toolbox/toolbox_info.hocon`) during the final persistence step. This tool converts the HOCON definition into an interactive HTML graph using pyvis, saving the visualization alongside your configuration file in the `registries/` directory.