_____ ______ _____
/\ | __ \| ____|/ ____|
/ \ | |__) | |__ | (___
/ /\ \ | _ /| __| \___ \
/ ____ \| | \ \| |____ ____) |
/_/ \_\_| \_\______|_____/
ARES — Agent Runtime & Evolution System.
Build resilient, self-evolving AI agents in Go. Unified SDK, DAG workflow, chaos engineering, MCP support.
Runtime Evolution: ARES continuously evolves its DAG topology, scheduler, knowledge planner, and recovery strategies — all in production, without restarts. LLM is a participant in evolution, not the leader.
package main
import "github.com/Timwood0x10/ares/sdk"
func main() {
rt := sdk.MustNew(sdk.WithOllama("llama3.2"))
defer rt.Close()
agent := rt.NewAgent("assistant")
result, _ := agent.Run(ctx, "Say hello")
println(result.Output)
}Install the CLI:
go install github.com/Timwood0x10/ares/cmd/ares@latest
ares doctor
ares run -c ares.yaml "What is Go?"Or run examples directly:
git clone https://github.com/Timwood0x10/ares
cd ares
make quickstart # go run examples/quickstart
make examples # build all 24 examples| Feature | Description |
|---|---|
| Unified SDK | Single sdk.MustNew() API for LLM, tools, memory, evolution |
| Runtime Evolution | Genome + Diff Engine + Coordinator evolve DAG, scheduler, planner, recovery in production |
| Strategy GA | Population-based strategy optimization — NSGA-II multi-objective, steady-state, uniform/two-point/segment crossover, 6 mutation types |
| Evidence-Driven | Every runtime event (flight, chaos, fitness) feeds into evolution decisions |
| DAG Workflow | Dynamic graphs with conditional branching and recovery |
| Chaos Resilient | Fault injection, failover, survival testing, self-healing |
| Memory | Session context, task distillation, vector similarity search |
| MCP Ready | Connect any Model Context Protocol server for tools and data |
| Multi-Agent | Leader/sub orchestration with automatic failover |
| Observability | OpenTelemetry traces, structured logs, Prometheus metrics |
Start from "I want to use capability X" and find the code in one step.
ares serve # Start full agent monitoring (LLM + MCP + dashboard)
ares agent list # List all registered agents
ares arena run/validate/list/serve/survival/inspect # Chaos engineering scenarios
ares evolution run/status # Runtime evolution
ares flight inspect/replay # Inspect and replay task recordings
ares workflow run <id> <input> # Execute a workflow
ares knowledge build <goal> # Build a knowledge graph (via HTTP API)
ares mcp-null serve # Start minimal MCP null server (stdio)
ares db migrate/setup-test/create-table/check-rls # Database management
ares init # Scaffold a new project (main.go + ares.yaml)
ares run # Run agent from config file
ares bench # Quick performance benchmark
ares doctor # Diagnose environment (LLM key, Ollama, Git)
ares version # Show versionrt := sdk.MustNew(
sdk.WithOpenAI("gpt-4o-mini"), // or WithOllama, WithAnthropic
sdk.WithDefaultMemory(), // session history
sdk.WithEvolution(), // strategy evolution
sdk.WithMCP(sdk.MCPConn{ // MCP server tools
Name: "my-server", Command: "/path/to/server", Args: []string{"serve"},
}),
)
defer rt.Close()
// Agent with tools and human-in-the-loop.
agent := rt.NewAgent("assistant",
sdk.WithInstruction("You are helpful."),
sdk.WithTools(calculatorTool, weatherTool),
sdk.WithHumanInput(approveFn),
)
result, _ := agent.Run(ctx, "Calculate 15*23")
// Streaming response.
ch, _ := agent.Stream(ctx, "Tell me a story")
for chunk := range ch { fmt.Print(chunk.Content) }
// Multi-agent team.
team := rt.NewTeam("project", leaderAgent, []*Agent{memberAgent})
teamResult, _ := team.Run(ctx, "Research and write")See examples/README.md for 9 hands-on examples.
Deep dives into ARES internals:
graph TB
User["User / CLI"] --> SDK
subgraph SDK ["SDK Layer (sdk/)"]
RT["Runtime<br/>MustNew / New"]
A["Agent<br/>Run / Stream"]
T["Team<br/>Multi-Agent"]
CFG["Config<br/>YAML + Options"]
EV["Evolve()<br/>GA Strategy Evolution"]
end
SDK --> LLM
SDK --> Tools
SDK --> Memory
SDK --> Evo
subgraph LLM ["LLM Providers"]
OAI["OpenAI"]
OLL["Ollama"]
ANTH["Anthropic"]
OR["OpenRouter"]
end
subgraph Tools ["Tool System"]
BT["Built-in<br/>calculator, search..."]
MCP["MCP Servers<br/>Stdio / SSE"]
CT["Custom Tools<br/>ToolFunc"]
end
subgraph Memory ["Memory System"]
SES["Session Context"]
DIST["Task Distillation"]
VEC["Vector Search"]
CONF["Config<br/>max_history, session_ttl..."]
MP["Memory Patch Executor<br/>Runtime Evolution"]
end
subgraph Evo ["GA Evolution Engine"]
direction TB
POP["Population<br/>N individuals"]
SEL["7 Selection Operators<br/>tournament/rank/nsga2..."]
CROSS["3 Crossover Types<br/>uniform/two_point/segment"]
MUT["6 Mutation Types<br/>param/swap/inversion/scramble..."]
SCORE["Experience-Guided Scoring<br/>multi-objective"]
SS["Steady-State GA<br/>online learning mode"]
SHARE["Fitness Sharing<br/>SelectionScore preservation"]
end
POP --> SEL --> CROSS --> MUT --> SCORE
SCORE --> POP
SS -.-> POP
subgraph RuntimeEvo ["Runtime Evolution Pipeline"]
direction TB
TICKER["Background Ticker<br/>5min interval"]
SCHED["Scheduler<br/>OnAgentEnd callback"]
ADAPTER["GenomePopulationAdapter<br/>Run()"]
GENOME["Genomes<br/>Workflow / Scheduler / Knowledge<br/>Recovery / Planner / Memory"]
DIFF["Diff Engine<br/>4 Differs"]
COORD["Coordinator<br/>Apply / Reject / Delay"]
EXEC["Executors<br/>Graph / Recovery / Knowledge / Memory"]
STORE["Strategy Store<br/>Active Strategy"]
AGENT["Live Agent<br/>consume evolved params"]
end
TICKER --> ADAPTER
SCHED --> ADAPTER
ADAPTER --> GENOME
GENOME --> DIFF
DIFF --> COORD
COORD --> EXEC
ADAPTER --> STORE
STORE --> AGENT
Evo --> ADAPTER
AGENT --> LLM
AGENT --> Tools
AGENT --> Memory
subgraph CLI ["CLI (cmd/ares/)"]
INIT["ares init"]
RUN["ares run"]
BENCH["ares bench"]
DOCTOR["ares doctor"]
EVO["ares evolution"]
ARENA["ares arena"]
end
subgraph EX ["Examples"]
QS["01 Quickstart"]
TC["02 Tool Calling"]
DAG["03 DAG Workflow"]
MA["04 Multi-Agent"]
EVO_DEMO["05 Evolution Demo"]
CHAOS["06 Chaos Resilience"]
HIL["07 Human-in-Loop"]
GA_FULL["10 GA Full Evolution"]
end
style SDK fill:#1e3a5f,stroke:#3b82f6,color:#fff
style LLM fill:#1a2332,stroke:#64748b
style Tools fill:#1a2332,stroke:#64748b
style Memory fill:#1a2332,stroke:#64748b
style Evo fill:#1a2332,stroke:#64748b
style RuntimeEvo fill:#2d1b69,stroke:#8b5cf6,color:#fff
style CLI fill:#2d1b69,stroke:#8b5cf6,color:#fff
style EX fill:#1a3a2a,stroke:#22c55e
sequenceDiagram
participant U as User
participant S as SDK
participant A as Agent
participant GA as GA Engine
participant C as Coordinator
participant E as Executors
participant M as Memory
U->>S: rt.Evolve(agent, task)
S->>GA: Create Population(10)
loop 3 generations
GA->>GA: ScoreAgents(execution results)
GA->>GA: Evolve(selection → crossover → mutation)
end
GA->>S: BestStrategy params
S->>A: applyEvolvedParams(tool_selector, search_depth, scheduler...)
Note over S,A: Strategy params applied to live agent
U->>A: agent.Run(task)
A->>M: Read strategy, load tools
A->>A: Execute with evolved params
A->>C: Submit evidence
C->>E: Apply patches if needed
Note over GA,C: Background: ticker + scheduler trigger evolution
loop Every 5min
GA->>GA: Run evolution cycle
GA->>C: submitToCoordinator(patches)
C->>E: Evaluate & Apply
end
| Recipe | Code |
|---|---|
| Chat Agent | 20-line conversational agent |
| Tool Calling | Custom tools for LLM function calling |
| Multi-Agent | Leader/member team orchestration |
| Memory | Persistent conversation context |
| Coding Agent | Code generation with specialized instructions |
| Code Review | Automated PR review |
| GitHub Agent | Issue and PR automation |
ARES's runtime evolution system is evidence-driven: every execution, fault, and insight produces Evidence, which feeds into the evolution cycle. The system evolves DAG topology, scheduler selection, knowledge planner parameters, and recovery strategies — all in production, without restarts.
Execution → Evidence → Genome → Candidate → Diff Engine → RuntimePatch → Coordinator → Apply
| Component | Role | Sources |
|---|---|---|
| 5 Genomes | Generate candidate configurations via mutation + crossover | workflow, scheduler, knowledge, recovery, prompt |
| 4 Differs | Compare old vs new snapshots → produce RuntimePatches | workflow, knowledge, scheduler, recovery |
| Coordinator | Decides Apply/Reject/Delay for each PatchProposal | GA, Chaos, AKF, LLM, Human, K8s, Rule |
| 3 Executors | Apply patches to live runtime | Graph, Knowledge, Recovery |
| LLM Adapter | Converts natural-language suggestions into PatchProposals | parsed format → Coordinator |
Key design: LLM is a participant, not the leader. The Coordinator treats all 7 PatchSource values equally. No source has privileged access.
=== Runtime Evolution (internal/evolution) ===
BenchmarkWorkflowGenome_Mutate 309k 7.1µs 11.4KB 155 allocs
BenchmarkSchedulerGenome_Mutate 3.3M 0.4µs 719B 15 allocs
BenchmarkKnowledgeGenome_Mutate 2.8M 0.4µs 960B 11 allocs
BenchmarkRecoveryGenome_Mutate 2.2M 0.5µs 1.1KB 21 allocs
BenchmarkDiffEngine_Workflow 2.9M 0.4µs 256B 3 allocs
BenchmarkCoordinator_Evaluate 217M 5.4ns 0B 0 allocs
BenchmarkFullEvolutionCycle 206k 5.3µs 8.0KB 109 allocs
=== Event System (internal/ares_events) ===
BenchmarkMemoryStore_Append 226k 516ns 596B 7 allocs
BenchmarkMemoryStore_AppendBatch 27k 3.96µs 8.4KB 1 alloc
BenchmarkMemoryStore_Read 28k 4.33µs 17.5KB 11 allocs
BenchmarkMemoryStore_ConcurrentAppend 165k 667ns 619B 6 allocs
=== Evaluation Framework (internal/ares_eval) ===
BenchmarkExactMatchEvaluator_Evaluate 39.2M 3.1ns 0B 0 allocs
BenchmarkToolUsageEvaluator_Evaluate 4.2M 28.7ns 0B 0 allocs
BenchmarkAgentTestRunner_RunSingle 372k 315ns 320B 5 allocs
BenchmarkReportGenerator_GenerateMarkdown 33k 3.5µs 4.3KB 76 allocs
BenchmarkLoader_Load 2.5k 47.3µs 34.1KB 601 allocs
=== AKG Knowledge Fabric (internal/knowledge) ===
--- Linkers ---
DecisionLinker (100 objs) 8.4k 15.1µs 10.9KB 295 allocs
ArchitectureLinker (100 objs) 3.7k 34.1µs 102.6KB 85 allocs
TimelineLinker (100 objs) 61.2k 2.01µs 3.1KB 11 allocs
SimilarityLinker (100 objs) 74 1.96ms 3.2MB 20216 allocs
--- Compiler ---
DefaultCompiler Prompt (100 nodes) 2.6k 45.6µs 73.3KB 819 allocs
DefaultCompiler All Formats (100) 478 263.7µs 365.2KB 3476 allocs
--- Memory Store ---
Store_Save 213k 503ns 586B 11 allocs
Store_Get 2.09M 56ns 13B 1 alloc
Store_QueryByType 22.8k 5.16µs 4.5KB 11 allocs
Store_Search 1.3k 77.2µs 69.4KB 1514 allocs
--- Pipeline ---
DefaultNormalizer_Normalize 254k 476ns 607B 9 allocs
--- Planner ---
KnowledgePlanner_Plan 170k 720ns 928B 14 allocs
--- Retriever (end-to-end) ---
Retrieve (100 objs) 16 10.8ms 23.8MB 132959 allocs
ares evolution status # Show genomes, differs, coordinator state
ares evolution run # Run one evolution cyclego run examples/11-knowledge-import/ --dir ./notes # Ingest markdown into pgvector
go run examples/11-knowledge-import/ --ask "question" # RAG query against KB
go run examples/11-knowledge-import/ --evolve "task" # GA evolution on import
go run examples/11-knowledge-import/ --chat # Interactive chat with tools
go run examples/11-knowledge-import/ --team --dir ./notes # Multi-agent import
go run examples/11-knowledge-import/ --chaos-fail 0.3 # With fault injection
go run examples/11-knowledge-import/akg/ # Build AKG from KB
go run examples/runtime_evolution/basic/ # Full end-to-end evolution demo
go run examples/runtime_evolution/knowledge/ # Knowledge parameter evolution
go run examples/runtime_evolution/full/ # All 4 genomes + real executorsBeyond runtime-level evolution, ARES includes a strategy-level Genetic Algorithm that optimizes agent inference parameters (temperature, top_k, prompt templates, tool configs) through population-based search. The system evolves a population of strategies across generations using selection, crossover, and mutation, with zero-cost background evolution cycles.
| Feature | Description |
|---|---|
| NSGA-II Multi-Objective | 4 default dimensions (success_rate 0.40, quality 0.25, cost 0.20, latency 0.15) with direction-aware Pareto dominance |
| Steady-State GA | Configurable replace rate (0.1–0.5, default 0.3) — replaces only the worst individuals each generation |
| Score / SelectionScore | Canonical score preserved; selection score adjusted by fitness sharing for diversity |
| Fitness Sharing | 3 strategies — full O(n²), reservoir sampling, spatial grid index (for >500 individuals) |
| 3 Crossover Types | Uniform (per-gene), Two-Point (swap segment), Segment (contiguous block) |
| 6 Mutation Types | Parameter, Prompt, Tool, Swap, Inversion, Scramble |
| Evolution Callbacks | OnGeneration / OnFitness / OnMutation / OnCrossover |
| Termination | MaxGenerations + TargetFitness (stops when BestEverScore ≥ target) |
| Generation History | Per-generation snapshots with metadata |
| Experience System | 3-tier pipeline: ToolCallRecord → RawExperience → NormalizedExperience → EvolutionHint → GuidanceProvider |
=== GA Genome (internal/ares_evolution/genome) ===
CrossoverUniform (10 params) 500k 2.4µs 2.9KB 29 allocs
CrossoverUniform (100 params) 68k 17.7µs 21.0KB 36 allocs
TruncationSelection (pop=100) 200k 6.2µs — —
TournamentSelection (pop=50,k=2) 380k 3.2µs — —
RouletteWheelSelection (pop=100) 410k 2.9µs — —
Evolve_OneGeneration (pop=10) 437k 281ns 344B 6 allocs
Evolve_MultipleGenerations (100) 3.7k 28µs 34.4KB 600 allocs
ApplyFitnessSharing (pop=100) 88 1.35ms 540KB 106 allocs
RealWorldEvolution (100 gen) 12 9.87ms 4.43MB 59894 allocs
go run examples/10-ga-full-evolution/main.go # Full GA evolution demo
go run examples/05-evolution-demo/main.go # Pre-NSGA-II evolution demoApache 2.0
ARES's genetic algorithm implementation was inspired by the design and features of PyGAD — the Python genetic algorithm library by Ahmed F. Gad. PyGAD's architecture, operator design, and multi-objective optimization capabilities served as a valuable reference for building the GA engine in this project.
We recommend PyGAD for anyone looking for a mature, well-documented GA library in Python:
- GitHub: github.com/ahmedfgad/GeneticAlgorithmPython
- Documentation: pygad.readthedocs.io
Additional GA concepts and terminology follow the standard definitions from the Genetic Algorithm article on Wikipedia.