Evolving Ai Agents

# A-Evolve API Reference

## Top-Level Module: `agent_evolve`

```python
import agent_evolve as ae
```

### `ae.Evolver`

Main entry point for running evolution.

```python
class Evolver:
    def __init__(
        self,
        agent: str | BaseAgent,
        benchmark: str | BenchmarkAdapter,
        config: EvolveConfig | None = None,
        engine: EvolutionEngine | None = None,
        workspace_dir: str | None = None,
    ): ...

    def run(self, cycles: int | None = None) -> EvolutionResult: ...
```

**Parameters**:
- `agent`: One of:
  - Built-in seed name: `"swe"`, `"terminal"`, `"mcp"`
  - Path to workspace directory: `"./my-agent"`
  - `BaseAgent` instance
- `benchmark`: One of:
  - Built-in name: `"swe-verified"`, `"mcp-atlas"`, `"terminal2"`, `"skill-bench"`, `"arc-agi-3"`
  - `BenchmarkAdapter` instance
- `config`: Evolution configuration. Defaults to `EvolveConfig()`.
- `engine`: Custom evolution engine. Defaults to `AEvolveEngine`.
- `workspace_dir`: Override working directory for evolved state.

**Resolution logic**:
- String agent names are matched against built-in seed workspaces, then treated as paths
- Seed workspaces are copied to a working directory before evolution begins
- Manifest validation ensures `entrypoint` and `evolvable_layers` are present

---

## Core Types: `agent_evolve.types`

### `Task`

```python
@dataclass
class Task:
    id: str                    # Unique identifier
    input: str                 # Task description or input data
    metadata: dict = field(default_factory=dict)  # Extra context
```

### `Trajectory`

```python
@dataclass
class Trajectory:
    task_id: str               # Matches Task.id
    output: str                # Agent's final answer/patch/action
    steps: list[dict] = field(default_factory=list)  # Tool calls
    conversation: list[dict] = field(default_factory=list)  # Full messages
```

### `Feedback`

```python
@dataclass
class Feedback:
    success: bool              # Binary pass/fail
    score: float               # 0.0 to 1.0 continuous score
    detail: str = ""           # Human-readable explanation
    raw: dict = field(default_factory=dict)  # Benchmark-specific data
```

### `Observation`

```python
@dataclass
class Observation:
    task: Task
    trajectory: Trajectory
    feedback: Feedback
```

### `SkillMeta`

```python
@dataclass
class SkillMeta:
    name: str                  # Unique skill identifier
    description: str           # What it does and when to trigger
    path: str                  # Filesystem path to SKILL.md
```

### `StepResult`

```python
@dataclass
class StepResult:
    mutated: bool              # Whether workspace was changed
    summary: str               # Description of changes
    metadata: dict = field(default_factory=dict)
```

### `CycleRecord`

```python
@dataclass
class CycleRecord:
    cycle: int                       # Cycle number
    score: float                     # Average score this cycle
    mutated: bool                    # Whether workspace was changed
    engine_name: str = ""            # Name of the engine used
    summary: str = ""                # What the engine did
    observation_batch: str = ""      # Path to observation JSONL
    metadata: dict = field(default_factory=dict)
```

### `EvolutionResult`

```python
@dataclass
class EvolutionResult:
    cycles_completed: int
    final_score: float
    score_history: list[float] = field(default_factory=list)  # Score per cycle
    converged: bool = False
    details: dict = field(default_factory=dict)
```

---

## Protocol: `agent_evolve.protocol.base_agent`

### `BaseAgent`

```python
class BaseAgent:
    def __init__(self, workspace_dir: str | Path): ...

    def solve(self, task: Task) -> Trajectory:
        """Override: solve a single task and return trajectory."""
        raise NotImplementedError

    def reload_from_fs(self):
        """Re-read prompts, skills, memory from workspace after evolution."""
        ...

    def export_to_fs(se