Birfy/agentdescent: 에이전트를 매개변수로 하는 경사 하강법

웹사이트 및 인터랙티브 데모 ·
시작하기 ·
문서화

경사 하강법(Gradient descent) — 하지만 여기서 매개변수는 에이전트입니다. 에이전트(기술, 프롬프트, 하네스)가 스스로 진화하는 것을 위한 병렬적이고 비동기적인 프레임워크이며, 차분값(diffs)은 경사(gradients)이고 집계기(aggregator)는 최적화기(optimizer)입니다.

N개의 워커가 공유 아티팩트에 대한 수정을 병렬로 제안하며, 배리어 프리(barrier-free) 집계기가 이를 단일 버전 관리 라이브러리로 병합합니다. 순차적인 자체 개선은 반복당 하나의 승인된 변경으로 제한되지만, 동시 편집을 병합하는 것은 그 한계를 극복하려는 시도입니다.

이 비유가 깨져야 하는 지점은 전체 설계에 있습니다: 경사(gradients)는 더하고, 차분값(diffs)은 그렇게 하지 않습니다. 따라서 집계는 평균화가 아니라 충돌 해결(conflict resolution), 융합(fusion), 통계적 수용 및 트랜잭션 커밋입니다.

모든 행은 해당 설정을 생성한 곳을 명시하며, 전체 결과 페이지에는 배울 것이 아무것도 없었던 실행 기록도 보고합니다.

품질은 설계가 지원할 수 있는 경우에만 주장됩니다. 논문에서는 비교하여 유의미성에 도달하지 못한 경우 p-값 대신 구간(interval)을 보고하며, 이를 명시합니다.

실선, 위쪽: 고정된 데이터 경로입니다. N개의 워커가 레저 스냅샷에 대해 작업을 롤아웃하고 증거 카드가 포함된 차분값을 방출하며; 하나의 집계기 스레드가 5단계 병합을 실행하고 승자를 커밋합니다; 녹색 가장자리는 지연 예산(lag budget)으로 제한되는 유일한 피드백 경로입니다.

점선, 아래쪽: evolve()의 키워드 인자 중 하나에 의해 선택된 이음매들입니다.

. Red: 거버넌스 레이어(governance layer)는 의도적으로 경계가 아니며 — 자체 수정 시스템은 자신의 평가자(evaluator)를 대체할 수 없어야 합니다.

스테이지 1~5는 이산 공간(discrete space)에 대한 하나의 최적화기 단계입니다. 그 단계 자체가 무엇을 할 수 있는지는 상위에서, 즉 전략(strategy)이 작성하는 **키 공간(key space)**의 편집 내용에 따라 결정됩니다 — 서로 다른 키에 대한 편집은 융합되고, 같은 키에 대한 편집은 충돌합니다. 이것이 위 표가 하나의 키 아티팩트(one-key artifact)로 시작하는 이유입니다.

이 그림은 논문의 것이며, tools/gen_architecture_figure.py를 통해 TikZ 소스에서 렌더링되었으므로, 논문이 보여주는 것에서 벗어날 수 없습니다.

이 지침들은 0.6.0을 대상으로 합니다. 해당 버전이 게시되면:

pip install "agentdescent>=0.6.0"
agentdescent demo

게시 전 또는 소스에서 개발할 때는 체크아웃(checkout)을 설치하세요:

git clone https://github.com/Birfy/agentdescent && cd agentdescent
pip install -e .
agentdescent demo

이 라이브러리는 Python ≥ 3.9를 지원하며, 예측 기반 감사 추정기(prediction-powered audit estimator)를 위해 NumPy를 설치합니다. 패키지화된 데모는 모델 API 키 없이 오프라인 진화 루프(offline evolution loop)를 실행하고 다음과 같은 출력으로 끝납니다:

held-out reward: 1.000 outcomes: {'committed': 1}
what it learned: rules.md -> 'COLUMN: amount'

연구 예제는 wheel 밖에 있습니다. python -m examples.run_demo 비교를 실행하려면, 리포지토리를 클론하고 설치 및 첫 실행을 따르세요.
이 라이브러리에는 evolve()와 DirectoryStrategy, 그리고 그 알고리즘 포트가 포함되어 있습니다.

