Agentic Architectures

Catalogue / Evolution & Emergence

Scored Archive Self-improvement

Each round competes with the best of the past, scored on fixed rubrics

Shape
loop
Model calls
rounds × candidates × 2 (e.g. 5 rounds × 4 candidates = 40)
Latency
high
Complexity
medium

Also known as Archive-guided generation, Best-so-far loop

1

How do I keep improving a result when there is no single right answer?

Generate several candidates, score each one on a few explicit dimensions with fixed rubrics, and keep the best in an archive. Each new round is written while looking at the archive's top entries and their scores, so it has to beat its own past to get in.

You may need it if

  • You test many versions of the same thing, such as headlines, onboarding emails or pricing copy.
  • "Better" has several parts, like clarity, tone and length, that pull in different directions.
  • One rewrite at a time stalls, and the best idea often comes from an earlier attempt.
2

When is a scored archive more machinery than the task needs?

Use it when

  • There is no single correct answer, only better and worse ones.
  • You can write a rubric of three to five dimensions, each with a scoring guide from 1 to 10.
  • You can afford dozens of model calls to gain a clearly better result.

Avoid it when

What it costs

Model calls
rounds × candidates × 2 (e.g. 5 rounds × 4 candidates = 40)
Latency
high
Complexity
medium
3

How does quality climb from round to round?

A loop around a store. Generators write candidates while reading the archive's best entries. A scorer rates each candidate on every dimension and writes the scores to the archive, which keeps only the top few. A rule then decides whether to run another round.

improved androunds leftplateau orrounds spentTask: The task, optionally with a starting draft and the scoring dimensions.TaskGenerators: Each writes one new candidate, aiming to beat the archive's best on its weakest dimensions.GeneratorsScorer: Scores each candidate on every dimension using the fixed rubric, with a reason per score.ScorerArchive: The best candidates so far with their scores per dimension. Keeps a fixed number, drops the rest.ArchiveStill improving?: Counts rounds and compares the archive's best total with the previous round.Stillimproving?Best result: The top archive entry, its scores and the runners-up.Best result
  1. Step 1 of 5

    A first batch of candidates

    Several generators each write one candidate for the task, for example four subject lines for a renewal email. If a draft was supplied, it enters the archive as the first entry to beat.

  2. Step 2 of 5

    Scored on fixed dimensions

    The scorer rates each candidate on every dimension, such as clarity, urgency and fit with the brand, using the same written rubric every round. It does not know which round a candidate comes from.

  3. Step 3 of 5

    Only the best are kept

    Scored candidates go into the archive. It keeps the top five by total score and drops the rest, so it always holds the strongest examples found so far.

  4. Step 4 of 5

    The next round sees the bar

    Generators now read the top entries with their scores and reasons. Each tries to beat them, often by fixing the weakest dimension of the leader or combining two strong entries.

  5. Step 5 of 5

    A plain rule decides

    The gate checks the archive's best total. If it rose this round and rounds remain, the loop runs again. If it stalled or the limit is reached, the best entry leaves.

What each part does
Task
The task, optionally with a starting draft and the scoring dimensions.
Generators
Each writes one new candidate, aiming to beat the archive's best on its weakest dimensions.
Scorer
Scores each candidate on every dimension using the fixed rubric, with a reason per score.
Archive
The best candidates so far with their scores per dimension. Keeps a fixed number, drops the rest.
Still improving?
Counts rounds and compares the archive's best total with the previous round.
Best result
The top archive entry, its scores and the runners-up.
  • Archive → Generators: top entries and scores
  • Generators → Scorer: new candidates
  • Scorer → Archive: scored candidates
  • Archive → Still improving?: best total so far
  • Still improving? → Generators: improved and rounds left
  • Still improving? → Best result: plateau or rounds spent

Where it connects

Entry
task
TaskDraft

A task to produce many versions of, or an existing draft to beat. Scoring dimensions are optional; the stage writes three to five when absent.

Exit
best
Answer

When: The best total did not improve this round, or the round limit is reached.

The top candidate, its score per dimension with reasons, the runners-up in the archive and the best total after each round.

Working memory for one run
archive
Options

