[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6MA1XFXKCN2XTEW3DAYDVHM":3,"skill-same:01M6MA1XFXKCN2XTEW3DAYDVHM":115},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":45,"linkOnly":46,"markdownContent":47,"markdownBody":48,"frontMatter":49,"refName":57,"commitSha":58,"skillDirectory":59,"forksCount":60,"repositoryHtmlUrl":61,"repositoryHomepageUrl":62,"ownerHtmlUrl":63,"ownerBlogUrl":64,"ownerDescription":65,"updatedAt":66,"install":67,"resources":80},"01M6MA1XFXKCN2XTEW3DAYDVHM","evolving-ai-agents",null,"Provides guidance for automatically evolving and optimizing AI agents across any domain using LLM-driven evolution algorithms. Use when building self-improving agents, optimizing agent prompts and skills against benchmarks, or implementing automated agent evaluation loops.","hashgraph-online\u002Fawesome-codex-plugins","hashgraph-online","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F160371962?v=4","01M6CNB6NRJVNNGN14TR01Q6D3","HOL (Hashgraph Online)","01M6JT1HSKKG9V68KQAQGBA7XP",1575,"MIT","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fevolving-ai-agents\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44],"ai agents","evolving ai agents","domain","when","for","implementing","self-improving","loops","Prompt Optimization","across","algorithms","self","agentic","skill discovery","evolve","discovery","applications","Evaluation","Optimization","benchmark","agentic ai","2026-11-10 10:12:30",false,"---\nname: evolving-ai-agents\ndescription: Provides guidance for automatically evolving and optimizing AI agents across any domain using LLM-driven evolution algorithms. Use when building self-improving agents, optimizing agent prompts and skills against benchmarks, or implementing automated agent evaluation loops.\nlicense: MIT\nmetadata:\n  version: 1.0.0\n  category: llm-applications\n  maintainer: Kalaris Labs\n  contributor: A-EVO Lab\n  tags: Agent Evolution, Self-Improving Agents, Prompt Optimization, LLM, Benchmark Evaluation, Skill Discovery, Agentic AI\n  dependencies: a-evolve>=0.1.0, pyyaml>=6.0\n---\n\n# Evolving AI Agents with A-Evolve\n\n## Overview\n\nA-Evolve is universal infrastructure for evolving any AI agent across any domain using any evolution algorithm with zero manual engineering. It represents all evolvable agent state as files (prompts, skills, memory, tools), runs iterative solve-observe-evolve cycles against benchmarks, and uses LLM-driven mutation to improve agent performance automatically.\n\n**Benchmark results** (Claude Opus 4.6):\n- MCP-Atlas: 79.4% (#1)\n- SWE-bench Verified: 76.8% (~#5)\n- Terminal-Bench 2.0: 76.5% (~#7)\n- SkillsBench: 34.9% (#2)\n\n## When to Use A-Evolve\n\n**Use A-Evolve when:**\n- Optimizing agent prompts, skills, or memory against a measurable benchmark\n- Building self-improving agents with automated gating and rollback\n- Evolving domain-specific tool usage and procedures through LLM-driven mutation\n- Running iterative solve-observe-evolve loops to maximize agent performance\n- Needing reproducible, git-versioned evolution history for every change\n\n**Key differentiator**: Other frameworks _build_ agents; A-Evolve _optimizes_ them. It sits on top of any agent framework and makes it better through automated evolution.\n\n**Do NOT use A-Evolve for:**\n- Building multi-agent orchestration from scratch (use CrewAI, LangGraph)\n- One-shot agent tasks with no iteration needed (use LangChain, LlamaIndex)\n- RAG pipeline optimization (use LlamaIndex, Chroma)\n- Prompt-only optimization without skill\u002Fmemory evolution (use DSPy)\n\n## Quick Start\n\n### Installation\n\n```bash\npip install a-evolve                    # Core\npip install a-evolve[anthropic]         # With Claude support\npip install a-evolve[all]               # All providers\n```\n\n### Three-Line Evolution\n\n```python\nimport agent_evolve as ae\n\nevolver = ae.Evolver(agent=\"swe\", benchmark=\"swe-verified\")\nresults = evolver.run(cycles=10)\nprint(f\"Final score: {results.final_score}\")\n```\n\nThis copies the built-in SWE seed workspace, runs 10 evolution cycles against SWE-bench Verified, and returns the optimized agent.\n\n## Core Concepts\n\n### The Agent Workspace\n\nAll evolvable state lives as files in a workspace directory:\n\n```\nmy-agent\u002F\n├── manifest.yaml          # Metadata + entrypoint\n├── prompts\u002F\n│   ├── system.md          # Main system prompt (evolved)\n│   └── fragments\u002F         # Modular prompt pieces\n├── skills\u002F\n│   └── skill-name\u002F\n│       └── SKILL.md       # Reusable procedure with frontmatter\n├── memory\u002F\n│   ├── episodic.jsonl     # Lessons from failures\n│   └── semantic.jsonl     # General knowledge\n├── tools\u002F\n│   ├── registry.yaml      # Tool manifest\n│   └── tool_name.py       # Tool implementations\n└── evolution\u002F             # Managed by engine (metrics, history)\n```\n\n### The Evolution Loop\n\nEach cycle follows five phases:\n\n1. **Solve** — Agent processes a batch of tasks from the benchmark\n2. **Observe** — Benchmark evaluates trajectories, producing (task, trajectory, feedback) triples\n3. **Evolve** — Evolution engine mutates workspace files based on observations\n4. **Gate** — Validate mutations (git snapshot before\u002Fafter for rollback)\n5. **Reload** — Agent reinitializes from evolved filesystem state\n\n### Three Pluggable Interfaces\n\n```python\n# 1. Agent — implements solve()\nclass MyAgent(ae.BaseAgent):\n    def solve(self, task: ae.Task) -> ae.Trajectory:\n        # Domain-specific solving logic\n        return ae.Trajectory(task_id=task.id, output=result, steps=steps)\n\n# 2. Benchmark — implements get_tasks() and evaluate()\nclass MyBenchmark(ae.BenchmarkAdapter):\n    def get_tasks(self, split=\"train\", limit=None) -> list[ae.Task]:\n        return [ae.Task(id=\"1\", input=\"...\")]\n\n    def evaluate(self, task: ae.Task, trajectory: ae.Trajectory) -> ae.Feedback:\n        return ae.Feedback(success=True, score=0.95, detail=\"Passed\")\n\n# 3. Engine — implements step()\nclass MyEngine(ae.EvolutionEngine):\n    def step(self, workspace, observations, history, trial):\n        # Mutate workspace based on observations\n        return ae.StepResult(mutated=True, summary=\"Updated prompts\")\n```\n\n## Workflow 1: Evolve an Existing Agent\n\n**Use when**: You have a working agent and want to optimize it against a benchmark.\n\n**Critical Requirements:**\n- [ ] Agent implements `BaseAgent.solve()` returning `Trajectory`\n- [ ] Benchmark implements `BenchmarkAdapter` with `get_tasks()` and `evaluate()`\n- [ ] Seed workspace has `manifest.yaml` with entrypoint and evolvable layers\n- [ ] System prompt exists at `prompts\u002Fsystem.md`\n- [ ] Workspace is a git repo (run `git init && git add -A && git commit -m \"init\"`)\n\n### Steps\n\n```python\nimport agent_evolve as ae\n\n# Configure evolution parameters\nconfig = ae.EvolveConfig(\n    batch_size=10,           # Tasks per solve round\n    max_cycles=20,           # Maximum evolution iterations\n    evolve_prompts=True,     # Mutate system prompt\n    evolve_skills=True,      # Discover and refine skills\n    evolve_memory=True,      # Build episodic memory\n    evolver_model=\"us.anthropic.claude-opus-4-6-v1\",\n)\n\n# Point to your agent workspace and benchmark\nevolver = ae.Evolver(\n    agent=\".\u002Fmy-agent-workspace\",\n    benchmark=\"swe-verified\",     # Or custom BenchmarkAdapter instance\n    config=config,\n)\n\n# Run evolution\nresults = evolver.run(cycles=10)\n\n# Inspect results\nprint(f\"Cycles completed: {results.cycles_completed}\")\nprint(f\"Final score: {results.final_score}\")\nprint(f\"Converged: {results.converged}\")\nfor cycle_num, score in enumerate(results.score_history):\n    print(f\"  Cycle {cycle_num + 1}: {score:.3f}\")\n```\n\n### Post-Evolution\n\nThe workspace is now optimized. Inspect what changed:\n\n```bash\ncd my-agent-workspace\ngit log --oneline              # See evo-1, evo-2, ... tags\ngit diff evo-1 evo-10          # Compare first and last evolution\ncat prompts\u002Fsystem.md          # Read evolved prompt\nls skills\u002F                     # See discovered skills\n```\n\n## Workflow 2: Add a Custom Benchmark\n\n**Use when**: You want to evolve agents on your own domain-specific tasks.\n\n**Critical Requirements:**\n- [ ] Define task format (inputs, expected outputs)\n- [ ] Implement scoring logic (0.0–1.0 scale)\n- [ ] Prepare task dataset (train + holdout split)\n\n### Steps\n\n```python\nimport agent_evolve as ae\n\nclass CodeReviewBenchmark(ae.BenchmarkAdapter):\n    \"\"\"Evaluate agents on code review quality.\"\"\"\n\n    def get_tasks(self, split=\"train\", limit=None):\n        tasks = load_review_dataset(split)\n        if limit:\n            tasks = tasks[:limit]\n        return [\n            ae.Task(id=t[\"id\"], input=t[\"diff\"], metadata={\"expected\": t[\"comments\"]})\n            for t in tasks\n        ]\n\n    def evaluate(self, task, trajectory):\n        expected = task.metadata[\"expected\"]\n        actual = trajectory.output\n        precision, recall = compute_review_metrics(expected, actual)\n        f1 = 2 * precision * recall \u002F (precision + recall + 1e-9)\n        return ae.Feedback(\n            success=f1 > 0.7,\n            score=f1,\n            detail=f\"P={precision:.2f} R={recall:.2f} F1={f1:.2f}\",\n        )\n\n# Use with any agent\nevolver = ae.Evolver(agent=\".\u002Fmy-agent\", benchmark=CodeReviewBenchmark())\nresults = evolver.run(cycles=5)\n```\n\n## Workflow 3: Create a Custom Evolution Engine\n\n**Use when**: The default LLM-driven mutation doesn't suit your domain.\n\n### Steps\n\n```python\nimport agent_evolve as ae\n\nclass RuleBasedEngine(ae.EvolutionEngine):\n    def step(self, workspace, observations, history, trial):\n        failures = [o for o in observations if not o.feedback.success]\n        if not failures:\n            return ae.StepResult(mutated=False, summary=\"No failures to address\")\n\n        # Analyze failure patterns\n        error_types = categorize_errors(failures)\n        prompt = workspace.read_prompt()\n\n        # Append learned rules to prompt\n        new_rules = generate_rules(error_types)\n        workspace.write_prompt(prompt + \"\\n\" + new_rules)\n\n        return ae.StepResult(\n            mutated=True,\n            summary=f\"Added {len(new_rules)} rules from {len(failures)} failures\",\n        )\n\nevolver = ae.Evolver(\n    agent=\".\u002Fmy-agent\",\n    benchmark=\"my-benchmark\",\n    engine=RuleBasedEngine(),\n)\n```\n\n## Built-in Components\n\n### Seed Agents\n\n| Agent | Domain | Model | Key Feature |\n|-------|--------|-------|-------------|\n| `swe` | SWE-bench | Claude Opus 4.6 | Verify-fix loop, skill proposals |\n| `terminal` | Terminal-Bench | Claude Sonnet 4 | Concurrent timeout, env discovery |\n| `mcp` | MCP-Atlas | Claude Opus 4.6 | MCP server integration |\n\n### Benchmarks\n\n| Name | Domain | Metric |\n|------|--------|--------|\n| `swe-verified` | Code patching | Pass rate |\n| `mcp-atlas` | Tool calling | Accuracy |\n| `terminal2` | Shell tasks | Pass rate |\n| `skill-bench` | Multi-step procedures | Accuracy |\n| `arc-agi-3` | Interactive games | RHAE score |\n\n### Evolution Algorithms\n\n| Algorithm | Strategy | Best For |\n|-----------|----------|----------|\n| A-Evolve\u002FSkillForge | LLM-driven workspace mutation | General-purpose |\n| Guided Synthesis | Memory-first, curated skills | Skill discovery |\n| Adaptive Evolution | Reward tracking, filtered observations | Fine-grained control |\n| Adaptive Skill | Skill-centric refinement | Skill-heavy domains |\n\n## Configuration Reference\n\n```python\nae.EvolveConfig(\n    batch_size=10,              # Tasks per solve round\n    max_cycles=20,              # Max evolution iterations\n    holdout_ratio=0.2,          # Test set split for gating\n    evolve_prompts=True,        # Mutate system prompts\n    evolve_skills=True,         # Discover\u002Frefine skills\n    evolve_memory=True,         # Build episodic memory\n    evolve_tools=False,         # Mutate tool implementations\n    trajectory_only=False,      # Hide scores from evolver\n    evolver_model=\"us.anthropic.claude-opus-4-6-v1\",\n    evolver_max_tokens=16384,\n    egl_threshold=0.05,         # Convergence epsilon\n    egl_window=3,               # Cycles for plateau detection\n)\n```\n\n**Convergence**: Evolution stops early when score improvement is less than `egl_threshold` over the last `egl_window` cycles.\n\n## Skill Format\n\nSkills are reusable procedures discovered and refined during evolution:\n\n```markdown\n---\nname: verify-edge-cases\ndescription: \"TRIGGER when: checking boundary conditions. DO NOT TRIGGER: for happy-path tests.\"\n---\n\n## Pattern\nTest all falsy-but-valid values: 0, False, \"\", [], {}\n\n## Process\n1. List all input boundaries\n2. Run each against the implementation\n3. Check both output AND side effects\n```\n\nSkills accumulate in the workspace `skills\u002F` directory. The evolver curates them: ACCEPT new skills, MERGE overlapping ones, SKIP redundant proposals. Target: 5–10 broad skills, not 30 narrow ones.\n\n## Common Issues\n\n### Evolution score plateaus early\n\n**Cause**: Batch size too small or evolver doesn't see enough failure diversity.\n**Fix**: Increase `batch_size` (try 15–20) and ensure benchmark tasks cover diverse failure modes. Set `trajectory_only=False` so the evolver sees scores.\n\n### Agent workspace grows too large\n\n**Cause**: Skill library bloat from accepting every proposal.\n**Fix**: The default SkillForge engine curates skills automatically. If using a custom engine, implement merging logic to consolidate overlapping skills.\n\n### Git conflicts during evolution\n\n**Cause**: Multiple evolution runs on the same workspace.\n**Fix**: Each `evolver.run()` should operate on its own workspace copy. Use `Evolver(agent=\"seed-name\")` to auto-copy the seed each time.\n\n### LLM provider errors during evolution\n\n**Cause**: Rate limits or authentication issues with the evolver model.\n**Fix**: Check `evolver_model` config. For Bedrock, ensure AWS credentials are configured. For Anthropic, set `ANTHROPIC_API_KEY`.\n\n### Custom agent not picking up evolved state\n\n**Cause**: Agent doesn't implement `reload_from_fs()`.\n**Fix**: Override `reload_from_fs()` in your `BaseAgent` subclass to re-read prompts, skills, and memory from the workspace after each evolution cycle.\n\n## Usage Instructions for Agents\n\nWhen this skill is loaded:\n\n1. **Read this entire file** before implementing any evolution workflow\n2. **Start with the Quick Start** — get a minimal evolution running before customizing\n3. **Use built-in seeds when possible** — `\"swe\"`, `\"terminal\"`, `\"mcp\"` have battle-tested configurations\n4. **Always initialize git** in custom workspaces before running evolution\n5. **Check convergence settings** — default `egl_threshold=0.05` with `egl_window=3` may be too aggressive for your domain\n6. **Inspect evolved state** after each run — read `prompts\u002Fsystem.md` and `skills\u002F` to understand what the evolver learned\n\n**Pro Tips:**\n- Set `trajectory_only=False` (default) so the evolver sees scores — this accelerates learning\n- Start with `batch_size=10` and adjust based on task diversity\n- Use `holdout_ratio=0.2` to prevent overfitting to training tasks\n- After evolution, `git diff evo-1 evo-N` shows the cumulative effect of all mutations\n- If the evolver isn't finding skills, enrich `feedback.detail` strings with specific failure reasons\n\n**Warning Signs:**\n- Score oscillating between cycles → benchmark evaluation may be non-deterministic\n- Skills directory growing past 15+ skills → engine isn't merging\u002Fcurating properly\n- Prompt growing past 10K chars → evolution is appending without refactoring\n- `converged=True` after 2-3 cycles → increase `egl_window` and decrease `egl_threshold`\n\n## References\n\n- **Architecture deep dive**: See [references\u002Farchitecture.md](references\u002Farchitecture.md)\n- **API reference**: See [references\u002Fapi.md](references\u002Fapi.md)\n- **Step-by-step tutorials**: See [references\u002Ftutorials.md](references\u002Ftutorials.md)\n- **Real-world examples**: See [references\u002Fexamples.md](references\u002Fexamples.md)\n- **GitHub issues & solutions**: See [references\u002Fissues.md](references\u002Fissues.md)\n- **Design patterns**: See [references\u002Fdesign-patterns.md](references\u002Fdesign-patterns.md)\n- **Release history**: See [references\u002Freleases.md](references\u002Freleases.md)\n\n## Related skills\n\n- `autogpt-agents`: Autonomous AI agent platform for building and deploying continuous agents.\n- `research-skill-creator`: Create, improve and test agent skills for research workflows (paper writing, lab protocols, analysis pipelines, domain databases) that meet…\n- `dspy`: Builds and optimizes language model programs with DSPy (Stanford NLP), using Signatures, modules (Predict, ChainOfThought, ReAct, ProgramOf…\n","# Evolving AI Agents with A-Evolve\n\n## Overview\n\nA-Evolve is universal infrastructure for evolving any AI agent across any domain using any evolution algorithm with zero manual engineering. It represents all evolvable agent state as files (prompts, skills, memory, tools), runs iterative solve-observe-evolve cycles against benchmarks, and uses LLM-driven mutation to improve agent performance automatically.\n\n**Benchmark results** (Claude Opus 4.6):\n- MCP-Atlas: 79.4% (#1)\n- SWE-bench Verified: 76.8% (~#5)\n- Terminal-Bench 2.0: 76.5% (~#7)\n- SkillsBench: 34.9% (#2)\n\n## When to Use A-Evolve\n\n**Use A-Evolve when:**\n- Optimizing agent prompts, skills, or memory against a measurable benchmark\n- Building self-improving agents with automated gating and rollback\n- Evolving domain-specific tool usage and procedures through LLM-driven mutation\n- Running iterative solve-observe-evolve loops to maximize agent performance\n- Needing reproducible, git-versioned evolution history for every change\n\n**Key differentiator**: Other frameworks _build_ agents; A-Evolve _optimizes_ them. It sits on top of any agent framework and makes it better through automated evolution.\n\n**Do NOT use A-Evolve for:**\n- Building multi-agent orchestration from scratch (use CrewAI, LangGraph)\n- One-shot agent tasks with no iteration needed (use LangChain, LlamaIndex)\n- RAG pipeline optimization (use LlamaIndex, Chroma)\n- Prompt-only optimization without skill\u002Fmemory evolution (use DSPy)\n\n## Quick Start\n\n### Installation\n\n```bash\npip install a-evolve                    # Core\npip install a-evolve[anthropic]         # With Claude support\npip install a-evolve[all]               # All providers\n```\n\n### Three-Line Evolution\n\n```python\nimport agent_evolve as ae\n\nevolver = ae.Evolver(agent=\"swe\", benchmark=\"swe-verified\")\nresults = evolver.run(cycles=10)\nprint(f\"Final score: {results.final_score}\")\n```\n\nThis copies the built-in SWE seed workspace, runs 10 evolution cycles against SWE-bench Verified, and returns the optimized agent.\n\n## Core Concepts\n\n### The Agent Workspace\n\nAll evolvable state lives as files in a workspace directory:\n\n```\nmy-agent\u002F\n├── manifest.yaml          # Metadata + entrypoint\n├── prompts\u002F\n│   ├── system.md          # Main system prompt (evolved)\n│   └── fragments\u002F         # Modular prompt pieces\n├── skills\u002F\n│   └── skill-name\u002F\n│       └── SKILL.md       # Reusable procedure with frontmatter\n├── memory\u002F\n│   ├── episodic.jsonl     # Lessons from failures\n│   └── semantic.jsonl     # General knowledge\n├── tools\u002F\n│   ├── registry.yaml      # Tool manifest\n│   └── tool_name.py       # Tool implementations\n└── evolution\u002F             # Managed by engine (metrics, history)\n```\n\n### The Evolution Loop\n\nEach cycle follows five phases:\n\n1. **Solve** — Agent processes a batch of tasks from the benchmark\n2. **Observe** — Benchmark evaluates trajectories, producing (task, trajectory, feedback) triples\n3. **Evolve** — Evolution engine mutates workspace files based on observations\n4. **Gate** — Validate mutations (git snapshot before\u002Fafter for rollback)\n5. **Reload** — Agent reinitializes from evolved filesystem state\n\n### Three Pluggable Interfaces\n\n```python\n# 1. Agent — implements solve()\nclass MyAgent(ae.BaseAgent):\n    def solve(self, task: ae.Task) -> ae.Trajectory:\n        # Domain-specific solving logic\n        return ae.Trajectory(task_id=task.id, output=result, steps=steps)\n\n# 2. Benchmark — implements get_tasks() and evaluate()\nclass MyBenchmark(ae.BenchmarkAdapter):\n    def get_tasks(self, split=\"train\", limit=None) -> list[ae.Task]:\n        return [ae.Task(id=\"1\", input=\"...\")]\n\n    def evaluate(self, task: ae.Task, trajectory: ae.Trajectory) -> ae.Feedback:\n        return ae.Feedback(success=True, score=0.95, detail=\"Passed\")\n\n# 3. Engine — implements step()\nclass MyEngine(ae.EvolutionEngine):\n    def step(self, workspace, observations, history, trial):\n        # Mutate workspace based on observations\n        return ae.StepResult(mutated=True, summary=\"Updated prompts\")\n```\n\n## Workflow 1: Evolve an Existing Agent\n\n**Use when**: You have a working agent and want to optimize it against a benchmark.\n\n**Critical Requirements:**\n- [ ] Agent implements `BaseAgent.solve()` returning `Trajectory`\n- [ ] Benchmark implements `BenchmarkAdapter` with `get_tasks()` and `evaluate()`\n- [ ] Seed workspace has `manifest.yaml` with entrypoint and evolvable layers\n- [ ] System prompt exists at `prompts\u002Fsystem.md`\n- [ ] Workspace is a git repo (run `git init && git add -A && git commit -m \"init\"`)\n\n### Steps\n\n```python\nimport agent_evolve as ae\n\n# Configure evolution parameters\nconfig = ae.EvolveConfig(\n    batch_size=10,           # Tasks per solve round\n    max_cycles=20,           # Maximum evolution iterations\n    evolve_prompts=True,     # Mutate system prompt\n    evolve_skills=True,      # Discover and refine skills\n    evolve_memory=True,      # Build episodic memory\n    evolver_model=\"us.anthropic.claude-opus-4-6-v1\",\n)\n\n# Point to your agent workspace and benchmark\nevolver = ae.Evolver(\n    agent=\".\u002Fmy-agent-workspace\",\n    benchmark=\"swe-verified\",     # Or custom BenchmarkAdapter instance\n    config=config,\n)\n\n# Run evolution\nresults = evolver.run(cycles=10)\n\n# Inspect results\nprint(f\"Cycles completed: {results.cycles_completed}\")\nprint(f\"Final score: {results.final_score}\")\nprint(f\"Converged: {results.converged}\")\nfor cycle_num, score in enumerate(results.score_history):\n    print(f\"  Cycle {cycle_num + 1}: {score:.3f}\")\n```\n\n### Post-Evolution\n\nThe workspace is now optimized. Inspect what changed:\n\n```bash\ncd my-agent-workspace\ngit log --oneline              # See evo-1, evo-2, ... tags\ngit diff evo-1 evo-10          # Compare first and last evolution\ncat prompts\u002Fsystem.md          # Read evolved prompt\nls skills\u002F                     # See discovered skills\n```\n\n## Workflow 2: Add a Custom Benchmark\n\n**Use when**: You want to evolve agents on your own domain-specific tasks.\n\n**Critical Requirements:**\n- [ ] Define task format (inputs, expected outputs)\n- [ ] Implement scoring logic (0.0–1.0 scale)\n- [ ] Prepare task dataset (train + holdout split)\n\n### Steps\n\n```python\nimport agent_evolve as ae\n\nclass CodeReviewBenchmark(ae.BenchmarkAdapter):\n    \"\"\"Evaluate agents on code review quality.\"\"\"\n\n    def get_tasks(self, split=\"train\", limit=None):\n        tasks = load_review_dataset(split)\n        if limit:\n            tasks = tasks[:limit]\n        return [\n            ae.Task(id=t[\"id\"], input=t[\"diff\"], metadata={\"expected\": t[\"comments\"]})\n            for t in tasks\n        ]\n\n    def evaluate(self, task, trajectory):\n        expected = task.metadata[\"expected\"]\n        actual = trajectory.output\n        precision, recall = compute_review_metrics(expected, actual)\n        f1 = 2 * precision * recall \u002F (precision + recall + 1e-9)\n        return ae.Feedback(\n            success=f1 > 0.7,\n            score=f1,\n            detail=f\"P={precision:.2f} R={recall:.2f} F1={f1:.2f}\",\n        )\n\n# Use with any agent\nevolver = ae.Evolver(agent=\".\u002Fmy-agent\", benchmark=CodeReviewBenchmark())\nresults = evolver.run(cycles=5)\n```\n\n## Workflow 3: Create a Custom Evolution Engine\n\n**Use when**: The default LLM-driven mutation doesn't suit your domain.\n\n### Steps\n\n```python\nimport agent_evolve as ae\n\nclass RuleBasedEngine(ae.EvolutionEngine):\n    def step(self, workspace, observations, history, trial):\n        failures = [o for o in observations if not o.feedback.success]\n        if not failures:\n            return ae.StepResult(mutated=False, summary=\"No failures to address\")\n\n        # Analyze failure patterns\n        error_types = categorize_errors(failures)\n        prompt = workspace.read_prompt()\n\n        # Append learned rules to prompt\n        new_rules = generate_rules(error_types)\n        workspace.write_prompt(prompt + \"\\n\" + new_rules)\n\n        return ae.StepResult(\n            mutated=True,\n            summary=f\"Added {len(new_rules)} rules from {len(failures)} failures\",\n        )\n\nevolver = ae.Evolver(\n    agent=\".\u002Fmy-agent\",\n    benchmark=\"my-benchmark\",\n    engine=RuleBasedEngine(),\n)\n```\n\n## Built-in Components\n\n### Seed Agents\n\n| Agent | Domain | Model | Key Feature |\n|-------|--------|-------|-------------|\n| `swe` | SWE-bench | Claude Opus 4.6 | Verify-fix loop, skill proposals |\n| `terminal` | Terminal-Bench | Claude Sonnet 4 | Concurrent timeout, env discovery |\n| `mcp` | MCP-Atlas | Claude Opus 4.6 | MCP server integration |\n\n### Benchmarks\n\n| Name | Domain | Metric |\n|------|--------|--------|\n| `swe-verified` | Code patching | Pass rate |\n| `mcp-atlas` | Tool calling | Accuracy |\n| `terminal2` | Shell tasks | Pass rate |\n| `skill-bench` | Multi-step procedures | Accuracy |\n| `arc-agi-3` | Interactive games | RHAE score |\n\n### Evolution Algorithms\n\n| Algorithm | Strategy | Best For |\n|-----------|----------|----------|\n| A-Evolve\u002FSkillForge | LLM-driven workspace mutation | General-purpose |\n| Guided Synthesis | Memory-first, curated skills | Skill discovery |\n| Adaptive Evolution | Reward tracking, filtered observations | Fine-grained control |\n| Adaptive Skill | Skill-centric refinement | Skill-heavy domains |\n\n## Configuration Reference\n\n```python\nae.EvolveConfig(\n    batch_size=10,              # Tasks per solve round\n    max_cycles=20,              # Max evolution iterations\n    holdout_ratio=0.2,          # Test set split for gating\n    evolve_prompts=True,        # Mutate system prompts\n    evolve_skills=True,         # Discover\u002Frefine skills\n    evolve_memory=True,         # Build episodic memory\n    evolve_tools=False,         # Mutate tool implementations\n    trajectory_only=False,      # Hide scores from evolver\n    evolver_model=\"us.anthropic.claude-opus-4-6-v1\",\n    evolver_max_tokens=16384,\n    egl_threshold=0.05,         # Convergence epsilon\n    egl_window=3,               # Cycles for plateau detection\n)\n```\n\n**Convergence**: Evolution stops early when score improvement is less than `egl_threshold` over the last `egl_window` cycles.\n\n## Skill Format\n\nSkills are reusable procedures discovered and refined during evolution:\n\n```markdown\n---\nname: verify-edge-cases\ndescription: \"TRIGGER when: checking boundary conditions. DO NOT TRIGGER: for happy-path tests.\"\n---\n\n## Pattern\nTest all falsy-but-valid values: 0, False, \"\", [], {}\n\n## Process\n1. List all input boundaries\n2. Run each against the implementation\n3. Check both output AND side effects\n```\n\nSkills accumulate in the workspace `skills\u002F` directory. The evolver curates them: ACCEPT new skills, MERGE overlapping ones, SKIP redundant proposals. Target: 5–10 broad skills, not 30 narrow ones.\n\n## Common Issues\n\n### Evolution score plateaus early\n\n**Cause**: Batch size too small or evolver doesn't see enough failure diversity.\n**Fix**: Increase `batch_size` (try 15–20) and ensure benchmark tasks cover diverse failure modes. Set `trajectory_only=False` so the evolver sees scores.\n\n### Agent workspace grows too large\n\n**Cause**: Skill library bloat from accepting every proposal.\n**Fix**: The default SkillForge engine curates skills automatically. If using a custom engine, implement merging logic to consolidate overlapping skills.\n\n### Git conflicts during evolution\n\n**Cause**: Multiple evolution runs on the same workspace.\n**Fix**: Each `evolver.run()` should operate on its own workspace copy. Use `Evolver(agent=\"seed-name\")` to auto-copy the seed each time.\n\n### LLM provider errors during evolution\n\n**Cause**: Rate limits or authentication issues with the evolver model.\n**Fix**: Check `evolver_model` config. For Bedrock, ensure AWS credentials are configured. For Anthropic, set `ANTHROPIC_API_KEY`.\n\n### Custom agent not picking up evolved state\n\n**Cause**: Agent doesn't implement `reload_from_fs()`.\n**Fix**: Override `reload_from_fs()` in your `BaseAgent` subclass to re-read prompts, skills, and memory from the workspace after each evolution cycle.\n\n## Usage Instructions for Agents\n\nWhen this skill is loaded:\n\n1. **Read this entire file** before implementing any evolution workflow\n2. **Start with the Quick Start** — get a minimal evolution running before customizing\n3. **Use built-in seeds when possible** — `\"swe\"`, `\"terminal\"`, `\"mcp\"` have battle-tested configurations\n4. **Always initialize git** in custom workspaces before running evolution\n5. **Check convergence settings** — default `egl_threshold=0.05` with `egl_window=3` may be too aggressive for your domain\n6. **Inspect evolved state** after each run — read `prompts\u002Fsystem.md` and `skills\u002F` to understand what the evolver learned\n\n**Pro Tips:**\n- Set `trajectory_only=False` (default) so the evolver sees scores — this accelerates learning\n- Start with `batch_size=10` and adjust based on task diversity\n- Use `holdout_ratio=0.2` to prevent overfitting to training tasks\n- After evolution, `git diff evo-1 evo-N` shows the cumulative effect of all mutations\n- If the evolver isn't finding skills, enrich `feedback.detail` strings with specific failure reasons\n\n**Warning Signs:**\n- Score oscillating between cycles → benchmark evaluation may be non-deterministic\n- Skills directory growing past 15+ skills → engine isn't merging\u002Fcurating properly\n- Prompt growing past 10K chars → evolution is appending without refactoring\n- `converged=True` after 2-3 cycles → increase `egl_window` and decrease `egl_threshold`\n\n## References\n\n- **Architecture deep dive**: See [references\u002Farchitecture.md](references\u002Farchitecture.md)\n- **API reference**: See [references\u002Fapi.md](references\u002Fapi.md)\n- **Step-by-step tutorials**: See [references\u002Ftutorials.md](references\u002Ftutorials.md)\n- **Real-world examples**: See [references\u002Fexamples.md](references\u002Fexamples.md)\n- **GitHub issues & solutions**: See [references\u002Fissues.md](references\u002Fissues.md)\n- **Design patterns**: See [references\u002Fdesign-patterns.md](references\u002Fdesign-patterns.md)\n- **Release history**: See [references\u002Freleases.md](references\u002Freleases.md)\n\n## Related skills\n\n- `autogpt-agents`: Autonomous AI agent platform for building and deploying continuous agents.\n- `research-skill-creator`: Create, improve and test agent skills for research workflows (paper writing, lab protocols, analysis pipelines, domain databases) that meet…\n- `dspy`: Builds and optimizes language model programs with DSPy (Stanford NLP), using Signatures, modules (Predict, ChainOfThought, ReAct, ProgramOf…\n",{"name":5,"license":15,"metadata":50,"description":7},{"tags":51,"version":52,"category":53,"maintainer":54,"contributor":55,"dependencies":56},"Agent Evolution, Self-Improving Agents, Prompt Optimization, LLM, Benchmark Evaluation, Skill Discovery, Agentic AI","1.0.0","llm-applications","Kalaris Labs","A-EVO Lab","a-evolve>=0.1.0, pyyaml>=6.0","main","2b63f856ce19c2a797929cacabd9e0fc936812fa","plugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fevolving-ai-agents",491,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins","https:\u002F\u002Fhol.org\u002Fplugins\u002Fbest-codex-plugins","https:\u002F\u002Fgithub.com\u002Fhashgraph-online","https:\u002F\u002Fhol.org","Open-source standards and developer tools for interoperable AI agents: discovery, identity, communication, payments, privacy and security.","2026-11-14 14:06:13",{"source":8,"skillName":5,"commands":68,"prompt":78,"zipAvailable":79},[69,72,75],{"tool":70,"command":71},"npx","npx skills add hashgraph-online\u002Fawesome-codex-plugins --skill evolving-ai-agents",{"tool":73,"command":74},"bunx","bunx skills add hashgraph-online\u002Fawesome-codex-plugins --skill evolving-ai-agents",{"tool":76,"command":77},"pnpm","pnpm dlx skills add hashgraph-online\u002Fawesome-codex-plugins --skill evolving-ai-agents","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fevolving-ai-agents\u002FSKILL.md",true,[81,87,91,95,99,103,107,111],{"path":82,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":85,"sourceHtmlUrl":86},"references\u002Fapi.md","REFERENCE","参考文档",15810,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fevolving-ai-agents\u002Freferences\u002Fapi.md",{"path":88,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":89,"sourceHtmlUrl":90},"references\u002Farchitecture.md",15505,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fevolving-ai-agents\u002Freferences\u002Farchitecture.md",{"path":92,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":93,"sourceHtmlUrl":94},"references\u002Fdesign-patterns.md",15192,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fevolving-ai-agents\u002Freferences\u002Fdesign-patterns.md",{"path":96,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":97,"sourceHtmlUrl":98},"references\u002Fexamples.md",10015,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fevolving-ai-agents\u002Freferences\u002Fexamples.md",{"path":100,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":101,"sourceHtmlUrl":102},"references\u002Fissues.md",16411,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fevolving-ai-agents\u002Freferences\u002Fissues.md",{"path":104,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":105,"sourceHtmlUrl":106},"references\u002FREADME.md",27098,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fevolving-ai-agents\u002Freferences\u002FREADME.md",{"path":108,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":109,"sourceHtmlUrl":110},"references\u002Freleases.md",4561,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fevolving-ai-agents\u002Freferences\u002Freleases.md",{"path":112,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":113,"sourceHtmlUrl":114},"references\u002Ftutorials.md",23161,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fevolving-ai-agents\u002Freferences\u002Ftutorials.md",[116,125,133,141,149,157],{"skillNo":117,"name":118,"nameZh":6,"description":119,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":120,"sourceHtmlUrl":121,"categories":122,"keywords":123,"publishedAt":124},"01M7DV332YQMGD8WTRJ9DZQXTB","worktable-review-with-annotations","Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":126,"name":127,"nameZh":6,"description":128,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":129,"sourceHtmlUrl":130,"categories":131,"keywords":132,"publishedAt":124},"01M7DV2YGHCZVBEB1AHYB6CGHE","worktable-find-and-synthesize-context","Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FSKILL.md",[],[],{"skillNo":134,"name":135,"nameZh":6,"description":136,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":137,"sourceHtmlUrl":138,"categories":139,"keywords":140,"publishedAt":124},"01M7DV2TQN1H11ME2SAF9MXN7V","worktable-create-or-update-docs","Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FSKILL.md",[],[],{"skillNo":142,"name":143,"nameZh":6,"description":144,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":145,"sourceHtmlUrl":146,"categories":147,"keywords":148,"publishedAt":124},"01M7DV2NE452NEA8TXATKSNAJH","worktable-create-or-manage-records","Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FSKILL.md",[],[],{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":153,"sourceHtmlUrl":154,"categories":155,"keywords":156,"publishedAt":124},"01M7DV2HENRBR2KSCVM064WH0Y","worktable-create-or-manage-interactive-html","Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FSKILL.md",[],[],{"skillNo":158,"name":159,"nameZh":6,"description":160,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":161,"sourceHtmlUrl":162,"categories":163,"keywords":164,"publishedAt":124},"01M7DV2CADR5R7RQFFYPNAGR9Y","worktable-collaborate-threads","Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FSKILL.md",[],[]]