ScienceEvolve 提供自主科研智能體工作流程框架與 SDK

Build, run, and improve your own science research workflow, and evolve it.

English | 简体中文

ScienceEvolve is the fully autonomous research framework presented in Rethinking Scientific Discovery in the Agentic Era. Build an Agent team, follow its execution, improve the task using real feedback, and authorize Main to evolve the workflow itself.

🧩 Two ways to use ScienceEvolve — shared workflow semantics, with an interface for your way of working.

— This repository. Run workflows from TypeScript or the command line and embed research in your own services. See the SDK examples and Web / SDK comparison (Chinese).

— Web / Server entry. Compose Agents visually, connect model gateways, manage research projects, and inspect traces and delivered files.

Your research team, one workflow

“Here is a Poisson solver. Explore two improvements, validate convergence, compare the errors, and write a report.”

Connect planning, parallel exploration, implementation, and review in workflow.json. Main coordinates the work and confirms completion; Workers handle research, experiments, coding, and review. Each Agent can select Codex, Claude Code, DSH, pi, or Hermes, with its own model, prompt, Skills, and MCP tools.

Two feedback loops: improve the task and the process

The task loop runs a method, collects real feedback, improves the method, and runs again. The process loop reviews the research results and updates Agent responsibilities, tools, or routing before continuing. Start with a fixed workflow and enable process evolution when needed.

Evolver is part of the team. In the current implementation, Main takes this role when authorized to reconfigure dynamically. Main submits workflow.json and calls apply_workflow; SDK Runtime validates the proposal before applying it. Actual task evaluation determines whether the change helps.

Main / Worker and orchestration · Dynamic reconfiguration scope (Chinese)

Features

Let Main evolve the workflow

Authorized Main can add or remove Agents, change responsibilities and paths, switch Harnesses, and submit an updated workflow. SDK Runtime validates before applying the proposal so the team can adapt to the task. Editable scope.

Set Loop rounds and the exit Agent

Main starts a finite-element mesh convergence experiment. Coder → Executor → Review runs for three complete rounds, then exits to the selected Writer Agent, which delivers the error analysis report (errors.md). Both the number of rounds and exit Agent are configurable. Configure SDK Loops (Chinese).

Revert and retry from experiment evidence

With Git collaboration enabled, Idea proposes a larger simulation time step. Execution implements and merges it, but evaluation regresses. The authorized Review Agent uses git_revert on its current task branch to restore the accepted code and rerun the benchmark. The revert is a new commit; the failed change remains in history. Configure Git credentials and workflows (Chinese).

Review and integrate parallel contributions

With Git collaboration enabled, Agents work in isolated worktrees. Collaboration groups organize parallel exploration, with review and PR integration at each level. Configure a GitHub account.

Resume interrupted work

System Runtime retains project state, completed progress, and execution traces. Recoverable interruptions can resume through review and delivery. Check actual external processes and results before continuing external jobs.

Keep adjusting in natural language

Describe new goals and changes through task input. Main, when authorized to reconfigure, can update Agents, Loops, and collaboration groups through the SDK workflow update mechanism. Use run.addInput() for follow-up requirements and run.respond() to answer task questions.

Quick start

You need Node.js 24+, npm 10+, Git to clone the source, and a model gateway. This starter uses the bundled pi Harness and a Chat Completions gateway with reasoning_effort: high support.

1. Install the SDK and CLI

Clone the repository's main branch and install:

git clone --branch main --single-branch https://github.com/OpenMOSS/ScienceEvolve.git ScienceEvolve
cd ScienceEvolve
npm ci
npm run install:cli
scievolve --help

Keep this terminal in the repository root. Create an empty task directory, such as /absolute/todo-project, and choose a separate absolute /absolute/scienceevolve-data directory for runtime state. Replace these paths in the commands below; neither directory may contain the other.

2. Connect and test a model

Set MODEL_API_KEY in the startup environment. In Bash use export MODEL_API_KEY='YOUR_KEY'; in PowerShell use $env:MODEL_API_KEY = 'YOUR_KEY'.

Save the following as reasoning.json in the repository root. Replace YOUR_MODEL here and in the commands with the same model ID from your provider:

{
  "YOUR_MODEL": {
    "parameter": "reasoning_effort",
    "options": [{ "id": "high", "label": "High", "value": "high" }]
  }
}

scievolve gateway add --data-dir /absolute/scienceevolve-data --name research --url https://YOUR_PROVIDER/v1 --protocol chat-completions --models YOUR_MODEL --default-model YOUR_MODEL --key-env MODEL_API_KEY --reasoning-file reasoning.json
scievolve gateway test GATEWAY_ID --data-dir /absolute/scienceevolve-data --model YOUR_MODEL --harness pi --reasoning-option high

