A Graph-Structured Harness for Search Agents

Official implementation of Harness-G: A Graph-Structured Harness for Search Agents

Yanning Hou^*, Haoyuan Chen^*, Sihang Zhou^†, Xiaoshu Chen, Xirui Liu, Duanyang Yuan, Lingyuan Meng, Quan Liu, Jian Huang
National University of Defense Technology
^*Equal contribution    ^†Corresponding author

Paper · Overview · Method · Results · Quick Start · Citation

Reinforcement-learning search agents typically generate free-form retrieval queries. Although the strings may look diverse, they often retrieve nearly identical evidence, leaving group-relative optimization with little meaningful retrieval contrast. We refer to this failure mode as retrieval-equivalence collapse.

Harness-G replaces free-form query generation with a finite menu of typed, verifiable actions over a programmatically induced paragraph–sentence–entity graph. The policy selects an action ID, while the environment handles query construction, graph navigation, validation, and deduplication.

Harness-G consists of three components:

1. Graph construction: build a paragraph–sentence–entity graph without a generative LLM.
2. Structured navigation: expose a bounded, state-dependent action menu instead of asking the policy to write retrieval queries.
3. Structured Non-Myopic Credit (SNC): compare feasible same-state alternatives and propagate downstream gains to enabling actions during GRPO training.

The frozen answerer and action previews are used only during training, so Harness-G introduces no additional scorer calls at inference time. Core implementations are available in harness_g/snc.py and harness_g/snc_trainer.py.

Harness-G achieves the highest average F1 across six QA benchmarks at both evaluated Qwen2.5 model scales.

With Qwen2.5-3B-Instruct, Harness-G improves over Graph-R1 by +7.97 F1 on 2WikiMultiHopQA, +9.12 F1 on HotpotQA, and +5.95 F1 on MuSiQue.

git clone https://github.com/7HHHHH/Harness-G.git
cd Harness-G

ENV_NAME=s3 PYTHON_VERSION=3.9 \
  bash scripts/setup_harness_g_conda.sh

conda activate s3
python -m pip install tiktoken
python -m spacy download en_core_web_sm

The reported experiments use Linux, Python 3.9, PyTorch 2.4, and NVIDIA GPUs. If your CUDA version differs, install the corresponding PyTorch build first.

Datasets are not redistributed in this repository. We use the six-dataset release provided by Graph-R1; follow their dataset instructions to obtain the source corpora and QA splits.

Set up an external workspace for corpora, graphs, checkpoints, and run outputs:

export EXPERIMENT_ROOT=/absolute/path/to/harness_g_experiments
bash experiments/scripts/setup_workspace.sh

Prepare a 2WikiMultiHopQA corpus, construct the graph, and launch training:

python experiments/scripts/prepare_corpus.py \
  --source /absolute/path/to/2wiki_corpus.jsonl

bash experiments/scripts/build_graph.sh
bash experiments/scripts/launch_full_snc.sh

Launchers for HotpotQA, MuSiQue, NQ, PopQA, TriviaQA, and the 1.5B model are included under experiments/. See the experiment guide for dataset preparation and additional commands.

Evaluation utilities for Exact Match, token-overlap F1, retrieval similarity, and generation quality are provided in evaluation/.

If you find Harness-G useful, please cite:

@misc{hou2026harnessg,
  title         = {Harness-G: A Graph-Structured Harness for Search Agents},
  author        = {Yanning Hou and Haoyuan Chen and Sihang Zhou and Xiaoshu Chen
                   and Xirui Liu and Duanyang Yuan and Lingyuan Meng and Quan Liu
                   and Jian Huang},
  year          = {2026},
  eprint        = {2607.27652},
  archivePrefix = {arXiv},
  primaryClass  = {cs.CL},
  url           = {https://arxiv.org/abs/2607.27652}
}

This project builds on Graph-R1 and VERL. We thank their authors and contributors for making their work publicly available.

This project is released under the MIT License.