evomaster

name	evomaster
description	Build, configure, and run EvoMaster autonomous AI agents. Use when you need to create single or multi-agent systems with tool calling, MCP integration, skill extensions, or self-evolving workflows for scientific discovery, Kaggle competitions, or general automation tasks.

EvoMaster Skill

EvoMaster is a framework for building autonomous AI agents that can think, use tools, and self-evolve through iterative experimentation. This skill guides you through setting up, configuring, and running EvoMaster-based agent systems.

Prerequisites

Before running any EvoMaster agent, you need API keys for the LLM providers you plan to use. Please ask the user to provide the following as needed:

• LLM API Key (required): e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY, or a compatible provider key
• LLM Base URL (if using a proxy or custom endpoint): e.g., GPT_BASE_URL
• LLM Model Name: e.g., GPT_CHAT_MODEL
• Search API Key (optional, for web search tools): e.g., Google Search API key
• MCP Service URLs (optional, for MCP tool integrations): e.g., Bohrium platform endpoints
• Bohrium Credentials (optional, for scientific computing): BOHRIUM_ACCESS_KEY, BOHRIUM_PROJECT_ID
• Kaggle Credentials (optional, for Kaggle competitions): Kaggle API token

Store these in a .env file at the project root. EvoMaster automatically loads .env files and substitutes ${VAR_NAME} placeholders in configuration YAML files.

Environment Setup

Clone and Install

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

# Install dependencies
pip install -r requirements.txt

# (Optional) Install additional dependencies for specific features
pip install faiss-cpu       # For RAG vector search
pip install bohr-agent-sdk  # For Bohrium integration

Verify Installation

python -c "from evomaster.core import BasePlayground; print('EvoMaster ready')"

Framework Capability Map

EvoMaster provides a comprehensive agent framework with the following capabilities:

Agent Architectures

Architecture	Description	Use Case
Single Agent	One agent with tools, running a think-act-observe loop	Simple automation, scientific discovery, general tasks
Multi-Agent (Sequential)	Multiple agents with different roles executing in sequence	Planning + execution workflows, research pipelines
Multi-Agent (Parallel)	Multiple agent copies executing the same or different tasks concurrently	Parallel experimentation, best-of-N optimization
Self-Evolving Multi-Agent	Agents that iterate through draft-research-improve cycles	Kaggle competitions, iterative optimization

Output Modes

Mode	Description	Config
Plain Text	Agent responds with text only, no tool calls	tools: { builtin: [] }
ReAct (Think + Act + Observe)	Agent reasons, calls tools, observes results, and iterates	tools: { builtin: ["*"] }

Extension System

Extension Type	Description
Built-in Tools	execute_bash (shell commands), str_replace_editor (file operations), think (reasoning), finish (task completion)
Custom Tools	User-defined tools inheriting from BaseTool, auto-discovered from playground/{name}/tools/
MCP Tools	Tools provided by MCP (Model Context Protocol) servers via stdio, HTTP, or SSE transport
Skills	Domain knowledge packages with metadata, documentation, and executable scripts

Tool & Skill Registration Mechanism

Built-in Tools

Built-in tools are automatically registered when creating an agent. Control which tools are exposed via the config:

agents:
  my_agent:
    tools:
      builtin: ["*"]                    # All built-in tools
      # builtin: ["execute_bash", "finish"]  # Only specific tools
      # builtin: []                     # No built-in tools (text-only agent)

Custom Tools

1. Create a Python file in playground/{your_playground}/tools/:

from evomaster.agent.tools.base import BaseTool, BaseToolParams
from pydantic import Field
from typing import ClassVar, Any

class MySearchParams(BaseToolParams):
    """Search the web for information."""
    name: ClassVar[str] = "my_search"
    query: str = Field(description="Search query")

class MySearchTool(BaseTool):
    name: ClassVar[str] = "my_search"
    params_class: ClassVar[type[BaseToolParams]] = MySearchParams

    def execute(self, session, args_json: str) -> tuple[str, dict[str, Any]]:
        params = self.parse_params(args_json)
        # Your tool logic here
        return f"Results for: {params.query}", {"status": "ok"}

2. Register in config:

agents:
  my_agent:
    tools:
      builtin: ["*"]
      my_search: "my_search"   # key: tool_type, value: filename (without .py)

3. Pre-built custom tools in this skill package

   Agents using this skill can find ready-made EvoMaster BaseTool implementations under scripts/ in the same directory as this SKILL.md. Copy or adapt these files into playground/{your_playground}/tools/ and register them as in step 2 (filename without .py as the tool config value).

   Script	Purpose
   scripts/google_search.py	Google-style search via the Serper API (see script / env for API key variables).
   scripts/web_fetch.py	Fetch pages via Jina Reader and extract structured content with the session LLM (see script for env and limits).

MCP Tools

