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

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
GetToolbox coded tool	Exposes the toolbox catalog to agents as a LangChain tool for runtime discovery.	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.

# 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.

# 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.

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

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

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

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

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:

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

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

{
    "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
coded_tools/agent_network_editor/get_toolbox.py	Coded tool exposing the toolbox catalog for runtime queries.	View on GitHub
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
run.py	CLI entry point that initializes the toolbox via AGENT_TOOLBOX_INFO_FILE.	View on GitHub
docs/toolbox.md	Human-readable documentation of default available tools.	View on GitHub

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, 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). 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.

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