# How to Use the Toolbox System for LangChain and Custom Tools in Neuro SAN Studio

> Discover how to leverage the Neuro SAN Studio toolbox system to integrate LangChain and custom tools. Map tool names to classes effortlessly using HOCON for powerful agent network definitions.

- 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 Neuro SAN Studio toolbox system maps tool names to LangChain tool classes via a HOCON configuration file, allowing agents to reference pre-built or custom tools by name in their network definitions.**

Neuro SAN Studio provides a centralized **Toolbox** catalog that bridges declarative agent configuration with LangChain tool execution. The system uses a HOCON file at `toolbox/toolbox_info.hocon` to register both built-in LangChain integrations and custom-coded tools, enabling dynamic tool injection into agent networks at runtime.

## Architecture of the Toolbox System for LangChain Integration

The toolbox architecture separates tool definition from tool consumption, allowing developers to register capabilities once and reuse them across multiple agent networks.

### Core Components

| Component | Role | Key Source |
|---|---|---|
| **Toolbox definition** | Stores the catalog mapping tool names to classes, descriptions, and JSON schemas. | `toolbox/toolbox_info.hocon` |
| **ToolboxInfoRestorer** | Parses the HOCON file and builds a Python dictionary of tool specifications at startup. | [`neuro_san/internals/run_context/langchain/toolbox/toolbox_info_restorer.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/neuro_san/internals/run_context/langchain/toolbox/toolbox_info_restorer.py) |
| **GetToolbox coded tool** | Exposes the toolbox catalog to agents as a LangChain tool for runtime discovery. | [`coded_tools/agent_network_editor/get_toolbox.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_editor/get_toolbox.py) |
| **Agent network HOCON** | Declares agents and references toolbox entries by name in the `toolbox` field. | `*.hocon` network definitions |
| **LangChain integration** | Creates tool instances and registers them with the LangChain `AgentExecutor` when agents are instantiated. | Internal to `neuro_san/internals/run_context/langchain/` |

### Runtime Flow

1. **Startup** – Neuro SAN reads the environment variable `AGENT_TOOLBOX_INFO_FILE` (defaults to `toolbox/toolbox_info.hocon`).
2. **Restoration** – `ToolboxInfoRestorer().restore(file_path)` parses the HOCON and returns a dictionary mapping tool names to specifications.
3. **Agent creation** – If an agent's HOCON contains `"toolbox": "my_tool"`, Neuro SAN looks up the class path, imports it, and instantiates the tool.
4. **Execution** – The agent invokes the tool through standard LangChain tool-calling mechanisms.
5. **Discovery** – Agents can call the `GetToolbox` tool to retrieve the catalog dynamically.

## How to Add Custom Tools to the Toolbox

Adding a custom tool requires implementing a LangChain-compatible class and registering it in the toolbox HOCON file.

### Step 1: Implement the LangChain Tool Class

Create a Python class that inherits from `BaseTool` or uses the `@tool` decorator. Place the file under `coded_tools/tools/` or any importable package.

```python

# coded_tools/tools/my_custom_tool.py

from langchain_core.tools import BaseTool
from pydantic import BaseModel

class MyCustomToolInput(BaseModel):
    query: str

class MyCustomTool(BaseTool):
    """Example custom tool that echoes the query."""
    name = "my_custom_tool"
    description = "Echoes the provided query back to the caller."
    args_schema = MyCustomToolInput

    def _run(self, query: str) -> str:
        return f"Echo: {query}"

```

### Step 2: Register in toolbox_info.hocon

Append a new entry to `toolbox/toolbox_info.hocon` using the JSON-schema-style parameter definition.

```hocon

# toolbox/toolbox_info.hocon

"my_custom_tool": {
    "class": "tools.my_custom_tool.MyCustomTool",
    "description": "Echoes the provided query back to the caller.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Text to be echoed."
            }
        },
        "required": ["query"]
    }
}

```

### Step 3: Reference in Agent Network Configuration

Create or edit an agent-network HOCON file to reference the tool by name.

```hocon
{
    "agents": [
        {
            "name": "echo_agent",
            "toolbox": "my_custom_tool",
            "system_prompt": "You are a helpful echo bot."
        }
    ]
}

```

When Neuro SAN loads this network, the `echo_agent` will have the `my_custom_tool` available in its LangChain toolset.

## Querying the Toolbox at Runtime with GetToolbox

The built-in `GetToolbox` coded tool exposes the toolbox catalog to agents, enabling dynamic discovery of available capabilities.

### Configuration

Add the `get_toolbox` entry to an agent's toolbox field:

```hocon
{
    "agents": [
        {
            "name": "inspector",
            "toolbox": "get_toolbox",
            "system_prompt": "You can ask me about available tools."
        }
    ]
}

```

### Programmatic Usage

Agents or external scripts can invoke the runner to query the toolbox:

```python
from neuro_san.internals.run_context.langchain.runner import NeuroSanRunner

# Load a network containing the GetToolbox tool

runner = NeuroSanRunner(network_path="examples/inspect_toolbox.hocon")
response = runner.invoke(
    agent_name="inspector",
    user_input="What tools are available?"
)
print(response)  # Returns dict of tool names and descriptions

```

