How to Use the Agent Network Designer to Generate Agent Networks from Natural Language

The Agent Network Designer is a meta-agent that converts plain-language business descriptions into fully configured multi-agent systems by orchestrating sub-networks and persisting the result as HOCON configuration files.

The Agent Network Designer in the cognizant-ai-lab/neuro-san-studio repository enables developers to bootstrap complex agent networks without manual configuration. By submitting natural language descriptions—such as "create a network for UNHCR back-office operations"—the system automatically generates the graph structure, agent instructions, and sample queries, then persists everything to registries/generated/ and updates manifest.hocon.

Architecture of the Agent Network Designer

The Agent Network Designer operates as a front-man agent that delegates specialized tasks to dedicated sub-networks. This modular architecture separates concerns between graph construction, instruction generation, and persistence.

Front-Man Agent and Workflow Orchestration

The entry point is defined in registries/agent_network_designer.hocon. This front-man receives the user's natural language request and executes a loopable workflow that can iterate until the network structure stabilizes. The workflow coordinates five sequential phases: loading the current state, editing the graph structure, refining instructions, generating sample queries, and persisting the final configuration.

Sub-Network Components

Each specialized task is handled by a dedicated sub-network:

• agent_network_editor – Creates or modifies the agent graph (nodes, tools, up-chain/down-chain relationships). Defined in registries/agent_network_editor.hocon.
• agent_network_instructions_editor – Generates role-specific instructions for each agent based on the current graph structure. Defined in registries/agent_network_instructions_editor.hocon.
• agent_network_query_generator – Produces 3-4 realistic sample queries that demonstrate how the new network handles user requests. Defined in registries/agent_network_query_generator.hocon.

Persistence Layer

The persist_agent_network coded tool (implemented in coded_tools/agent_network_designer/persist_agent_network.py) handles the final serialization. This tool:

1. Validates the in-memory agent_network_definition structure
2. Assembles the final HOCON via hocon_agent_network_assembler.py
3. Writes the file to registries/generated/ using file_system_agent_network_persistor.py
4. Updates manifest.hocon to register the new network

Step-by-Step Workflow

When you submit a natural language request, the Agent Network Designer executes the following sequence:

1. Load current state – Calls get_agent_network_definition (with an optional existing HOCON file if modifying a prior network).
2. Structure creation – Invokes agent_network_editor to build the agent graph.
3. Instruction generation – Invokes agent_network_instructions_editor to populate agent prompts.
4. Sample query generation – Invokes agent_network_query_generator to create usage examples.
5. Persist – Calls persist_agent_network to write the HOCON file and update the manifest.

Steps 2-4 repeat in a loop until the network definition converges, allowing iterative refinement without manual intervention.

Generating Agent Networks from Natural Language

The conversion process demonstrates how the system bridges human intent and machine configuration. Consider the request: "Create a network for UNHCR back-office operations."

The front-man agent first optionally calls web_search (configured in registries/agent_network_designer.hocon) to gather domain context about UNHCR operations. It then passes this context to the sub-networks:

• The editor creates agents like back_office_manager, finance_officer, and hr_officer with appropriate tool bindings.
• The instructions editor generates role-specific prompts (e.g., procurement procedures for the finance officer).
• The query generator produces examples like "How many refugees are currently in the camp?" and "Generate a weekly procurement plan for medical supplies."

Finally, persist_agent_network serializes this structure to registries/generated/unhcr_back_office.hocon and registers it in manifest.hocon, making the network immediately runnable by the Neuro-SAN runtime.

Code Examples

Submitting a Creation Request

Send a JSON payload to the agent_network_designer agent to bootstrap a new network:

{
  "agent": "agent_network_designer",
  "function": {
    "name": "agent_network_designer",
    "arguments": {
      "agent_network_description": "Create a network for UNHCR back-office operations",
      "mode": "create"
    }
  }
}

The front-man interprets this request, executes the looped workflow, and returns the persisted definition along with generated sample queries.

Inspecting Intermediate State

Use the get_agent_network_definition tool to debug the current graph during generation:

# Python pseudo-code using the Neuro-SAN client library

response = client.call_tool(
    "get_agent_network_definition",
    {"agent_network_hocon_file": None}  # None starts from empty state

)
print(response["agent_network_definition"])