A ranked list of at most five candidates, each with its score and reason per dimension. Written only by the scorer, read by the generators and the gate.

4

What do I ask my assistant to set up?

The agents to launch

Generator, three to five per round, each in a fresh context

Write one new candidate for the task. Study the archive entries and their scores. Aim to beat the leader, especially on its weakest dimension. Do not copy an entry; change it in a way you expect to score higher. Return only the candidate.

Sees: The task, the dimensions and the archive's top entries with scores and reasons. Not the other generators' work this round.

Scorer

Score each candidate on every dimension from 1 to 10, using only the rubric. For each score, give one sentence naming what earned or lost points. Score each candidate on its own merits, not relative to the others.

Sees: The task, the rubric and the candidates, labelled with neutral ids. Not who wrote them, which round they come from or their past scores.

A prompt you can paste

Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.

Framework-agnostic prompt
You are the orchestrator of a multi-agent workflow that follows the "Scored Archive Self-improvement" architecture.
Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it.

# Task
[Describe your task here]

# Scored Archive Self-improvement
Each round competes with the best of the past, scored on fixed rubrics.
Input: the task above. It must provide: A task to produce many versions of, or an existing draft to beat. Scoring dimensions are optional; the stage writes three to five when absent. If something essential is missing, ask for it before starting.

Agents to launch:
- Generator (three to five per round, each in a fresh context): Write one new candidate for the task. Study the archive entries and their scores. Aim to beat the leader, especially on its weakest dimension. Do not copy an entry; change it in a way you expect to score higher. Return only the candidate.
  Context for this agent: The task, the dimensions and the archive's top entries with scores and reasons. Not the other generators' work this round.
- Scorer: Score each candidate on every dimension from 1 to 10, using only the rubric. For each score, give one sentence naming what earned or lost points. Score each candidate on its own merits, not relative to the others.
  Context for this agent: The task, the rubric and the candidates, labelled with neutral ids. Not who wrote them, which round they come from or their past scores.

Procedure:
1. Write three to five scoring dimensions. For each, describe what a 3, a 6 and a 9 look like. Freeze this rubric for the whole run.
2. Create an empty archive that keeps the top five candidates by total score. If the input contains a draft, score it and add it.
3. Launch the generators, each in a fresh context with the task, the rubric and the current archive.
4. Launch the scorer on the new candidates, with neutral labels. Add them to the archive, keep the top five, drop the rest.
5. Record the best total. If it rose and fewer than 6 rounds were run, start the next round from the generator step.

Stop rule: Stop when the best total does not rise for one round, or after 6 rounds, whichever comes first.

Exit:
- `best`, when: The best total did not improve this round, or the round limit is reached. Deliver: The top candidate, its score per dimension with reasons, the runners-up in the archive and the best total after each round.

# Final deliverable
The best candidate, its score and reason per dimension, the other archive entries, and a line per round showing the best total, so the reader sees where gains came from.

The same thing in code

LangGraph, python, package langgraph
import asyncio
import random

from langchain.chat_models import init_chat_model
from langgraph.graph import END, START, StateGraph
from pydantic import BaseModel

llm = init_chat_model("anthropic:claude-sonnet-5-5")
GENERATORS, KEEP, MAX_ROUNDS = 3, 5, 6
# the rubric, frozen for the whole run
RUBRIC = """clarity: 3 = hard to follow, 6 = clear with effort, 9 = clear on first read
accuracy: 3 = several errors, 6 = minor slips, 9 = every claim holds
concision: 3 = padded, 6 = some repetition, 9 = nothing to cut"""


class DimScore(BaseModel):
    dimension: str
    score: int
    reason: str


class Card(BaseModel):
    id: str
    scores: list[DimScore]


class Scored(BaseModel):
    cards: list[Card]


class Entry(BaseModel):
    text: str
    scores: list[DimScore]

    @property
    def total(self) -> int:
        return sum(s.score for s in self.scores)


class State(BaseModel):
    task: str
    archive: list[Entry] = []
    candidates: list[str] = []
    best_by_round: list[int] = []


