Skip to content

README.md

Latest commit

 

History

History
176 lines (122 loc) · 5.49 KB

README.md

File metadata and controls

176 lines (122 loc) · 5.49 KB

Evoltjs

English | 中文

Today’s AI coding tools solve one-shot code generation. But the real cost of software lies in long-term evolution: changing requirements, architectural drift, and endless maintenance — turning top engineers into permanent system caretakers.

EVOLT exists to end this.

EVOLT is a framework for self-evolving agents that enables AI to own the full software lifecycle — from initial construction, to long-term maintenance, to continuous evolution.

We are not building another code assistant. We are solving the core problem of long-horizon software engineering.

🏗️ Core Architecture (Vision)

EVOLT is built around a self-evolving improvement engine with three layers:

  • 🛠️ Tool-using agents — Agents that can read, write, test, and refactor real codebases like software engineers.
  • 💾 Persistent experience — Successful actions and patterns are encoded as reusable, composable knowledge assets. (Planned)
  • 🧠 Self-evolution — Agent strategies and workflows continuously improve through experience. (Planned)

✅ Current Status

EVOLT has already open-sourced and stabilized its core foundation: tool-using agents. You can today build AI agents that understand and operate on real code repositories.

We are actively designing and developing self-evolution and persistent experience. The full roadmap is public — contributions and discussion are welcome.

🚀 Why Start with Tools?

We believe that powerful, programmable tool-use is the foundation of long-term autonomy. Before an agent can learn how to improve itself, it must first be able to act reliably in the real world — just like a human engineer working on a live codebase.

Installation

Local Development

For local development, you can use npm link to test the package, especially after making code changes and wanting to test the modified effects locally:

# In the project root directory  
npm run build  
npm link  

# In the project where you want to use evoltagent  
npm link evoltagent

Install from npm (After Release)

npm install evoltagent

Usage

Basic Example

⚠️ Note: The configuration file config.yaml uses camelCase naming (e.g., apiKey, baseUrl), which differs from the snake_case used in the Python version. For details, refer to LLM_CONFIG.md.

import { Agent, ModelResponse, ModelConfig } from "evoltagent";  

// Configure the model using ModelConfig  
const modelConfig: ModelConfig = {  
  provider: "deepseek",  
  model: "deepseek-chat",  
  apiKey: process.env.DEEPSEEK_API_KEY,  
  baseUrl: process.env.DEEPSEEK_BASE_URL || "https://api.deepseek.com/v1",  
  contextWindowTokens: 128000,  
  maxOutputTokens: 8092,  
  temperature: 0.2,  
  topP: 0.9,  
  stream: true,  
};  

async function main() {  
  const agent = new Agent({  
    name: "posy",  
    profile: "You are a helpful assistant.",  
    tools: ["ThinkTool.execute", "Reply2HumanTool.reply"],  
    modelConfig: modelConfig,  
  });  

  const result = await agent.run("Please introduce yourself");  
  console.log("Agent response:", result);  
}  

main().catch(console.error);

Using MCP Tools

First, you need to set up the configuration file. For the configuration method of the MCP Server, refer to LLM_CONFIG.md for details. If you have configured model parameters, you can use the model name from the configuration file to replace the ModelConfig above.

import { Agent, ModelResponse } from "evoltagent";  

async function runAgent(userInput: string): Promise<ModelResponse[]> {  
  const agent = new Agent({  
    name: "posy",  
    profile: "You are an assistant capable of operating a browser.",  
    mcpServerNames: ["playwright"],  
    modelConfig: "deepseek",  
    verbose: 2,  
  });  

  return await agent.run(userInput);  
}

Development

Build the Project

npm run build

Run Examples

⚠️ Note: Files in examples/agent/ require BOYUE_API_KEY and BOYUE_API_URL to be set in the .env file.

⚠️ Note: To use another provider, simply adjust the configuration in examples/agent/modelConfig.ts.

# Basic examples  
npx tsx examples/agent/agentDemoWithModelConfig.ts  
npx tsx examples/agent/agentDemo.ts  

# MCP tools example  
npx tsx examples/agent/agentWithMCPTools.ts

Exported Modules

Core Modules

  • Agent - Main Agent class
  • Model - Model class
  • Message, MessageHistory - Message and message history management

Tools

  • SystemToolStore, FunctionCallingStore - Tool storage
  • ThinkTool - Thinking tool
  • CommandLineTool - Command line tool
  • FileEditor - File editor
  • Reply2HumanTool - Reply-to-human tool
  • TodoListTool - Todo list tool
  • GitTool - Git tool

Tool Registration

  • tools - Register tools
  • registerAgentAsTool - Register Agent as a tool

Environments

  • BaseEnvironment - Base environment
  • CodingEnvironment - Coding environment

Configuration

  • loadModelConfig - Load model configuration
  • Other configuration constants and paths

🙏 Acknowledgments

Sincere thanks to the open-source project claude-quickstarts, which provided significant assistance during the development of this project.