AgentLoom
Run permissioned, resumable multi-agent applications defined in YAML.
- Source repo
- linora-u/AgentLoom
- Stars
- ★ 169
- Last updated
- 13d ago
- Primary language
- Python
- FA score
- 52/100 · Major gaps
At a glance
- Works with
- Portable with changesOpenAI API
- You'll need
- Typical use
- Release review teams combining an api_reviewer and test_reviewer Worker into one decision pipeline.
- Main limitation
- The installer only supports macOS and Linux shells and needs Git/Bash; Windows is not documented.
- Source review
- 52/100 · Major gaps
What does this agent do, and when should you use it?
AgentLoom treats a multi-agent system as an Application with an execution contract: YAML declares the Supervisor, typed Workers, models, tools, Skills, Hooks, permissions and runtime policy, and the runtime executes it via CLI or Python API. A Supervisor lists Workers in worker_agents; each selected Worker becomes a callable tool, and complex Workers declare Draft 2020-12 input_schema/output_schema that are validated as executable contracts. Every allocated Run gets an immutable run_id, manifest and versioned lifecycle events, with logs, audit records and artifacts under .agentloom; a logical task_id survives resume. Goal Mode keeps one root Supervisor objective across continuation segments and only that Supervisor can mark the Goal complete with evidence; checkpoints preserve the Goal and completed work. An optional durable extra uses DBOS 3.2.0 with SQLite for persistent Worker queues.
Reads an Application directory — Supervisor and Worker YAML, optional config/system.yaml, skills/, sysprompt/ — plus the model catalog in config/model.yaml, then runs through the agentloom/loom commands or execute_app(). The Python runtime owns model routing, Worker-tool generation, concurrency, permissions, Hooks, checkpoints and evidence, while deterministic preprocessing and output writing stay ordinary Python. Storage separates attempts from recoverable tasks: .agentloom/runs/<application_id>/<run_id>/ holds manifest.json, logs/runtime.log, audit/, artifacts/; .agentloom/checkpoints/<application_id>/<task_id>/ holds checkpoint.json, workers/, todos.json, goal.json, context_store/, file-history/. The CLI emits --output-format json or jsonl, and execute_app() returns an ApplicationRunResult with output, timestamps, structured Goal state and a RunInfo receipt. The durable adapter submits via app.durable(root=...).worker(...).submit_many(items, revision="1") and a dedicated consumer runs with loom durable serve.
- Release review teams combining an api_reviewer and test_reviewer Worker into one decision pipeline.
- Platform teams needing run_id, audit and recovery points for long tasks and incident review.
- CI/CD maintainers calling
loom run ... --output-format jsonland consuming lifecycle events elsewhere. - Analysts processing many repositories with
app.worker(path).map(items)or persistent durable queues. - Teams building internal coding assistants that create, validate and run Applications from the YAML contract.
How do you install or deploy this agent?
The source installer targets macOS and Linux shells and requires Git and Bash. It installs uv via its official installer if missing, creates an isolated environment in the checkout's .venv, and writes agentloom/loom launchers to .agentloom. A custom location is set with AGENTLOOM_INSTALL_DIR=/path/to/install.
How do you use this agent?
Create config/model.yaml (Git-ignored) with a model catalog, then write Supervisor and Worker YAML in an Application directory. Run the included code-review Application and optionally request JSONL events; from Python use execute_app() or Application.open() for structured results. Persistent queues require the durable extra and a dedicated consumer process.
What are this agent's strengths and limitations?
- Typed Worker contracts: Draft 2020-12
input_schema/output_schemaare validated at runtime instead of being prompt conventions. - Auditable Runs: immutable
run_id, manifest, versioned lifecycle events and audit directories, with preflight rejections emitted before storage exists. - Resume semantics: a logical
task_idsurvives resume, and Goal, Todo, context-store and file-history each have their own storage location. - Layered authority: Skills are on-demand model-context packages, Hooks are separately authorized runtime code, and tool/file/Shell/MCP access stays governed by Agent config.
- Durable queues built on DBOS 3.2.0 with SQLite by default for admission, retries and recovery.
- The installer only supports macOS and Linux shells and needs Git/Bash; Windows is not documented.
- Durable execution is validated only under macOS launchd; Linux and real PostgreSQL or multi-host execution are stated as unvalidated.
- The repository license is unknown, so adoption may require separate legal review.
- Models must be reached through an OpenAI-compatible endpoint with your own key and base URL.
- The architecture notes that old
src.*imports and module commands were removed, so existing code needs the migration map.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| AgentLoom This agent | 52 · Major gaps | — | ★ 169 | 13d ago | Python | OpenAI API |
| Pi Dynamic Workflows | 88 · Good | Agent plugin / skillFree + model costs | ★ 590 | 8d ago | TypeScript | — |
| Maestro-Flow | 52 · Major gaps | CLIFree + model costs | ★ 574 | 10d ago | TypeScript | Codex · Claude Code · Claude API |
| Docker Agent | 46 · Major gaps | CLIFree + model costs | ★ 4.7k | today | Go | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Docs describe tool allowlists, path_validation, shell sandboxing, and Worker permissions not inheriting Supervisor overrides, indicating a reasonably designed least-privilege model (least_privilege=2). User confirmation is thin: Goal completion and memory promotion require human initiation, but destructive Shell/file writes lack an explicit confirmation flow (user_confirmation=1). Data flow transparency is supported by physical isolation of model.yaml vs system.yaml, api_key filtering, and redacted records (data_flow_transparency=2). Sensitive data handling has isolation and redaction but no key rotation/encryption detail (sensitive_data_handling=2). Dependency security uses uv.lock, --require-hashes, and pinned versions, but the dependency surface is very broad (docker, sentry, langfuse) with no vulnerability-scan evidence (dependency_security=2). External effects include durable queues, launchd, and Shell execution, but replay/side-effect commit relies on a 'trusted host' assertion without enforced confirmation (external_effects=1). Rollback is supported by checkpoints, resume, file-history, and run retention (rollback=2). Source attribution mentions OpenClaw source reference and a Pi license file but lacks a complete third-party attribution list (source_attribution=1).
Docs are consistent on Run/task identity, preflight rejection, structured failures, and JSON/JSONL parity (self_consistency=2). Dependency availability is documented with locks and install profiles, but Pi needs Node 22.19+ and SQLite 3.51.1 deadlock must be avoided, showing environment sensitivity (dependency_availability=2). Failure messages include run.rejected, WorkerBatchError, and diagnostic errors (failure_messages=2).
Targets multi-agent orchestration with rich example applications (audience_and_scenarios=2). Capability boundaries are documented via runtime registry values, schema contracts, and Skills not granting authority (capability_boundaries=2). Trigger precision covers YAML and schedules but lacks precise trigger conditions and misfire safeguards (trigger_precision=1). Environment fit is partial: only macOS/Linux partly validated, Linux durable and PostgreSQL unvalidated, Windows only via wexpect dependency (environment_fit=1).
Information architecture is clear with TOC and cross-links (information_architecture=2). Install notes are detailed with uv, profiles, and wheel install (install_notes=2). Naming stability is weakened by migrations and deprecated legacy interfaces (src.* removal, legacy batch) (naming_stability=1). Examples and FAQ exist via example apps and a common-errors section (examples_and_faq=2). Known limitations are explicitly listed (known_limitations=2). License metadata is unknown and no LICENSE file is present (license=0). Version 1.0.1 exists but no CHANGELOG (versioning_changelog=1). Maintenance responsibility is only a personal email and issues, with unverified publisher (maintenance_responsibility=1).
Output usability is supported by structured Run results, JSON/JSONL, and artifacts (output_usability=2). Marginal value comes from YAML orchestration, typed Workers, and resumable Runs, differentiating it from generic frameworks (marginal_value=2). Cost-benefit is weakened by a large dependency set, complex install, Node requirement, and multiple profiles (cost_benefit=1).
Claim traceability is partial with doc and spec links but mostly self-asserted without per-claim evidence mapping (claim_traceability=1). Cross-source corroboration exists across README, docs, CI, and pyproject, but test results were not verified in this static review (cross_source_corroboration=1). Fact/inference separation is suggested via 【推断】 labeling, but the boundary between claims and implementation evidence is unclear (fact_inference_separation=1).
- License metadata is unknown and no LICENSE file is present; confirm authorization before commercial use.
- Publisher identity is unverified; maintenance responsibility and update path are unclear.
- The dependency surface is very broad (docker, sentry, langfuse, litellm, etc.) with no vulnerability-scan evidence; audit independently.
- Durable execution is only partly validated on macOS; Linux and PostgreSQL are unvalidated, and SQLite 3.51.1 has a known deadlock to avoid.
- Destructive Shell/file writes lack an explicit user confirmation flow, and external side-effect replay relies on a 'trusted host' assertion.
- Deprecated legacy interfaces and naming migrations (src.* removal, legacy batch) may break compatibility on upgrade.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Highlights - Added local Codex Exec tool support: AgentLoom can register local codex exec as a normal function tool. - Added fixed_args support so workflows can lock tool inputs and prevent LLM overrides. - Added codex_exec_demo showing sequential Codex tool calls through structured tool_call mode. - Bumped AgentLoom package, system version, User-Agent, badges, and docs to 1.0.1.View on GitHub ↗ -
v1.0.0 AgentLoom v1.0.0
Release notes excerpt
AgentLoom v1.0.0 AgentLoom v1.0.0 is the first stable public release of the project. Highlights - Configuration-driven multi-agent application runtime - Supervisor / Worker agent workflow model - Worker agents exported as callable tools - Built-in file, shell, search, code editing, git, todo, and skill tools - MCP client integration for external tools - Runtime safety controls, path boundaries, and shell execution policies - Checkpoint resume and long-task recovery - Rich terminal logs, run archives, Web UI, and dashboard monitoring …View on GitHub ↗
FAQ
Do I need an OpenAI-compatible model service?
config/model.yaml expects openai/<model-id> entries with an API key and optional base_url, so you supply the model provider or compatible endpoint.Can the durable queue run on Linux?
How do I debug a failed Run?
RunInfo receipt and write to logs/runtime.log, audit/ and artifacts/ under .agentloom/runs/<application_id>/<run_id>/; preflight rejections emit run.rejected before storage is created.Can CI consume events from runs?
loom run ... --output-format json or jsonl emits machine-readable lifecycle events, and Python callers read the same canonical state through execute_app().