1. Create an MCP configuration file (e.g., mcp_config.json) in your config directory:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    },
    "my-http-server": {
      "transport": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

2. Enable in config:

agents:
  my_agent:
    tools:
      builtin: ["*"]
      mcp: "mcp_config.json"    # Path to MCP config (relative to config dir)
      # mcp: "*"                 # Use default mcp_config.json

MCP tools are automatically discovered, connected, and registered. Each MCP tool is named {server_name}_{tool_name}.

Skills

Skills are domain knowledge packages located under evomaster/skills/. Each skill has a SKILL.md with YAML frontmatter (name, description) and optional scripts/ and reference/ directories.

1. Enable skills for an agent in config:

agents:
  my_agent:
    skills: ["*"]           # Expose all available skills
    # skills: ["rag"]       # Expose only the RAG skill
    # skills: []            # No skills (default)
    skill_dir: "./evomaster/skills"  # Skills root directory

2. The agent uses skills via the use_skill tool with three actions:
   • get_info: Load the full SKILL.md content for a skill
   • get_reference: Load a specific reference document from the skill
   • run_script: Execute a script bundled with the skill

Agent Workflow Decision Tree

When receiving a user request to build an EvoMaster agent, follow this decision process:

1. ANALYZE the business scenario
   ├── Simple automation / single task?
   │   └── Use Single Agent (see reference/minimal.md)
   │
   ├── Task requires planning + execution phases?
   │   └── Use Multi-Agent Sequential (see reference/minimal_multi_agent.md)
   │
   ├── Task benefits from parallel attempts?
   │   └── Use Multi-Agent Parallel (see reference/minimal_multi_agent_parallel.md)
   │
   ├── Task requires iterative self-improvement?
   │   └── Use Self-Evolving Multi-Agent (see reference/minimal_kaggle.md)
   │
   └── Task requires external services (scientific computing, web APIs)?
       └── Use MCP Integration (see reference/minimal_bohrium.md)

2. EVALUATE tool requirements
   ├── Only text reasoning needed? → builtin: []
   ├── Code execution + file editing? → builtin: ["*"]
   ├── External API access needed? → Add MCP tools
   ├── Domain knowledge needed? → Add Skills (see reference/skills.md)
   └── Custom functionality? → Create Custom Tools (see reference/custom_tools.md)

3. READ the appropriate reference documents
   └── Navigate to reference/ for detailed implementation guides

Reference Documentation

Detailed guides are in the reference/ directory. Load only what you need:

Document	Description
reference/minimal.md	Single-agent ReAct pattern - the simplest EvoMaster setup
reference/minimal_bohrium.md	MCP tool integration with Bohrium scientific computing platform
reference/minimal_kaggle.md	Self-evolving multi-agent system for Kaggle competitions
reference/minimal_multi_agent.md	Sequential multi-agent collaboration (Planning + Coding)
reference/minimal_multi_agent_parallel.md	Parallel multi-agent execution with independent workspaces
reference/minimal_skill_task.md	Agents using Skills for knowledge retrieval (RAG)
reference/custom_tools.md	How to create, register, and use custom tools (including MCP)
reference/skills.md	How to create, register, and use Skills
reference/configuration.md	Complete configuration reference (YAML structure, environment variables)

Troubleshooting

Dependency Errors

Error	Solution
ModuleNotFoundError: No module named 'evomaster'	Run from the project root, or add the root to PYTHONPATH
ModuleNotFoundError: No module named 'dotenv'	pip install python-dotenv
ImportError: cannot import name 'create_llm'	Ensure evomaster/utils/ is intact; check requirements.txt

API Call Failures

Error	Solution
AuthenticationError / 401	Check OPENAI_API_KEY or equivalent in .env; verify the key is valid
RateLimitError / 429	Reduce max_retries or add retry_delay in LLM config; use a different API key
Timeout errors	Increase timeout in LLM config (default 60s); check network connectivity
ContextOverflowError	Set truncation_strategy: "latest_half" or "summary" in agent context config

MCP Tool Issues

Error	Solution
MCP config file not found	Verify the mcp path in tools config is relative to the config directory
Failed to add MCP server	Check the MCP server command/URL; ensure the server binary is installed
MCP tools not appearing	Verify mcp_config.json format; check server logs for connection errors

Multi-Agent Issues

Error	Solution
Agents sharing context unexpectedly	Use copy_agent() to create independent agent copies for parallel execution
Parallel tasks interfering	Enable split_workspace_for_exp: true in session parallel config
Agent deadlock in multi-agent	Ensure agents are sequential (not waiting on each other); check max_turns limits

Session Issues

Error	Solution
working_dir does not exist	Create the workspace directory, or let EvoMaster auto-create via set_run_dir()
Docker container not starting	Check Docker daemon is running; verify image exists; check resource limits
File not found in workspace	Verify symlinks config maps source data correctly; check working_dir path

Other Issues

Please refer to the core code of EvoMaster.