EvoScientist/README.md at 438f9e56d5b15a6949649285b27660477be99db9

ouyangbo/EvoScientist

Fork 0

Files

T

X-iZhang 9bbde69f7f update

2026-03-12 03:12:06 +00:00

17 KiB

Raw Blame History

English | 简体中文

EvoScientist aims to harness vibe research by enabling self-evolving AI scientists that autonomously explore, generate insights, and iteratively improve. It is designed to be opinionated and ready to use out of the box, offering a living research system that grows alongside evolving agent skills, toolsets, and memory bases. Moving beyond traditional human-in-the-loop systems, EvoScientist adopts a human-on-the-loop paradigm, where AI acts as a research buddy that co-evolves with human researchers and internalizes scholarly taste and scientific judgment.

✨ Features

🤖 Multi-Agent Team — 6 sub-agents (plan, research, code, debug, analyze, write) working in concert.
🧠 Persistent Memory — Context, preferences, and findings survive across sessions.
🔬 Scientific Workflow — Intake → plan → execute → evaluate → write → verify.
🌐 Multi-Provider — Anthropic, OpenAI, Google, NVIDIA — one config to switch.
📱 Multi-Channel — CLI as the hub; Telegram, Discord, Slack, Feishu, WeChat, and more — one agent session.
🔌 MCP & Skills — Plug in MCP servers or install skills from GitHub on the fly.

🎯 ᯓ➤ Roadmap

🖥️ Full-screen TUI and classic CLI interfaces
📻 EvoMemory v1.0 shipped
⚒️ 200+ predefined skills built in
🧩 Built-in research-lifecycle skills shipped
👋 Human-in-the-loop action approval
🦾 Agent-initiated human clarification
📑 Technical report on the way
📺 Web app with workspace UI
📹 Demo and tutorial in the works
📊 Benchmark suite to be released
⏰ Scheduled tasks for the core system planned

🔥 News

[?? Mar 2026] ⛳ Technical Report is live! Check it out 👈
[?? Mar 2026] 🏆 6/6 accepted at ICAIS 2025 AI Scientist Track — Best Paper & AI Reviewer's Appraisal Award! Details 👈
[?? Mar 2026] 🚀 EvoScientist officially debuts!

📦 Installation

Tip

Requires Python 3.11+ (< 3.14). We recommend uv or conda for dependency management and virtual environments.

