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

> Learn to configure domain-specific execution agents like ColliderAgent and COBRApy in AutoResearchClaw. Set Config mode and supply agent configurations for specialized sandboxes and efficient research.

- Repository: [AIMING Lab/AutoResearchClaw](https://github.com/aiming-lab/AutoResearchClaw)
- Tags: how-to-guide
- Published: 2026-05-28

---

**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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/pipeline/stage_impls/_execution.py) (lines 149–151 and 239–242), the logic follows this pattern:

```python
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/collider_plan.md) or [`biology_plan.md`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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:

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

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

```python
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/tests/test_hep_incremental.py) (lines 13–19), the pattern appears as:

```python
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/config.py) | Defines `Config`, `ColliderAgentConfig` (line 299), and `BiologyAgentConfig` (line 342). |
| [`researchclaw/experiment/collider_agent_sandbox.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/experiment/collider_agent_sandbox.py) | Implements `ColliderAgentSandbox` for HEP workflows, including `run_project` (line 165). |
| [`researchclaw/experiment/biology_agent_sandbox.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/experiment/biology_agent_sandbox.py) | Implements `BiologyAgentSandbox` for COBRApy-based metabolic modeling. |
| [`researchclaw/pipeline/stage_impls/_execution.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/prompts/biology.py) | Provides the prompt template driving the Biology Agent workflow. |
| [`tests/test_hep_incremental.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/collider_plan.md) as the input prompt and expects [`results.json`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/results.json) as output. For the Biology Agent, it produces [`biology_plan.md`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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.