agent-fleet-manager README

The project's README from github.com/dreamers-laboratory/agent-fleet-manager. As one markdown file: README.md.

agent-fleet-manager

A general-purpose engine for large-scale, repeated information gathering by a fleet of workers — plain fetchers, scrapers, or LLM agents. You register things to check and how often; the engine schedules what is due, leases work out in isolated batches, records what came back, detects change by content hash, backs off on failures, and keeps an auditable ledger of every write. One SQLite file is the entire system. Python standard library only.

It came out of a production system where a mixed fleet of LLM agents and plain fetchers tracks a few thousand sources on daily and weekly cadences. This is a clean rewrite of the part that generalizes: the bookkeeping. The engine never interprets what a source is — the route field means nothing to it and everything to your worker — which is why the same engine can run very different fleets.

What people use this shape of system for

In every case the engine's contribution is the same: which of your thousands of sources are due right now, what actually changed, what is failing and backing off, and proof of all of it.

The model

Five tables (see agentfleet/schema.sql):

Three rules carry the design. Workers never write canonical state; they drop result files in their write scope and the parent folds them in during reconcile, so a crashed or misbehaving worker can corrupt at most its own scratch directory. Change detection is a content hash, so any run can be repeated safely. Every canonical write is attributed, which matters once several agents share one database.

Scheduling: success sets next_due_at = now + cadence; failure sets next_due_at = now + cadence × min(2^streak, 16) and requeues up to 3 attempts.

Quickstart

python -m agentfleet.cli add-source --db fleet.db acme-careers https://example.com/careers --cadence 3600
python -m agentfleet.cli sweep --db fleet.db
python -m agentfleet.cli status --db fleet.db
python -m agentfleet.cli stats --db fleet.db

sweep queues due sources, leases batches, fetches each route over HTTP, and reconciles. stats prints per-source change rate, error rate, median and p95 latency, and fleet totals. python examples/demo.py runs the whole loop on local files with no network. Tests: python tests/test_engine.py.

Bring your own workers

The built-in executor is a function route -> (status, content_bytes). For an external fleet (LLM agents, containers, other machines), call lease() to get a manifest, hand each batch to a worker, and have the worker write {action_id}.json result files into its write_scope:

{"action_id": 7, "source_id": 3, "status": "ok", "sha256": "…", "bytes": 4096,
 "started_at": "2026-08-31T19:50:21Z", "finished_at": "2026-08-31T19:50:22Z", "elapsed_ms": 812.4}

Then reconcile(conn, batch_id). The engine treats a missing result file as a failure, so dead workers resolve themselves. An LLM agent makes a good worker precisely because the contract is this narrow: read the manifest, do the check however you judge best, write result files, touch nothing else. SKILL.md teaches a coding agent to operate the whole loop.

Watch it in Grafana

The tables are span-shaped by construction, so telemetry is an export:

python -m agentfleet.cli export-otel --db fleet.db --endpoint http://localhost:4318

maps run → trace, batch → parent span, action → child span (with source name, hash, bytes, attempt, and changed-flag attributes) and posts OTLP/HTTP JSON to any collector, including a Grafana Cloud OTLP gateway. Omit --endpoint to inspect the JSON on stdout.

Apache-2.0. Built by Dreamers Inc.

agent-fleet-manager (dreamers-laboratory/agent-fleet-manager)

Searching Database…

147 ·GitHub
Agent-fleet-manager
Что это?Это движок, который планирует, раздаёт в аренду и отслеживает масштабные повторные проверки источников (веб-страниц, фидов, листингов) флотом воркеров — простых загрузчиков, скраперов или LLM-агентов, — фиксируя изменения по хэшу контента и ведя поддающийся аудиту журнал каждой записи.
Это фреймворк, на котором я строю своё, или готовый скрапер?Это фреймворк/библиотека вокруг пяти таблиц SQLite (source, action, batch, observation, changelog); он никогда не интерпретирует, чем является источник, и целиком отдаёт логику загрузки подключаемым вами воркерам.
Как его попробовать?Выполните `python examples/demo.py`, чтобы увидеть весь цикл sweep-lease-reconcile на локальных файлах без сети; команда `sweep` ставит подошедшие источники в очередь и раздаёт батчи в аренду, а `stats` печатает по каждому источнику долю изменений и ошибок и задержки.
Нужно ли ставить дополнительные библиотеки или поднимать сервер базы данных?Нет — используется только стандартная библиотека Python, а вся система умещается в один файл SQLite.
Знает ли движок, чем на самом деле являются мои источники?Нет, поле «route» он считает бессмысленной учётной информацией — вся интерпретация того, что и как загружать, полностью отдана вашему коду воркера.
Зачем нужен SKILL.md?Он обучает кодинг-агента вести полный цикл sweep-lease-reconcile, чтобы LLM могла сама управлять флотом.
Что будет, если воркер упадёт посреди батча?Воркеры пишут файлы результатов только в собственный каталог записи, а родитель затем сводит их; отсутствие файла результата просто считается сбоем, поэтому упавший или неправильно ведущий себя воркер не может повредить каноническое состояние.
Можно ли наблюдать за этим в Grafana?Да: таблицы напрямую отображаются на спаны (run — в трейс, batch — в родительский спан, action — в дочерний), поэтому движок может отправлять телеметрию OTLP/HTTP JSON в любой коллектор, включая OTLP-шлюз Grafana Cloud, или просто печатать её в stdout.
Что люди реально отслеживают с его помощью?Примеры: поиск кандидатов и лидов на страницах вакансий, слежение за ценами и функциями конкурентов, мониторинг регуляторных и compliance-страниц, поддержание исследовательских корпусов в актуальном состоянии и мониторинг маркетплейсов и листингов.
What are similar projects?agento11y, 3d-asset-server, opensre, bareloop, evenfire, youtube-automation-agent, prefect, pyspider
Which topics is it in?grafana, opentelemetry, scheduler, crawler, web-scraping, observability, sqlite, monitoring, agent, automation, tool, ai-agents
Creator
dreamers-laboratory
Size
<0.1 MB
Stars
147
Updated
CommitOct 01Releasev0.1.0Oct 01
Age
1mo
Commits · 90 Days