Reef: инфраструктура непрерывного самоулучшения агентов

Reef — первая open-source инфраструктура для непрерывно самоулучшающихся агентов. Она связывает в один цикл инференс агента, сбор обратной связи, обучение и версионированную доставку обновлений. С её помощью можно обучать веса модели через Slime и SGLang или улучшать сам harness агента — промпты, правила и скиллы.

Проект опубликован под Apache-2.0, пакет называется reef-infra, требует Python 3.12+.

Когда использовать Reef

Reef нужен, когда агент должен становиться сильнее просто за счёт того, как вы с ним работаете:

Как Reef встраивается в стек

Как работает цикл

Каждый цикл обучения состоит из четырёх шагов:

1. Serve — обслуживает запросы агента и записывает взаимодействия. Модули: service/ (запросы и записи), runtime/ (инференс и обновление артефактов).
2. Observe — сопоставляет обратную связь с записанными взаимодействиями. Модули: storage/records.py (хранение), train/processors/ (сопоставление и допустимость фидбека).
3. Grow — порождает обновление из допустимых записей. Модули: recipe/ (интеграция recipe), train/ (батчи и джобы).
4. Commit — применяет настроенную политику отбора и публикует принятые обновления. Модули: train/evaluation/ (оценка кандидатов), artifact/ (история версий), surface/ (доставка).

Установка

Для артефактов и чекпоинтов нужен системный пакет git-lfs — Reef инициализирует Git LFS локально для своих репозиториев артефактов. Авторы рекомендуют uv:

uv venv && source .venv/bin/activate
uv pip install reef-infra
python3 -c "import reef; print(reef.__version__)"

Из исходников (нужно для разработки и training-примеров):

git lfs install
git clone https://github.com/Human-Agent-Society/reef.git
cd reef
uv venv && source .venv/bin/activate
uv pip install -e .
python3 -c "import reef; print(reef.__version__)"

Минимальный запуск — чистый inference-сервер:

uv run reef serve --inference.model-path Qwen/Qwen2.5-1.5B-Instruct

Два режима: веса и harness

Recipe деплоя определяет, какая поверхность обновляется — веса модели или harness агента.

Обучение весов

Пример запуска SAO-деплоя (arXiv:2607.07508) — из чекаута Reef, в окружении, удовлетворяющем GPU-требованиям:

uv pip install -e ".[slime]" && uv pip install --no-deps --group runtime

export MODEL_PATH="Qwen/Qwen2.5-1.5B-Instruct"
export REEF_TOKEN="reef-local"

reef serve -c recipes/sao/examples/imo_answerbench/serve.yaml \
  --inference.model-path "$MODEL_PATH" \
  --reef.port "8900"

curl -f http://127.0.0.1:8900/healthz

Инференс-эндпоинт совместим с OpenAI и Anthropic: /v1/chat/completions и /v1/messages принимают тела запросов этих провайдеров. Запрос несёт заголовок x-reef-scenario — новое имя создаёт scenario с recipe из деплоя. Reef добавляет ответный заголовок x-reef-agent-record-id: это receipt, по которому позднее report находит взаимодействие. Отчёт может содержать числовый score, текстовый или структурированный feedback и перечень оцениваемых receipt'ов:

import os
import httpx

reef = httpx.Client(
    base_url="http://127.0.0.1:8900",
    headers={"Authorization": f"Bearer {os.environ['REEF_TOKEN']}", "x-reef-scenario": "hello-reef"},
    timeout=300,
)

# Send a provider-compatible inference request
response = reef.post(
    "/v1/chat/completions",
    json={
        "model": os.environ["MODEL_PATH"],
        "messages": [{"role": "user", "content": "Return exactly: reef is ready"}],
    },
)

response.raise_for_status()
receipt = response.headers["x-reef-agent-record-id"]
answer = response.json()["choices"][0]["message"]["content"]

# Sending report about the inference
matched = answer.strip() == "reef is ready"

reef.post(
    "/reef/report",
    json={"score": float(matched), "feedback": "matched" if matched else "wrong answer", "references": [receipt]},
).raise_for_status()

Когда recipe набирает достаточно обратной связи, он запускает training-шаг и синхронизирует обновлённые веса в serving-рантайм. Последующие запросы используют текущую версию без перезапуска Reef.

Эволюция harness

Reefine — встроенный recipe доработки harness: обычным языком, через API модели, без локальных GPU:

reef serve --recipe reefine \
  --inference.upstream-url http://127.0.0.1:11434 \
  --inference.upstream-model gemma4:26b

Reef слушает 127.0.0.1:8901 (состояние — в .reef/reefine/). Свою копию конфигурации деплоя можно передать через -c. В соседнем терминале создаётся scenario, ставится harness и запрашивается изменение:

curl -fsS -H "Content-Type: application/json" \
  -d '{"name": "my-harness"}' http://127.0.0.1:8901/reef/scenarios
curl -fsS -H "x-reef-scenario: my-harness" \
  'http://127.0.0.1:8901/reef/harness/install?adapter=pi' | bash

reef-pi evolve "when I ask you to fix a bug, reproduce it with a failing test first"

В сессии reef-pi команда /reefine <текст> делает тот же запрос. Модель оформляет изменение как скилл, запись в rules, agent-команду или pi-расширение; на Linux с изоляцией (bwrap и pasta) она может прогнать изменённый harness как coding-агент, прежде чем вернуть результат. Версии смотрятся через /versions, установка — /versions <version> install. Подробнее — туториал Reefine и гайд Reefine.

Рецепты и примеры

Recipe выбирается по типу задачи и по тому, что должно эволюционировать — веса или harness. Weight-рецепты требуют GPU-стека, harness-рецепты — только эндпоинта модели. Reefine входит в reef-infra, остальные лежат в recipes/:

Стартовый стек — recipes/basic/ (только запись). Небольшой разбор обратной связи, правок-кандидатов и публикации — в туториале по эволюции harness.

Документация и сообщество

Документация на reefinfra.ai/docs: Quickstart, HTTP API, «Write a recipe», эволюция harness и модели, каталог рецептов, core loop и глоссарий.

Участвовать можно через Discord, GitHub Discussions и гайд контрибьютора; уязвимости — по security policy. Roadmap — в issue #25.

Важные части Reef построены на проектах SGLang (инференс), slime (обучение весов) и cordis (эволюция harness).