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

> Learn how to use the Agent Network Designer to generate agent networks from natural language. Convert plain language into multi agent systems with this powerful tool.

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

---

**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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/hocon_agent_network_assembler.py)
3. Writes the file to `registries/generated/` using [`file_system_agent_network_persistor.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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:

```json
{
  "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

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

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

```python
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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/hocon_agent_network_assembler.py), writes to `registries/generated/` using [`file_system_agent_network_persistor.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_designer/persist_agent_network.py)) writes completed configurations to the `registries/generated/` directory using [`file_system_agent_network_persistor.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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.