How to Configure Domain-Specific Execution Agents (ColliderAgent and COBRApy) in AutoResearchClaw

Configure domain-specific execution agents in AutoResearchClaw by setting Config.mode to "collider_agent" or "biology_agent" and supplying the corresponding ColliderAgentConfig or BiologyAgentConfig object, which the pipeline uses to instantiate specialized sandboxes that manage skill installation, Claude Code invocation, and domain-specific result parsing.

AutoResearchClaw provides specialized back-ends for high-energy physics (HEP) and constraint-based metabolic modeling through domain-specific execution agents. This guide explains how to enable and configure the ColliderAgent for particle physics research and the COBRApy-based Biology Agent for genome-scale metabolic modeling using the configuration classes and sandbox implementations in the aiming-lab/AutoResearchClaw repository.

Understanding the Agent Architecture

AutoResearchClaw replaces its default Python-code generation stage with domain-specific executors when configured appropriately. The architecture consists of two primary specialized agents:

• ColliderAgent: Targets high-energy physics workflows using Claude Code integrated with the external ColliderAgent repository.
• Biology Agent (COBRApy): Targets metabolic modeling using Claude Code, COBRApy, and BIGG genome-scale models.

Both agents follow an identical integration pattern. The global Config object declares agent-specific configuration via the collider_agent and biology_agent fields. During execution, the pipeline stage defined in researchclaw/pipeline/stage_impls/_execution.py checks Config.mode and instantiates the corresponding sandbox—ColliderAgentSandbox or BiologyAgentSandbox—to handle the workflow.

Configuration Classes and Core Parameters

Configuration objects reside in researchclaw/config.py and control how the sandboxes prepare workspaces and execute domain code.

ColliderAgentConfig Options

The ColliderAgentConfig class (defined at line 299) governs the HEP execution environment:

• incremental: bool (default False): When set to True, the sandbox preserves prior artifacts and incremental build states between runs. Defined at line 338.
• install_skills: bool (default True): Controls automatic copying of agent skill directories into the workspace .claude/ folder. Set to False if skills are pre-installed globally. Defined at lines 327–329.
• collider_agent_dir: str (default "external/agents/ColliderAgent"): Path to the external ColliderAgent repository containing skills/ and agents/ folders. The sandbox resolves this using Path(...).expanduser().resolve() at line 608.

BiologyAgentConfig Options

The BiologyAgentConfig class (defined at line 342) mirrors the ColliderAgent pattern for metabolic modeling:

• incremental: bool: Inherits the same incremental execution semantics for preserving COBRApy model files between iterations.
• install_skills: bool: Controls whether the sandbox copies the Biology-Agent skills into the workspace.
• biology_agent_dir: str (implicit, default "external/agents/Biology-Agent"): Analogous to collider_agent_dir, pointing to the Biology-Agent repository.

Pipeline Integration and Execution Flow

The execution stage selects the appropriate sandbox based on the top-level configuration. As implemented in researchclaw/pipeline/stage_impls/_execution.py (lines 149–151 and 239–242), the logic follows this pattern:

if ca_cfg := config.collider_agent:
    from researchclaw.experiment.collider_agent_sandbox import ColliderAgentSandbox
    sandbox = ColliderAgentSandbox(ca_cfg, workspace)
    # Execute and parse results.json...

elif ba_cfg := config.biology_agent:
    from researchclaw.experiment.biology_agent_sandbox import BiologyAgentSandbox
    sandbox = BiologyAgentSandbox(ba_cfg, workspace)
    # Execute and parse COBRApy outputs...

Each sandbox performs three distinct operations:

1. Prepare Workspace: Creates a .claude/ directory, copies skill/agent files (global or project-scoped), and writes the prompt file (collider_plan.md or biology_plan.md).
2. Invoke Claude Code: Executes claude -p <prompt> with the correct environment variables (e.g., CLAUDE_CODE_PATH).
3. Parse Results: Reads the agent-produced results.json (ColliderAgent) or COBRApy solution files (Biology Agent) and converts them into AutoResearchClaw's standard metric format.

Practical Configuration Examples

Enabling ColliderAgent for High-Energy Physics

To activate the ColliderAgent back-end, set mode="collider_agent" and provide a ColliderAgentConfig instance:

from researchclaw.config import Config, ColliderAgentConfig

cfg = Config(
    mode="collider_agent",
    collider_agent=ColliderAgentConfig(
        incremental=False,
        install_skills=True,
        collider_agent_dir="external/agents/ColliderAgent",
    ),
)

