Topologies¶

A topology is the coordination pattern for a run. It determines how work gets split up, how agents execute, and how results are verified. You choose a topology when you create a run.

If you are not sure which one to use, start with dag. It handles most tasks well.

epsilon runs create --topology dag --task "Build a URL shortener service"

Choosing a topology¶

I want to...	Use
Split a task into parallel steps with QA	`dag`
Break a large task into isolated teams	`tree`
Force work through ordered stages	`pipeline`
Retry and re-plan adaptively	`supervisor`
Let workers pull tasks from a queue	`work_queue`
Fan out over a large list of independent items	`sharded_queue`
Fan out and then merge results	`map_reduce`
Optimize an agent implementation over a task family	`population_search`
Let Epsilon pick for me	`auto`

Free-form vs. manifest-backed¶

The topologies split into two groups:

Free-form (dag, tree, pipeline, supervisor): You give Epsilon a task description. An LLM decomposes it into steps. These require model credentials when using the built-in agent.

Manifest-backed (work_queue, sharded_queue, map_reduce): You give Epsilon a JSON manifest that explicitly lists the work items. These can run with or without an LLM, depending on your implementation.

population_search is its own category — it optimizes a candidate agent codebase against a measured task family.

dag¶

The default for most tasks. Decomposes work into a dependency-ordered DAG, executes nodes in parallel waves, runs QA, assigns failures back to responsible agents, and repeats.

Good for: general multi-step tasks, parallel file or feature work, anything that benefits from automated QA.

epsilon runs create --topology dag \
  --task "Build a REST API with user auth and a SQLite backend"

How it works:

An LLM decomposes the task into a typed DAG
Nodes are executed in dependency-ordered waves
A QA agent validates the result
Failures are assigned back to responsible agents
Steps 2–4 repeat until QA passes or MAX_WAVES is exhausted

The number of QA/fix cycles is controlled by MAX_WAVES (default: 3).

tree¶

For larger tasks that benefit from team-based isolation. Decomposes work into 2–8 teams, each with its own git branch and sub-orchestrator. Teams run in parallel, then branches merge and integration QA runs on the merged result.

Good for: product-scale tasks, clear team-style splits, work that benefits from branch isolation.

epsilon runs create --topology tree \
  --task "Build an e-commerce platform with catalog, cart, checkout, and admin"

How it works:

An LLM decomposes the task into teams
Each team gets its own git branch
Teams execute in parallel (each running their own DAG internally)
All branches merge
Integration QA runs on the merged result
Fix cycles run if needed (controlled by INTEGRATION_WAVES)

pipeline¶

For tasks where stages must happen in order. Each stage completes before the next one starts.

Good for: sequential workflows, extraction → transform → review flows, staged delivery.

epsilon runs create --topology pipeline \
  --task "Build a notes API with staged delivery"

How it works:

An LLM decomposes the task into ordered stages
Stage 1 executes
Stage 2 executes (can read stage 1's outputs)
Continues through all stages
QA runs at the end

supervisor¶

Like pipeline, but after each stage, a supervisor agent reviews the result and decides what to do next: pass, retry, split into sub-tasks, or reassign to a different agent.

Good for: tasks where you expect some stages to fail and want adaptive recovery.

epsilon runs create --topology supervisor \
  --task "Build a service and recover from failed stages"

work_queue¶

A pull-based queue pattern. A broker holds tasks, and worker daemons pull them as they become available. Tasks can have dependencies — a task only becomes available when its dependencies are complete.

Good for: long-running workloads with many independent tasks, heterogeneous workers.

epsilon runs create --topology work_queue \
  --task "Process a batch of documents"

sharded_queue¶

A manifest-backed fan-out pattern. You provide a JSON manifest listing independent work items. Each item is assigned to a shard, processed in parallel, and results are collected per shard. Shard-local reducers can aggregate results within each shard before a final merge.

Good for: large lists of independent items (hundreds or thousands), explicit workloads where you define every task upfront.

epsilon runs create --topology sharded_queue \
  --task-manifest manifests/large-job.json

Requires a --task-manifest instead of --task.

map_reduce¶

A hierarchical aggregation pattern. Like sharded_queue, but with a fixed-arity tree of map and reduce stages. Map tasks process individual items, reduce tasks aggregate results, and the tree collapses to a single output.

Good for: summarization, extraction, and merge workloads over large datasets.

epsilon runs create --topology map_reduce \
  --task-manifest manifests/reduce-job.json

Requires a --task-manifest instead of --task.

population_search¶

A search pattern for optimizing agent behavior. Instead of solving one task, it evolves a candidate agent codebase across multiple generations, scoring candidates against a task family and selecting the best performers.

Good for: improving agent prompts, tool policies, and runtime configurations over a measured benchmark.

epsilon runs create --topology population_search \
  --task-family examples/population_search/polyglot_task_family.json

Requires a --task-family instead of --task. Model credentials are required for actual search runs.

All command examples¶

# free-form topologies
epsilon runs create --topology dag --task "Build a notes API"
epsilon runs create --topology tree --task "Build an e-commerce platform"
epsilon runs create --topology pipeline --task "Build a staged content workflow"
epsilon runs create --topology supervisor --task "Build a service with adaptive recovery"

# queue topologies
epsilon runs create --topology work_queue --task "Process a batch of documents"
epsilon runs create --topology sharded_queue --task-manifest manifests/large-job.json
epsilon runs create --topology map_reduce --task-manifest manifests/reduce-job.json

# search
epsilon runs create --topology population_search \
  --task-family examples/population_search/polyglot_task_family.json