The `GetToolbox` implementation in [`coded_tools/agent_network_editor/get_toolbox.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_editor/get_toolbox.py) internally calls `ToolboxInfoRestorer` to parse the HOCON file and return the tool specifications.

## Practical Code Examples

### Using Built-in Google Search

Reference the pre-configured `google_search` tool in your agent network:

```hocon
{
    "agents": [
        {
            "name": "searcher",
            "toolbox": "google_search",
            "system_prompt": "Answer questions using up-to-date web results."
        }
    ]
}

```

```python
from neuro_san.internals.run_context.langchain.runner import NeuroSanRunner

runner = NeuroSanRunner(network_path="search_network.hocon")
answer = runner.invoke(
    agent_name="searcher", 
    user_input="Who won the Nobel Prize in Physics 2023?"
)
print(answer)  # LLM invokes google_search tool internally

```

### Creating a Custom Image Generation Tool

Implement a tool that generates images from text prompts:

```python

# coded_tools/tools/my_image_gen.py

from langchain_core.tools import BaseTool
from pydantic import BaseModel

class ImgGenInput(BaseModel):
    prompt: str

class MyImageGenTool(BaseTool):
    name = "my_image_gen"
    description = "Generates an image from a textual prompt using a custom model."
    args_schema = ImgGenInput

    def _run(self, prompt: str) -> str:
        # Placeholder - real implementation calls model API

        return f"https://example.com/generated_image?prompt={prompt!r}"

```

Register in `toolbox/toolbox_info.hocon`:

```hocon
"my_image_gen": {
    "class": "tools.my_image_gen.MyImageGenTool",
    "description": "Generates an image from a textual prompt using a custom model.",
    "parameters": {
        "type": "object",
        "properties": {
            "prompt": {
                "type": "string",
                "description": "The text prompt describing the desired image."
            }
        },
        "required": ["prompt"]
    }
}

```

Use in agent configuration:

```hocon
{
    "agents": [
        {
            "name": "designer",
            "toolbox": "my_image_gen",
            "system_prompt": "Design creative illustrations for user requests."
        }
    ]
}

```

## Key Files for Toolbox Management

| File | Purpose | Direct Link |
|---|---|---|
| `toolbox/toolbox_info.hocon` | Central catalog mapping tool names to classes, descriptions, and JSON schemas. | [View on GitHub](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/toolbox/toolbox_info.hocon) |
| [`coded_tools/agent_network_editor/get_toolbox.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_editor/get_toolbox.py) | Coded tool exposing the toolbox catalog for runtime queries. | [View on GitHub](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_editor/get_toolbox.py) |
| [`neuro_san/internals/run_context/langchain/toolbox/toolbox_info_restorer.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/neuro_san/internals/run_context/langchain/toolbox/toolbox_info_restorer.py) | Internal parser that converts HOCON definitions to Python dictionaries. | Internal implementation |
| `coded_tools/tools/*.py` | Example tool implementations (e.g., Google Search, Wikipedia RAG). | [View folder](https://github.com/cognizant-ai-lab/neuro-san-studio/tree/main/coded_tools/tools) |
| [`run.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/run.py) | CLI entry point that initializes the toolbox via `AGENT_TOOLBOX_INFO_FILE`. | [View on GitHub](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/run.py) |
| [`docs/toolbox.md`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/docs/toolbox.md) | Human-readable documentation of default available tools. | [View on GitHub](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/docs/toolbox.md) |

## Summary

- The **Toolbox** is a declarative HOCON catalog that maps tool names to LangChain-compatible Python classes, stored in `toolbox/toolbox_info.hocon`.
- Agents reference toolbox tools by setting the `"toolbox"` field to the tool name in their HOCON network configuration.
- The **ToolboxInfoRestorer** parses the catalog at startup, while the **GetToolbox** coded tool enables runtime discovery of available capabilities.
- Adding custom tools requires implementing a LangChain `BaseTool` subclass and registering it in the toolbox HOCON file with a JSON schema for parameters.

## Frequently Asked Questions

### How do I reference a toolbox tool in an agent network HOCON file?

Set the `"toolbox"` field to the tool name as defined in `toolbox/toolbox_info.hocon`. For example, to use a custom tool named `my_custom_tool`, configure the agent as `{"name": "my_agent", "toolbox": "my_custom_tool", "system_prompt": "..."}`. The framework automatically instantiates the corresponding LangChain class when the network loads.

### What is the difference between built-in LangChain tools and custom-coded tools in Neuro SAN Studio?

Built-in tools are pre-implemented classes (such as Google Search or Wikipedia RAG) already registered in `toolbox/toolbox_info.hocon`. Custom-coded tools are Python classes you implement yourself, typically inheriting from LangChain's `BaseTool`, and then register in the same HOCON file. Both types are loaded identically by the `ToolboxInfoRestorer` and injected into agents via the same `"toolbox"` reference mechanism.

### How does the ToolboxInfoRestorer load tool definitions?

The `ToolboxInfoRestorer` class, located in [`neuro_san/internals/run_context/langchain/toolbox/toolbox_info_restorer.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/neuro_san/internals/run_context/langchain/toolbox/toolbox_info_restorer.py), reads the file path specified by the `AGENT_TOOLBOX_INFO_FILE` environment variable (defaulting to `toolbox/toolbox_info.hocon`). It parses the HOCON structure into a Python dictionary mapping tool names to their specifications, including the importable class path, description, and JSON schema parameters.

### Can I query available tools dynamically during agent execution?

Yes. Neuro SAN Studio includes a built-in coded tool called `GetToolbox` (implemented in [`coded_tools/agent_network_editor/get_toolbox.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_editor/get_toolbox.py)). By adding `"toolbox": "get_toolbox"` to an agent's configuration, you enable that agent to invoke the tool and retrieve the complete catalog of available tools, including descriptions and parameter schemas, at runtime. This supports self-reflective agents that adapt their behavior based on available capabilities.