How to Build and Evolve a Custom OpenAI Agent with A-Evolve Using Benchmarks, Skills, Memory, and Workspace Mutations

“`html

In this tutorial, we work directly with the A-Evolve framework in Colab and build a complete evolutionary agent pipeline from the ground up. We set up the repository, configure an OpenAI-powered agent, define a custom benchmark, and build our own evolution engine to see how A-Evolve actually improves an agent through iterative workspace mutations. Through the code, we use the framework’s core abstractions for prompts, skills, memory, benchmarking, and evolution, which help us understand not just how to run A-Evolve, but also how to extend it in a practical, Colab-friendly way.

import os
import sys
import json
import textwrap
import subprocess
import shutil
from pathlib import Path
from getpass import getpass
from collections import Counter, defaultdict

subprocess.check_call([sys.executable, “-m”, “pip”, “install”, “-q”, “openai>=1.30.0”, “pyyaml>=6.0”, “matplotlib>=3.8”])
REPO_DIR = Path(“/content/a-evolve”)
if REPO_DIR.exists():
shutil.rmtree(REPO_DIR)
subprocess.check_call([“git”, “clone”, “–depth”, “1”, “https://github.com/A-EVO-Lab/a-evolve.git”, str(REPO_DIR)])
sys.path.insert(0, str(REPO_DIR))

if not os.environ.get(“OPENAI_API_KEY”):
os.environ[“OPENAI_API_KEY”] = getpass(“Enter your OpenAI API key: “).strip()

OPENAI_MODEL = “gpt-4o-mini”

import yaml
import matplotlib.pyplot as plt

import agent_evolve as ae
from agent_evolve.protocol.base_agent import BaseAgent
from agent_evolve.benchmarks.base import BenchmarkAdapter
from agent_evolve.engine.base import EvolutionEngine
from agent_evolve.types import Task, Trajectory, Feedback, StepResult
from agent_evolve.contract.workspace import AgentWorkspace
from openai import OpenAI

client = OpenAI(api_key=os.environ[“OPENAI_API_KEY”])

WORKSPACE_ROOT = Path(“/content/a_evolve_demo_workspace”)
if WORKSPACE_ROOT.exists():
shutil.rmtree(WORKSPACE_ROOT)

(WORKSPACE_ROOT / “prompts”).mkdir(parents=True, exist_ok=True)
(WORKSPACE_ROOT / “skills”).mkdir(parents=True, exist_ok=True)
(WORKSPACE_ROOT / “memory”).mkdir(parents=True, exist_ok=True)
(WORKSPACE_ROOT / “tools”).mkdir(parents=True, exist_ok=True)

manifest = {
“name”: “colab-aevolve-demo-agent”,
“version”: “0.1.0”,
“contract_version”: “1.0”,
“agent”: {
“type”: “custom”,
“entrypoint”: None
},
“evolvable_layers”: [“prompts”, “skills”, “memory”],
“reload_strategy”: “hot”
}

with open(WORKSPACE_ROOT / “manifest.yaml”, “w”) as f:
yaml.dump(manifest, f, sort_keys=False)

initial_system_prompt = textwrap.dedent(“””
You are a precise text-transformation agent.

Solve the task exactly.
Be concise.
Return only the final answer with no explanation unless the task explicitly asks for JSON.
“””).strip()

(WORKSPACE_ROOT / “prompts” / “system.md”).write_text(initial_system_prompt)

We prepare the full Colab environment needed to run the tutorial from start to finish. We install the required packages, clone the A-Evolve repository, load the framework imports, and securely collect the OpenAI API key for model access.

“` Transform the following:

Original: The cat is sleeping on the windowsill.

Transformed: Sleeping on the windowsill is the cat. Transform the following statement:

Original: The cat chased the mouse.
Transformed: The mouse was chased by the cat.