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

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:

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

# 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, 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:

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.

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