def show(archive: list[Entry]) -> str:
    return "\n\n".join(f"[total {e.total}] " + "; ".join(f"{s.dimension} {s.score}: {s.reason}" for s in e.scores)
                       + f"\n{e.text}" for e in archive) or "(empty)"


async def generators(state: State) -> dict:
    # each generator is a fresh call: task, rubric and archive, never this round's other drafts
    prompt = ("Write one new candidate for the task. Study the archive entries and their scores. Aim to beat "
              "the leader, especially on its weakest dimension. Do not copy an entry. Return only the candidate.\n"
              f"Rubric:\n{RUBRIC}\n\nArchive:\n{show(state.archive)}\n\nTask: {state.task}")
    replies = await asyncio.gather(*(llm.ainvoke(prompt) for _ in range(GENERATORS)))
    return {"candidates": [r.text for r in replies]}


async def scorer(state: State) -> dict:
    # neutral labels, shuffled: the scorer never sees authorship, round or past scores
    ids = {f"c{i}": text for i, text in enumerate(random.sample(state.candidates, len(state.candidates)))}
    listing = "\n\n".join(f"[{k}]\n{v}" for k, v in ids.items())
    out = Scored.model_validate(await llm.with_structured_output(Scored).ainvoke(
        "Score each candidate on every dimension from 1 to 10 using only the rubric, one sentence per score. "
        f"Judge each on its own merits.\nRubric:\n{RUBRIC}\nTask: {state.task}\n\n{listing}"))
    scored = [Entry(text=ids[c.id], scores=c.scores) for c in out.cards if c.id in ids]
    archive = sorted(state.archive + scored, key=lambda e: e.total, reverse=True)[:KEEP]  # keep the top five
    return {"archive": archive, "best_by_round": state.best_by_round + [archive[0].total if archive else 0]}


def still_improving(state: State) -> str:
    totals = state.best_by_round
    improved = len(totals) == 1 or totals[-1] > totals[-2]
    return "generators" if improved and len(totals) < MAX_ROUNDS else END  # the gate: plateau or 6 rounds


graph = StateGraph(State).add_sequence([generators, scorer])
graph.add_edge(START, "generators")
graph.add_conditional_edges("scorer", still_improving, ["generators", END])
app = graph.compile()


async def run(task: str):
    final = State.model_validate(await app.ainvoke(State(task=task)))
    return final.archive[0], final.archive[1:], final.best_by_round

Replace the sample rubric with your own dimensions and level descriptions, and read the leader yourself before trusting a rising score.

Claude Agent SDK, python, package claude-agent-sdk
import random
from typing import TypeVar

from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage, query
from pydantic import BaseModel

M = TypeVar("M", bound=BaseModel)
GENERATORS, KEEP, MAX_ROUNDS = 3, 5, 6
# the rubric, frozen for the whole run
RUBRIC = """clarity: 3 = hard to follow, 6 = clear with effort, 9 = clear on first read
accuracy: 3 = several errors, 6 = minor slips, 9 = every claim holds
concision: 3 = padded, 6 = some repetition, 9 = nothing to cut"""


class DimScore(BaseModel):
    dimension: str
    score: int
    reason: str


class Card(BaseModel):
    id: str
    scores: list[DimScore]


class Scored(BaseModel):
    cards: list[Card]


class Candidates(BaseModel):
    candidates: list[str]


AGENTS = {
    "generator": AgentDefinition(
        description="Writes one new candidate that should beat the archive's leader.",
        prompt="Write one new candidate for the task. Study the archive entries and their scores. Aim to beat "
        "the leader, especially on its weakest dimension. Do not copy an entry. Return only the candidate.",
        tools=[],
    ),
    "scorer": AgentDefinition(
        description="Scores candidates against the fixed rubric.",
        prompt="Score each candidate on every dimension from 1 to 10 using only the rubric, with one sentence "
        "per score. Judge each candidate on its own merits, not against the others.",
        tools=[],
    ),
}


async def ask(prompt: str, agent: str, schema: type[M]) -> M:
    options = ClaudeAgentOptions(
        agents={agent: AGENTS[agent]}, tools=["Agent"], allowed_tools=["Agent"], max_turns=10,
        output_format={"type": "json_schema", "schema": schema.model_json_schema()},
    )
    async for message in query(prompt=prompt, options=options):
        if isinstance(message, ResultMessage):
            return schema.model_validate(message.structured_output)
    raise RuntimeError(f"{agent} returned nothing")