🪛 Install uv (if you don't have it)

curl -LsSf https://astral.sh/uv/install.sh | sh

Quick Install

uv tool install EvoScientist

Or install into the current environment instead:

uv pip install EvoScientist

Development Install

git clone https://github.com/EvoScientist/EvoScientist.git
cd EvoScientist
uv sync --dev

Using conda

conda create -n EvoSci python=3.11 -y
conda activate EvoSci
pip install -e ".[dev]"

Using PyPi

pip install EvoScientist          # quick install
pip install -e ".[dev]"           # development install

Optional: Channel dependencies

Messaging channel integrations require extra dependencies. Install only what you need:

uv pip install "EvoScientist[telegram]"     # Telegram
uv pip install "EvoScientist[discord]"      # Discord
uv pip install "EvoScientist[slack]"        # Slack
uv pip install "EvoScientist[wechat]"       # WeChat
uv pip install "EvoScientist[qq]"           # QQ
uv pip install "EvoScientist[all-channels]" # everything

Upgrade to the latest code base

git pull && uv sync --dev

🔝Back to top

🔑 Configuration

The easiest way to configure API keys is the interactive wizard:

EvoSci onboard

Tip

It walks you through provider selection, key validation, model choice, and workspace mode.

📟 Manual configuration via environment variables

Set at least one LLM provider key and (optionally) a search key:

# Pick one LLM provider
export ANTHROPIC_API_KEY="sk-..."   # Claude — console.anthropic.com
export OPENAI_API_KEY="sk-..."      # GPT   — platform.openai.com
export GOOGLE_API_KEY="AI..."       # Gemini — aistudio.google.com/api-keys
export NVIDIA_API_KEY="nvapi-..."   # NIM   — build.nvidia.com

# Web search (optional)
export TAVILY_API_KEY="tvly-..."    # app.tavily.com

Or use EvoSci config set to persist keys in ~/.config/evoscientist/config.yaml.

Alternatively, copy the example .env file for project-level configuration:

cp .env.example .env  # then fill in your keys

⚠️ Never commit .env files with real keys. It is already in .gitignore.

🔝Back to top

⚡ Quick Start

EvoSci  # or EvoScientist — interactive mode (TUI by default)

Run EvoSci -h for all CLI options.

Common examples

EvoSci                            # interactive mode (TUI by default)
EvoSci -p "your question"        # single-shot mode
EvoSci --workdir /path/to/project # open in a specific directory
EvoSci -m run                     # isolated per-session workspace
EvoSci --ui cli                   # classic CLI (lightweight)
EvoSci serve                      # headless mode — channels only, no interactive prompt

Action Approval (HITL)

By default, shell commands (execute tool) require human approval before running. To skip approval prompts:

# Per-session: auto-approve via CLI flag
EvoSci --auto-approve
EvoSci -p "query" --auto-approve

# Persistent: set in config (applies to all future sessions)
EvoSci config set auto_approve true

# Or allow only specific command prefixes
EvoSci config set shell_allow_list "python,pip,pytest,ruff,git"

During a session you can also reply 3 (Approve all) at any approval prompt to auto-approve for the rest of that session.

Agent Questions (Ask User)

The agent can proactively ask you questions when it needs clarification (e.g., dataset choice, experiment direction). This is enabled by default. To disable:

# Persistent: set in config
EvoSci config set enable_ask_user false

# Re-enable
EvoSci config set enable_ask_user true

In-session commands

Command	Description
`/new`	Start a new session
`/current`	Show thread ID and workspace path
`/channel`	Start a messaging channel
`/skills`	List installed skills
`/install-skill <src>`	Install skill from path or GitHub
`/mcp`	List MCP servers and tool routing
`/exit`	Quit

Script Inference

from EvoScientist import EvoScientist_agent
from langchain_core.messages import HumanMessage
from EvoScientist.utils import format_messages

thread = {"configurable": {"thread_id": "1"}}
last_len = 0

for state in EvoScientist_agent.stream(
    {"messages": [HumanMessage(content="Hi?")]},
    config=thread,
    stream_mode="values",
):
    msgs = state["messages"]
    if len(msgs) > last_len:
        format_messages(msgs[last_len:])
        last_len = len(msgs)

🔝Back to top

🔌 MCP Integration

Add external tools via MCP servers with a single command:

# Usage
EvoSci mcp add <name> <command> [-- args...]

# Example
EvoSci mcp add sequential-thinking npx -- -y @modelcontextprotocol/server-sequential-thinking

Tip

For command options, config fields, tool routing, wildcard filtering, and troubleshooting, see the MCP Integration Guide.

🔝Back to top

📱 Channels

Connect messaging platforms so they share the same agent session as the CLI:

# Usage
EvoSci channel setup <channel>

# Example
EvoSci channel setup telegram

Multiple channels can run concurrently — comma-separate names in the config:

channel_enabled: "telegram,discord,slack"

The channel can also be started interactively with /channel in the CLI session.

Tip

For per-channel setup guides, capability matrix, architecture details, and troubleshooting, see the Channel Integration Guide.

🔝Back to top

📚 Acknowledgments

This project builds upon the following outstanding open-source works:

LangChain — A framework for building agents and LLM-powered applications.
DeepAgents — The batteries-included agent harness.

We thank the authors for their valuable contributions to the open-source community.

🔝Back to top

🌍 Project Roles

Core Contributors

_{Xi Zhang}

_{Yougang Lyu}

_{Dinos Papakostas}

_{Yuyue Zhao}

_{Ziheng Zhang}

_{Xiaohui Yan}

Contributors

Jan Piotrowski, Wiktor Cupiał, Jakub Kaliski, Jakub Filipiuk, Xinhao Yi, Shuyu Guo, Andreas Sauter, Wenxiang Hu, Jacopo Urbani, Zaiqiao Meng, Jun Luo, Lun Zhou

Xiaoyi DeepResearch Team and the wider open-source community contribute to this project.

For any inquiries or collaboration opportunities, please contact: EvoScientist.ai@gmail.com

🔝Back to top

🤝 Contributing

We welcome contributions from developers, researchers, and AI coding agents at all levels. Our Contributing Guidelines are designed for both humans and AI agents — covering architecture, patterns, extension guides, and code standards to help you contribute safely and effectively.

📈 Star History

📝 Citation

If you find our paper and code useful in your research and applications, please cite using this BibTeX:

@article{evoscientist2026, 
  title={EvoScientist: Towards Multi-Agent Evolving AI Scientists for End-to-End Scientific Discovery}, 
  author={Yougang Lyu and Xi Zhang and Xinhao Yi and Yuyue Zhao and Shuyu Guo and Wenxiang Hu and Jan Piotrowski and Jakub Kaliski and Jacopo Urbani and Zaiqiao Meng and Lun Zhou and Xiaohui Yan}, 
  journal={arXiv preprint arXiv:2603.08127}, 
  year={2026} 
}

🔝Back to top

📜 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🔝Back to top

Created and maintained by Xi Zhang, built with the open-source community.

17 KiB Raw Blame History

✨ Features

🎯 ᯓ➤ Roadmap

🔥 News

📖 Table of Contents

📦 Installation

Quick Install

Development Install

🔑 Configuration

⚡ Quick Start

🔌 MCP Integration

📱 Channels

📚 Acknowledgments

🌍 Project Roles

Core Contributors

Contributors

🤝 Contributing

📈 Star History

📝 Citation

📜 License

17 KiB

Raw Blame History