How to Configure Tool Arguments Override in Agent Network Config in Neuro-San Studio

You configure tool arguments override in Neuro-San Studio by adding a tool_args block to the tool definition in your agent network HOCON file, which merges with the toolbox defaults at runtime.

Neuro-San Studio uses HOCON configuration files to define agent networks and their available tools. When you need to customize tool behavior for specific agents without modifying global defaults, you configure tool arguments override in the agent network config files located in the registries/ directory. This approach allows you to maintain reusable toolbox definitions while tailoring parameters for individual agent interactions.

Default Tool Arguments in the Toolbox

Before configuring overrides, you must understand how default tool arguments are structured. In the cognizant-ai-lab/neuro-san-studio repository, each tool available to agents is defined in a toolbox HOCON file such as toolbox/agent_network_designer_toolbox_info.hocon. These files contain a tool_args map that specifies the default parameters passed to the tool during execution.

Structure of Toolbox tool_args

The toolbox entry defines the tool class and its default arguments:

tool {
  name = "search_google"
  class = "cognify.google_search.GoogleSearchTool"
  tool_args = {
    api_key = "YOUR_DEFAULT_KEY"
    num_results = 5
    safe_search = true
  }
}

These values serve as the baseline configuration whenever an agent invokes this tool.

Override Tool Arguments in Agent Network Configurations

To customize tool behavior for a specific agent, you add a tool_args block within the tool definition in your network configuration file (e.g., registries/example_agent_network.hocon). This enables you to configure tool arguments override in agent network config files without altering the global toolbox definition.

Adding tool_args to Network HOCON

Reference the tool by name and supply the override values:

agents {
  web_assistant {
    tools = [
      {
        name = "search_google"
        tool_args = {
          # Override only the parameter you need

          num_results = 20
        }
      }
    ]
  }
}

In this example, num_results becomes 20 while api_key and safe_search retain their default values from the toolbox.

Merge Behavior and Precedence

During runtime, the framework merges the toolbox defaults with the per-agent overrides using dictionary unpacking. The override values replace defaults, while omitted keys preserve their original values. According to the source code, the merge logic follows this pattern:

# Simplified merge logic from the tool-calling path

override_args = tool_config.get("tool_args", {})
merged_args = {**default_tool_args, **override_args}
await agent_caller.call_agent(tool_args=merged_args, sly_data=sly_data)

The resulting argument map passed to the tool at execution time would be:

{
  "api_key": "YOUR_DEFAULT_KEY",
  "num_results": 20,
  "safe_search": true
}

Runtime Implementation in call_agent.py

The actual extraction and forwarding of tool arguments occurs in coded_tools/tools/call_agent.py. Lines 64-73 of this file handle retrieving the tool_args from the configuration and passing them to the agent caller:

# coded_tools/tools/call_agent.py

def tool(self, args):
    # ...

    tool_args: Dict[str, Any] = args.get("tool_args")
    if not tool_args:
        raise ValueError("Error: No tool_args provided.")
    # Log the final args (after merge happens later)

    logger.debug("tool_args: %s", tool_args)
    return await agent_caller.call_agent(tool_args=tool_args, sly_data=sly_data)

The agent_caller (implemented in coded_tools/tools/coded_tool_agent_caller.py) receives these arguments and performs the merge with toolbox defaults before invoking the target tool.

Key Files for Tool Argument Configuration

• toolbox/agent_network_designer_toolbox_info.hocon — Defines default tool_args for each toolbox-provided tool.
• coded_tools/tools/call_agent.py — Extracts tool_args from the network spec and forwards them to the agent caller (see lines 64-73).
• coded_tools/tools/coded_tool_agent_caller.py — Receives the merged tool_args and invokes the target tool.
• registries/*.hocon — Agent network definition files where you place tool_args overrides for specific agents.
• plugins/log_bridge/process_log_bridge.py — Demonstrates a similar pattern for merging configuration dictionaries with overrides.

Summary

• Define defaults in the toolbox HOCON file (toolbox/agent_network_designer_toolbox_info.hocon) using the tool_args map.
• Configure overrides by adding a tool_args block to the tool entry in your agent network HOCON file (e.g., registries/example_agent_network.hocon).
• Merge behavior performs a dictionary update where network-level values replace toolbox defaults, preserving unmodified keys.
• Runtime processing occurs in coded_tools/tools/call_agent.py, which extracts arguments and forwards them to coded_tool_agent_caller.py for execution.

Frequently Asked Questions

What file format does Neuro-San Studio use for configurations?

Neuro-San Studio uses HOCON (Human-Optimized Config Object Notation) files for both toolbox definitions and agent network configurations. This format supports comments, object merging, and inheritance patterns that make it ideal for defining hierarchical tool configurations and overrides.

Can I override multiple tool arguments at once?

Yes. You can override any number of parameters by including them in the tool_args block within your agent network configuration. Only the keys you specify will replace the defaults; all other parameters from the toolbox tool_args will remain unchanged in the merged dictionary passed to the tool.

What happens if I don't specify tool_args in the network config?

If you omit the tool_args block in the network configuration, the tool will execute using only the default values defined in the toolbox HOCON file. The merge logic defaults to an empty dictionary for overrides, resulting in {**default_tool_args, **{}}, which preserves all original defaults.

Where is the merge logic implemented in the source code?

The merge logic is implemented in the tool-calling path within the Neuro-San Studio framework, specifically in coded_tools/tools/call_agent.py where arguments are extracted (lines 64-73), and subsequently in coded_tools/tools/coded_tool_agent_caller.py where the dictionary merge occurs before invoking the target tool. A similar configuration merging pattern is also demonstrated in plugins/log_bridge/process_log_bridge.py.

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