async def run(task: str):
    archive: list[tuple[int, str, list[DimScore]]] = []  # the archive: (total, candidate, scores)
    best_by_round: list[int] = []
    while len(best_by_round) < MAX_ROUNDS:  # the gate: at most 6 rounds
        shown = "\n\n".join(f"[total {t}] {[s.model_dump() for s in sc]}\n{c}" for t, c, sc in archive) or "(empty)"
        # the fan-out: separate generator sub-agents, none sees another's draft
        drafts = await ask(f"Launch the generator agent {GENERATORS} times in parallel, each with exactly this input, "
                           f"and return their candidates verbatim.\n\nRubric:\n{RUBRIC}\n\nArchive:\n{shown}\n\n"
                           f"Task: {task}", "generator", Candidates)
        ids = {f"c{i}": c for i, c in enumerate(random.sample(drafts.candidates, len(drafts.candidates)))}
        listing = "\n\n".join(f"[{k}]\n{v}" for k, v in ids.items())  # neutral labels only
        scored = await ask(f"Hand this input unchanged to the scorer agent and return its scores.\n\nRubric:\n{RUBRIC}\n"
                           f"Task: {task}\n\n{listing}", "scorer", Scored)
        archive += [(sum(s.score for s in c.scores), ids[c.id], c.scores) for c in scored.cards if c.id in ids]
        archive = sorted(archive, key=lambda e: e[0], reverse=True)[:KEEP]  # keep the top five
        best_by_round.append(archive[0][0] if archive else 0)
        if len(best_by_round) > 1 and best_by_round[-1] <= best_by_round[-2]:
            break  # plateau: the best total did not rise this round
    return archive, best_by_round

Replace the sample rubric with your own dimensions and level descriptions, and read the leader yourself before trusting a rising score.

OpenAI Agents SDK, python, package openai-agents
import asyncio
import random

from agents import Agent, Runner
from pydantic import BaseModel

GENERATORS, KEEP, MAX_ROUNDS = 3, 5, 6
# the rubric, frozen for the whole run
RUBRIC = """clarity: 3 = hard to follow, 6 = clear with effort, 9 = clear on first read
accuracy: 3 = several errors, 6 = minor slips, 9 = every claim holds
concision: 3 = padded, 6 = some repetition, 9 = nothing to cut"""


class DimScore(BaseModel):
    dimension: str
    score: int
    reason: str


class Card(BaseModel):
    id: str
    scores: list[DimScore]


class Scored(BaseModel):
    cards: list[Card]


generator = Agent(
    name="Generator",
    instructions="Write one new candidate for the task. Study the archive entries and their scores. Aim to beat "
    "the leader, especially on its weakest dimension. Do not copy an entry. Return only the candidate.",
)
scorer = Agent(
    name="Scorer",
    instructions=f"Score each candidate on every dimension from 1 to 10 using only this rubric, with one sentence "
    f"per score. Judge each on its own merits, not against the others.\n{RUBRIC}",
    output_type=Scored,
)


async def run(task: str):
    archive: list[tuple[int, str, list[DimScore]]] = []  # the archive: (total, candidate, scores)
    best_by_round: list[int] = []
    while len(best_by_round) < MAX_ROUNDS:  # the gate: at most 6 rounds
        shown = "\n\n".join(f"[total {t}] {[s.model_dump() for s in sc]}\n{c}" for t, c, sc in archive) or "(empty)"
        brief = f"Rubric:\n{RUBRIC}\n\nArchive:\n{shown}\n\nTask: {task}"
        # the fan-out: separate runs, none sees another generator's draft
        drafts = await asyncio.gather(*(Runner.run(generator, brief) for _ in range(GENERATORS)))
        texts = random.sample([str(d.final_output) for d in drafts], len(drafts))
        ids = {f"c{i}": t for i, t in enumerate(texts)}  # neutral labels: no author, round or past score
        listing = "\n\n".join(f"[{k}]\n{v}" for k, v in ids.items())
        scored = (await Runner.run(scorer, f"Task: {task}\n\n{listing}")).final_output_as(Scored)
        archive += [(sum(s.score for s in c.scores), ids[c.id], c.scores) for c in scored.cards if c.id in ids]
        archive = sorted(archive, key=lambda e: e[0], reverse=True)[:KEEP]  # keep the top five
        best_by_round.append(archive[0][0] if archive else 0)
        if len(best_by_round) > 1 and best_by_round[-1] <= best_by_round[-2]:
            break  # plateau: the best total did not rise this round
    return archive, best_by_round