This call can be inserted between workflow steps to verify agent relationships before persistence.

Modifying an Existing Network

To update a previously generated network, specify the existing file and use mode: modify:

{
  "agent": "agent_network_designer",
  "function": {
    "name": "agent_network_designer",
    "arguments": {
      "agent_network_description": "Add a new 'emergency_response' agent to the UNHCR network",
      "mode": "modify",
      "agent_network_hocon_file": "registries/generated/unhcr_back_office.hocon"
    }
  }
}

The front-man loads the existing definition, invokes the editor to add the node, regenerates instructions and queries, and persists the updated file.

Direct Persistence (Advanced)

While normally handled automatically, you can invoke the persistor directly for custom serialization:

from coded_tools.agent_network_designer.persist_agent_network import PersistAgentNetwork

persist = PersistAgentNetwork()
persist.run({
    "sample_queries": [
        "How many refugees are currently in the camp?",
        "Generate a weekly procurement plan for medical supplies."
    ]
})

This tool validates the in-memory agent_network_definition, assembles the final HOCON via hocon_agent_network_assembler.py, writes to registries/generated/ using file_system_agent_network_persistor.py, and updates manifest.hocon.

Key Files and Implementation Details

Understanding the source structure helps when debugging or extending the Agent Network Designer:

• registries/agent_network_designer.hocon – Defines the front-man agent, workflow steps, and available tools including the optional web_search integration.
• registries/agent_network_editor.hocon – Sub-network responsible for graph construction and agent relationship management.
• registries/agent_network_instructions_editor.hocon – Sub-network that generates role-specific instructions for each agent in the graph.
• registries/agent_network_query_generator.hocon – Sub-network that creates realistic sample queries demonstrating network usage.
• coded_tools/agent_network_designer/persist_agent_network.py – Implements the persist_agent_network tool that orchestrates final serialization.
• coded_tools/agent_network_designer/file_system_agent_network_persistor.py – Handles filesystem operations for writing generated HOCON files and updating manifest.hocon.
• coded_tools/agent_network_designer/hocon_agent_network_assembler.py – Assembles the in-memory definition into valid HOCON syntax before persistence.

Summary

• The Agent Network Designer is a meta-agent in cognizant-ai-lab/neuro-san-studio that converts natural language descriptions into runnable multi-agent configurations.
• It orchestrates four specialized sub-networks: agent_network_editor (graph structure), agent_network_instructions_editor (prompts), agent_network_query_generator (examples), and persist_agent_network (serialization).
• The workflow is loopable, allowing iterative refinement of the agent graph before final persistence to registries/generated/ and automatic registration in manifest.hocon.
• Generated networks are immediately deployable by the Neuro-SAN runtime without manual configuration.

Frequently Asked Questions

What is the difference between "create" and "modify" modes in the Agent Network Designer?

Create mode initializes an empty agent_network_definition and builds a new agent network from scratch based on your natural language description. Modify mode loads an existing HOCON file (specified via agent_network_hocon_file) into the definition, applies your requested changes through the editor sub-network, and persists the updated configuration. Both modes execute the full workflow loop including instruction regeneration and sample query creation.

How does the Agent Network Designer handle domain-specific knowledge?

The front-man agent optionally invokes a web_search tool (configured in registries/agent_network_designer.hocon) to gather public information about the domain mentioned in your request (e.g., UNHCR operations). This context is passed to the agent_network_editor and agent_network_instructions_editor sub-networks, enabling the generation of factually grounded agent roles and specialized instructions without manual research.

Where are the generated agent network files stored?

The persist_agent_network tool (implemented in coded_tools/agent_network_designer/persist_agent_network.py) writes completed configurations to the registries/generated/ directory using file_system_agent_network_persistor.py. Simultaneously, it updates manifest.hocon to register the new network, making it immediately available to the Neuro-SAN runtime without additional configuration steps.

Can I inspect or debug the agent network during generation?

Yes. You can call the get_agent_network_definition tool directly (available in coded_tools/agent_network_designer/persist_agent_network.py) to retrieve the current in-memory state of the agent graph at any point in the workflow. Pass {"agent_network_hocon_file": None} to start from an empty state, or provide a file path to inspect existing configurations before modification.

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