Use the gateway ID returned by gateway add as GATEWAY_ID. Continue when the connection test passes. For other protocols, reasoning parameters, per-Agent models, or Codex native login, see the model configuration guide (Chinese).

3. Run a Workflow

Start with software development and testing. It builds a Node.js Todo CLI, then tests and repairs it in the task directory:

scievolve workflow validate example/02-software-development/workflow.json
scievolve start example/02-software-development/workflow.json example/02-software-development/requirement.txt --data-dir /absolute/scienceevolve-data --workspace /absolute/todo-project --gateway GATEWAY_ID --model YOUR_MODEL --harness pi

The CLI streams events and prints the run ID and final status. When the status is completed, inspect the source, tests, and usage instructions in your task directory, with execution records under development/. To pause, press Ctrl+C, wait for shutdown, and use the printed resume command with the same data directory.

SDK tutorial: from a first task to your own workflow

① Finish your first task. Follow the quick start above, then inspect the delivered code and run its tests. Add files or images with --inputs, and use run input / run respond for follow-up requirements and answers. See inputs, workspaces, and pause and recovery (Chinese).

② Compose your own workflow. Copy a workflow and edit its Agent roles, routes, completion criteria, and Loops. Use Git-on collaboration groups for isolated parallel work, and enable orchestration.allowMainReconfiguration when Main should evolve the process. The authoring Skill, workflow reference, and Loop guide explain these settings. Validate the configuration before starting it.

Embed it in Node.js

After the gateway setup above, save this as run.mjs in the repository root and run node run.mjs. Use the same paths, model, and tested gateway ID:

import { readFile } from 'node:fs/promises';
import { resolve } from 'node:path';
import { createResearchSdk, loadWorkflowConfig, bindWorkflowConfig } from '@scienceevolve/sdk';

const workflow = bindWorkflowConfig(
  await loadWorkflowConfig(resolve('example/02-software-development/workflow.json')),
  { model: 'YOUR_MODEL', harness: 'pi' }
);
const sdk = await createResearchSdk({ dataDir: '/absolute/scienceevolve-data' });
try {
  const run = await sdk.start({
    title: 'Todo CLI', workflow,
    requirement: await readFile('example/02-software-development/requirement.txt', 'utf8'),
    workspace: '/absolute/todo-project',
    gatewayBindings: { defaultGatewayId: 'GATEWAY_ID' }
  });
  console.log('runId', run.id);
  for await (const event of run.events()) console.log(event);
  const result = await run.wait();
  console.log(result.status, result.artifacts);
  if (result.status !== 'completed') process.exitCode = 2;
} finally {
  await sdk.close();
}

wait() also returns when a run is paused or interrupted; check status before accepting its result. For integration in another Node project, install the SDK there as a dependency. See the package guide and API / lifecycle reference (Chinese).

Examples

We implement or adapt workflow structures from published papers and open-source projects as ScienceEvolve configurations, including Agent roles, routing, and feedback loops. Credit belongs to the original authors; the table links the original work, official project, and our implementation.

Choose from 23 workflows: three starters and 20 workflows from papers or open-source projects. Select a configuration and requirement from example/, prepare its data, tools, and budget, and start it through the CLI or Node API.

Start with three introductory workflows

Software development and testing — coding, independent testing, and repair. · AHE code evolution — execution, evaluation, optimization, and batch decisions. · General research — ideation, execution, writing, review, and Main coordination.

Workflows from papers and open-source projects

† Google AI co-scientist and ScientistTwo follow the published papers; AgentRxiv code is included in Agent Laboratory. Pinned versions and method mappings are recorded in project manifests and the shared SOURCES.json.

Workflow structures in the Web editor

These Web canvas screenshots from main illustrate the software and AHE workflow structures. Run them in the SDK using the JSON configurations and CLI above.

Complete example index and startup instructions · Shared method sources

Built-in Skill sources and acknowledgements

The SDK bundles the runtime Skills from .agents/skills. Their upstream repositories and uses are listed below.

Bundled Skills include ScienceEvolve-specific integration changes. The project role Skills research-director, idea-agent, experiment-runner, latex-writer, and iclr-reviewer are maintained in this repository. Thank you to the upstream authors and contributors.

The CCFA and Nature copies do not record import commits; their repository attribution is based on comparing Skill names and contents with upstream.

Configure what you need

Detailed guides below are in Chinese unless indicated otherwise.

References

• Agentic Harness Engineering: Observability-Driven Automatic Evolution of Coding-Agent Harnesses. arXiv:2604.25850, 2026.

Additional documentation links