Replace the sample rubric with your own dimensions and level descriptions, and read the leader yourself before trusting a rising score.

Vercel AI SDK, typescript, package ai
import { anthropic } from '@ai-sdk/anthropic';
import { generateText, Output } from 'ai';
import { z } from 'zod';

const model = anthropic('claude-sonnet-5-5');
const GENERATORS = 3, KEEP = 5, MAX_ROUNDS = 6;
// the rubric, frozen for the whole run
const RUBRIC = `clarity: 3 = hard to follow, 6 = clear with effort, 9 = clear on first read
accuracy: 3 = several errors, 6 = minor slips, 9 = every claim holds
concision: 3 = padded, 6 = some repetition, 9 = nothing to cut`;

const dimScore = z.object({ dimension: z.string(), score: z.number().int(), reason: z.string() });
type Entry = { total: number; text: string; scores: z.infer<typeof dimScore>[] };

export async function run(task: string) {
  let archive: Entry[] = []; // the archive: top five by total score
  const bestByRound: number[] = [];
  while (bestByRound.length < MAX_ROUNDS) { // the gate: at most 6 rounds
    const shown = archive.map((e) => `[total ${e.total}] ${JSON.stringify(e.scores)}\n${e.text}`).join('\n\n') || '(empty)';
    // the fan-out: separate calls, none sees another generator's draft
    const drafts = await Promise.all(
      Array.from({ length: GENERATORS }, () =>
        generateText({
          model,
          instructions: 'Write one new candidate for the task. Study the archive entries and their scores. Aim to ' +
            'beat the leader, especially on its weakest dimension. Do not copy an entry. Return only the candidate.',
          prompt: `Rubric:\n${RUBRIC}\n\nArchive:\n${shown}\n\nTask: ${task}`,
        }),
      ),
    );
    const texts = drafts.map((d) => d.text).sort(() => Math.random() - 0.5);
    const ids = new Map(texts.map((t, i) => [`c${i}`, t])); // neutral labels: no author, round or past score
    const { output } = await generateText({
      model,
      instructions: 'Score each candidate on every dimension from 1 to 10 using only the rubric, with one sentence ' +
        'per score. Judge each on its own merits, not against the others.',
      prompt: `Rubric:\n${RUBRIC}\nTask: ${task}\n\n` + [...ids].map(([k, v]) => `[${k}]\n${v}`).join('\n\n'),
      output: Output.object({ schema: z.object({ cards: z.array(z.object({ id: z.string(), scores: z.array(dimScore) })) }) }),
    });
    for (const card of output.cards) {
      const text = ids.get(card.id);
      if (text) archive.push({ total: card.scores.reduce((n, s) => n + s.score, 0), text, scores: card.scores });
    }
    archive = archive.sort((a, b) => b.total - a.total).slice(0, KEEP); // keep the top five
    bestByRound.push(archive[0]?.total ?? 0);
    const n = bestByRound.length;
    if (n > 1 && bestByRound[n - 1] <= bestByRound[n - 2]) break; // plateau: the best total did not rise
  }
  return { best: archive[0], runnersUp: archive.slice(1), bestByRound };
}

Replace the sample rubric with your own dimensions and level descriptions, and read the leader yourself before trusting a rising score.

Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.

What goes wrong

  • A rubric with vague levels drifts between rounds and makes old and new scores incomparable. Describe each level concretely.
  • Generators that see only the single best entry converge on near-copies. Show the top three to five.
  • Scores can rise while real quality does not. Read the leader yourself before trusting the climb.

Chain it

Its result can feed