하나의 진입점(entry point)인 evolve()와 데이터셋을 인자(argument)로 변환하는 세 가지 빌딩 블록이 있습니다. 실제로 사용자가 결정해야 하는 것들 — 즉, 사용자 데이터, 점수화 방법, 어떤 모델을 사용할지 — 은 여전히 여러분이 결정합니다.

먼저 키를 설정하세요. 자격 증명(Credentials)은 호출 시점에 환경 변수에서 읽어오며 — 코드, 인자 또는 리포가 소유한 파일에서는 절대 읽지 않으며 — 기본 URL은 제공업체(provider)를 선택하는 역할을 합니다:

export OPENAI_BASE_URL=https://api.deepseek.com # 또는 GLM, 로컬 vLLM, OpenAI 자체
export OPENAI_API_KEY=sk-... # 해당 엔드포인트용 키

agentdescent doctor

기계가 무엇을 가지고 있는지 보고합니다. 위의 데모와 pytest -q를 사용하세요.

이 모든 것이 필요하지 않습니다.
모든 제공자(provider)는 기본 URL과 함께 →

from agentdescent import SingleSlot, evolve, openai_compatible, reflector, scorer, tasks_from
from agentdescent.dataloader import hf_rows
rows = hf_rows("hotpotqa/hotpot_qa", "validation", config="distractor", limit=40)
...

이 실행은 위의 표의 마지막 행입니다. 이 모델은 *"추가 설명이나 재진술을 생략하고 요청된 답변만 응답하라."*는 것을 학습했습니다.

데이터셋 없이 같은 것. 즉시 실행 가능 — API 키, 의존성 없음.

from agentdescent import Task, evolve
tasks = [Task(id=f"t{i}", prompt=f"item {i}") for i in range(12)]
def reward(task, output): # 반드시 [0, 1]을 반환해야 함
...

run 대신 agent=를 전달하여 실제 모델이나 에이전트를 교체하세요.

/propose:

