# evomaster-usage

> Use this skill when you need to install, configure, and run the sjtu-sai-agents/EvoMaster repository. Covers quickstart, LLM config via YAML/.env, running common playgrounds (minimal, minimal_multi_agent, minimal_skill_task, x_master), and troubleshooting typical setup/MCP issues.

- Author: Hang Lin
- Repository: SciX-Skill/evomaster-skill-how-to-use-this-repo-skill
- Version: 20260209232643
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-09
- Source: https://github.com/SciX-Skill/evomaster-skill-how-to-use-this-repo-skill
- Web: https://mule.run/skillshub/@@SciX-Skill/evomaster-skill-how-to-use-this-repo-skill~evomaster-usage:20260209232643

---

---
name: evomaster-usage
description: Use this skill when you need to install, configure, and run the sjtu-sai-agents/EvoMaster repository. Covers quickstart, LLM config via YAML/.env, running common playgrounds (minimal, minimal_multi_agent, minimal_skill_task, x_master), and troubleshooting typical setup/MCP issues.
---

# EvoMaster Usage

## Quick Start (Local)

### 1. Clone + Python env

```bash
git clone https://github.com/sjtu-sai-agents/EvoMaster.git
cd EvoMaster

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip

# Install EvoMaster + deps (pyproject.toml)
pip install -e .
```

Notes:
- EvoMaster declares `requires-python = ">=3.10"` in `pyproject.toml`.
- If you prefer: `pip install -r requirements.txt` also works (but `pip install -e .` is the most accurate).

### 2. Configure LLM credentials (recommended: `.env`)

```bash
cp .env.template .env
$EDITOR .env
```

EvoMaster loads `.env` from the project root when you run `python run.py ...`.

### 3. Run a playground

Minimal single-agent:

```bash
python run.py --agent minimal --task "Explain what this repo does and list the main modules."
```

Or with an explicit config YAML:

```bash
python run.py --agent minimal \
  --config configs/minimal/deepseek-v3.2-example.yaml \
  --task "Discover a pattern: Given sequence 1, 4, 9, 16, 25... find the formula"
```

Outputs are written under `runs/` (logs, trajectories, workspace).

## Common Workflows

### Use a different playground

Multi-agent (planning + coding):

```bash
python run.py --agent minimal_multi_agent \
  --config configs/minimal_multi_agent/deepseek-v3.2-example.yaml \
  --task "Write a small Python script that reads a file and prints the top 10 most frequent words."
```

Skill-based workflow (Analyze -> Plan -> Search -> Summarize):

```bash
python run.py --agent minimal_skill_task --interactive
```

X-Master (more complex; expects MCP services):

```bash
python run.py --agent x_master --task "Solve the problem and explain your reasoning."
```

If X-Master requires MCP services in your setup, follow `EvoMaster/playground/x_master/README.md` to start them.

### Use task files

Run from a text/markdown file path (the CLI treats `.txt`/`.md` as a file if it exists):

```bash
python run.py --agent minimal --task task.md
```

Batch tasks from JSON:

```bash
python run.py --agent minimal --task-file tasks.json
python run.py --agent minimal --task-file tasks.json --parallel
```

### Where to edit configs

Typical pattern:
- Pick the playground you want: `configs/<playground>/...yaml`
- Edit the LLM entry (provider/model/api_key/base_url)
- Ensure each agent points at the right LLM key (example in `playground/minimal/README.md`)

## Troubleshooting

### “ModuleNotFoundError” / import errors

You probably installed deps incorrectly or you are not in your venv.

```bash
source .venv/bin/activate
pip install -e .
python -c "import evomaster; print('ok')"
```

### YAML config edits don’t take effect

Sanity checks:
- You passed the correct `--config ...` file.
- Your YAML is valid (indentation, quotes).
- If you changed `.env`, re-run the command (env vars are loaded at process start).

### LLM requests fail (401/403/timeout)

Checklist:
- Confirm your API key is present (in `.env` or exported in shell).
- For OpenAI-compatible APIs, confirm `base_url` is correct.
- If you copied an example config, replace placeholder values (e.g. `api_key: "dummy"`).

### X-Master MCP tools not available

If the workflow expects MCP servers:
- Start the MCP services as documented in `playground/x_master/README.md`.
- Verify ports match your config (the docs show defaults like 8001/8002).

## What to Read Next (Repo Docs)

If you need deeper internals:
- `EvoMaster/README.md` for entry points and CLI examples
- `EvoMaster/docs/architecture.md` for the Playground -> Exp -> Agent model
- `EvoMaster/docs/skills.md` and `EvoMaster/playground/minimal_skill_task/README.md` for the skill system
- `EvoMaster/playground/*/README.md` for each playground’s specific setup