When passed to the pipeline, this configuration triggers ColliderAgentSandbox to handle the experiment execution.

Configuring the COBRApy Biology Agent for Metabolic Modeling

For constraint-based metabolic modeling using COBRApy and BIGG models:

from researchclaw.config import Config, BiologyAgentConfig

cfg = Config(
    mode="biology_agent",
    biology_agent=BiologyAgentConfig(
        incremental=True,
        install_skills=False,
    ),
)

The BiologyAgentSandbox loads genome-scale models via cobra.io.load_model, sets medium constraints and objectives, runs FBA/pFBA/FVA analysis, and writes a JSON summary that AutoResearchClaw converts to metrics.

Advanced Direct Sandbox Usage

For debugging or custom workflows, instantiate the sandbox directly without the full pipeline:

from pathlib import Path
from researchclaw.experiment.collider_agent_sandbox import ColliderAgentSandbox
from researchclaw.config import ColliderAgentConfig

cfg = ColliderAgentConfig(incremental=False)
workspace = Path("/tmp/auto-research-claw/run1")
sandbox = ColliderAgentSandbox(cfg, workspace)

sandbox.prepare_workspace()
sandbox.run_project(prompt_path=workspace / "collider_plan.md")
metrics = sandbox.read_results()

The run_project method is implemented at line 165 in researchclaw/experiment/collider_agent_sandbox.py.

Test-Driven Configuration Reference

The repository's test suite demonstrates minimal viable configurations. In tests/test_hep_incremental.py (lines 13–19), the pattern appears as:

cfg = ColliderAgentConfig(incremental=True, install_skills=False)
sandbox = ColliderAgentSandbox(cfg, workspace)
sandbox.run_project(...)

Key Source Files and Implementation Paths

File	Role
researchclaw/config.py	Defines Config, ColliderAgentConfig (line 299), and BiologyAgentConfig (line 342).
researchclaw/experiment/collider_agent_sandbox.py	Implements ColliderAgentSandbox for HEP workflows, including run_project (line 165).
researchclaw/experiment/biology_agent_sandbox.py	Implements BiologyAgentSandbox for COBRApy-based metabolic modeling.
researchclaw/pipeline/stage_impls/_execution.py	Contains the conditional logic (lines 149–151, 239–242) that selects the appropriate sandbox based on Config.mode.
researchclaw/prompts/biology.py	Provides the prompt template driving the Biology Agent workflow.
tests/test_hep_incremental.py	Reference implementation showing incremental ColliderAgent execution.

Summary

• Configure agents by instantiating ColliderAgentConfig or BiologyAgentConfig and assigning them to the corresponding fields in the global Config object.
• Select execution mode by setting Config.mode to "collider_agent" or "biology_agent" to trigger the appropriate sandbox branch in researchclaw/pipeline/stage_impls/_execution.py.
• Control workspace behavior using the incremental flag (preserve artifacts) and install_skills flag (auto-copy skill directories).
• Specify agent repositories via collider_agent_dir or biology_agent_dir to point to the external skill and agent definitions.
• Parse outputs automatically through the sandbox layer, which converts domain-specific results (results.json for ColliderAgent, COBRApy solution files for Biology) into standard AutoResearchClaw metrics.

Frequently Asked Questions

What is the difference between incremental and fresh execution modes?

Incremental mode (incremental=True) preserves the workspace state between runs, allowing the agent to build upon previously generated models or simulation outputs. Fresh mode (incremental=False, the default) wipes prior artifacts, ensuring each experiment starts from a clean state defined solely by the current prompt.

How does AutoResearchClaw handle skill installation for domain agents?

The install_skills parameter controls automatic skill deployment. When True (default), the sandbox copies the agent's skills/ and agents/ directories from the configured agent repository (e.g., external/agents/ColliderAgent) into the workspace's .claude/ folder. Set this to False if you maintain skills as global Claude Code installations.

Can I use both ColliderAgent and COBRApy in the same pipeline run?

No, the pipeline executes one execution mode per run. The conditional logic in researchclaw/pipeline/stage_impls/_execution.py checks for collider_agent first, then biology_agent, and instantiates only the first matching sandbox. To use both domains, configure separate pipeline runs with distinct Config objects and aggregate results externally.

Where does the sandbox write intermediate results and agent outputs?

The sandbox writes artifacts to the specified workspace directory. For ColliderAgent, it generates collider_plan.md as the input prompt and expects results.json as output. For the Biology Agent, it produces biology_plan.md and parses COBRApy model files and solution data. Both sandboxes create a .claude/ subdirectory for skill files when install_skills is enabled.

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