from agentdescent import LLMAgent, claude, openai_compatible, claude_code
evolve(tasks, reward, agent=LLMAgent(claude(model="claude-haiku-4-5"')))
evolve(tasks, reward, agent=LLMAgent(openai_compatible(model="deepseek-v4-flash"')))
...

**플러그인(plugin)**과 동일한 엔진입니다. 공유된 기술은 호스트에게 언제 그것을 사용해야 하는지 가르치고, MCP 서버는 doctor / plan / start / status / show / apply / cancel / resume를 노출하며, CLI도 이를 반영하여 에이전트에서 시작된 실행을 셸(shell)에서 검사할 수 있습니다.

현재의 main 체크아웃부터:

bash scripts/setup-hosts.sh # 설치하고 사용 가능한 모든 에이전트 CLI를 연결합니다
agentdescent demo # 완전한 진화 과정, 오프라인, 키 불필요, 약 10초 소요
agentdescent doctor # 이 기계가 어떤 CLI와 키를 가지고 있는지 확인합니다

에이전트 내부에서 "이 프롬프트를 이 예시들을 바탕으로 개선해줘"라고 말해보세요. doctor를 실행하고, 사양(spec)을 작성하며, 시작 전에 호출 횟수를 인용하고, 사용자의 승인을 기다린 후, 분리된 상태로 실행하고, 아무것도 쓰기 전에 다시 요청합니다.

아직 케이스가 없다는 것은 문제가 아닙니다. 이를 초안하는 것이 절차의 첫 단계일 뿐, 전제 조건은 아닙니다. 파일에 포인트를 지정하면 검토할 8~20개의 사례를 자동으로 작성해 줍니다.

kind

is text,

skill_dir,

agent_dir,

agent_code
— 또는 plugin: 호스트 플러그인 자체도 진화 가능하며, 각 롤아웃은 호스트의 격리된 복사본에 로드되고, 후크 및 권한 구성이 고정되며, 재귀 가드가 있어 플러그인이 스스로를 진화시키면서 중첩 실행을 시작하는 것을 방지합니다.

플러그인은 세 가지 명령어로 → · 설정하고 테스트할 수 있습니다 →

두 개의 심(seam)이 알고리즘을 전달하며, 둘 다 typing.Protocols입니다 — 상속받을 것이 없으며, 계약은 엔진 자체의 호출 지점에서 테스트를 통해 재파생되므로, 게시된 인터페이스는 실행되는 것과 어긋날 수 없습니다.

전략(The strategy) — 진화하는 것. 평평한 {key: value} 상태에 대한 세 가지 방법입니다.
그 키 공간이 동시 제안들이 아예 융합될 수 있는지 여부를 결정합니다.

여덟 가지 정책 슬롯 — 진화의 규칙. 각각은 Policies 번들의 하나의 필드이며, 각 기본값은 배포된 규칙으로 설정되고, 하나를 채우면 나머지 일곱 개는 그대로 둡니다. 드라이버는 무시하는 대신 처리할 수 없는 필드를 거부합니다 — 설치만 하고 절대 실행되지 않는 정책이 호출자가 완료된 실행으로부터 감지할 수 없는 유일한 실패입니다.

selection | task_sampler | proposal | staleness | conflict | fusion | acceptance | promotion |

파이프라인이 유지하지 않는 상태가 필요한 메커니즘 — 아카이브, 인스턴스별 점수 행(score rows), 섬 풀(island pool) — 대신 aggregator_factory의 종료를 사용합니다.
슬롯을 채우는 방법 →

출판된 자체 진화 알고리즘은 포크(fork) 형태로가 아니라 플러그인(plug-ins) 형태로 실행되며, 엔진을 건드리지 않고 직렬적(serial), 동기식(synchronous) 또는 배리어 프리 스케줄링(barrier-free scheduling) 방식으로 작동합니다. 이것이 바로 스케줄러를 각 논문 자체 루프의 속성(property)이 아닌 제어 가능한 변수(controlled variable)로 만드는 이유입니다.

벤치마크 충실도 (Benchmark-faithful) (8): ACE · GEPA · EvoSkill · SkillOpt · ADAS · DGM · OpenEvolve · ERA
마이크로 포트 및 유사체 (Microports and analogues) (15): PromptBreeder · AFlow · Self-Refine · Reflexion · SICA · Gödel Agent · Voyager · SkillWeaver · Absolute Zero · R-Zero · Agent0 · gskill · TextGrad · Dynamic Cheatsheet · Genesis

Genesis는 전체 알고리즘 — 즉 (version, path) 월드에 대한 재귀(recursion), 3방향 병합(three-way merge) 및 부모의 판결(parent's verdict) — 이 Policies(proposal=, acceptance=, conflict=)와 Strategy를 통해 어떤 엔진 변경도 없이 설치되는 것입니다.

충실도는 포트별로 선언되며, 각 프로젝트가 논문에서 벗어나 *출시된 코드(released code)*를 따르며, 유사체는 벤치마크 재현으로 인용되어서는 안 됩니다. 모든 포트는 API 키가 필요 없는 --dry-run 모드를 가지고 있습니다.

측정된 결과를 포함한 총 스물세 개 모두의 전체 문서는 birfy.github.io/agentdescent에서 확인할 수 있습니다.

@article{chen2026agentdescent,
title = {{AgentDescent}: Asynchronous Parallel Self-Evolution of {LLM} Agents by Merging Conflicting Edits},
... 

LaTeX 소스 및 빌드된 PDF는 여기에 있는 것이 아니라 paper 브랜치에 있습니다. 작성 내용은 다른 시계(different clocks)에서 코드 변경이 이루어집니다. 결과별 원시 데이터는 bench/results/에 있습니다.

대부분의 결과에 대해; merge-versus-selection 스윕은 논문에서 언급하는 명령을 통해 재측정 가능하며, 다시 계산할 수는 없습니다. 그 이유는 각 실행별 데이터가 보존되지 않았기 때문입니다 — 논문에서도 그렇게 말합니다.

**연구 참고 구현체(research reference implementation)**이지, 프로덕션 시스템이 아닙니다. 참신한 점은 좁은 엔지니어링 합성물입니다 — git 기반 버전 관리 원장 위에서 동시적이고, staleness-bounded이며, 충돌 해결된 diff 레벨 병합 기능이며 — 그리고 그 처리량 전제는 커뮤니티의 합의라기보다는 검증 가능한 가설입니다. 기여 환영: CONTRIBUTING.md. 이 스위트는 오프라인이며 결정론적이므로 pytest -q
필요한 API 키가 없습니다.