AgentLoom

Build multi-agent applications from YAML. Operate them from an evidence-aware terminal Studio.

Typed Workers, permissioned edits, resumable Runs, explicit Goal completion, and review-gated memory share one runtime truth.

_{Real reduced-motion terminal session using the current Chinese UI. The Studio indexes Applications, Skills, validation state, Runs, and commands from the project.}

AgentLoom treats a multi-agent system as an Application with an execution contract. YAML defines the Supervisor, typed Workers, models, tools, Skills, Hooks, permissions, and runtime policy. Application Studio can change that contract, show the Diff, request permission for side effects, run it, read structured evidence, and continue repairing failures.

Why AgentLoom

Workers become typed tools

A Supervisor explicitly selects Workers through worker_agents; each selected Worker becomes a callable tool named and described by that Worker. Simple Workers use the default task: string input and text output. Complex Workers declare Draft 2020-12 input_schema and output_schema, which runtimes validate as executable contracts rather than prompt conventions.

Runs produce evidence, not terminal guesses

Every allocated Run receives an immutable run_id, manifest, and versioned lifecycle events, with bounded file logs when enabled plus audit records and artifacts. A logical task_id survives resume. The Studio, CLI JSON/JSONL, and Python API read the same canonical state. Preflight rejection occurs before a Run or its storage is allocated.

Long-running work has an explicit owner

Goal Mode keeps one root Supervisor objective active across continuation segments and Worker delegation. Only that Supervisor can mark the Goal complete with evidence. Checkpointing preserves the Goal and completed work across interruptions and resume.

Memory has review boundaries

Self-Learning v6 stores searchable history and evidence-gated memory separately. Fact and experience candidates pass evidence gates and the configured scope-approval policy; promotion to Project scope is always initiated by a person.

Extensions do not silently gain authority

Skills are model-context packages loaded on demand. Hooks are separately and explicitly authorized runtime code. Built-in tool metadata is discoverable without importing implementations, while actual tool, file, Shell, and MCP access remains governed by Agent configuration and permissions.

Quick start

The source installer builds the Studio and prepares a locked Python environment for the current checkout:

git clone https://github.com/linora-u/AgentLoom.git
cd AgentLoom
./install

It currently supports macOS and Linux shells and requires Git and Bash. It installs missing uv and Bun through their official installers, then places the compatible unit under ~/.agentloom. Open a new terminal and verify it:

agentloom --version
agentloom --snapshot

The source installer defaults to smol plus professional code tools. For Pi without smol, use ./install --runtime pi with Node 22.19+ and npm available; it automatically downloads the pinned SDK and builds AgentLoom's bridge. See runtime installation profiles for locked checkout/release commands and clean Application verification.

Create the local model configuration:

cp config/llm.example.yaml config/llm.yaml

model:
  default_model_type: powerful
  powerful:
    model: "openai/<model-id>"
    api_key: "<api-key>"
    base_url: "https://<openai-compatible-endpoint>"  # optional for OpenAI
    tool_choice: "auto"
  fast:
    model: "openai/<fast-model-id>"
    api_key: "<api-key>"
    base_url: "https://<openai-compatible-endpoint>"
    tool_choice: "auto"

config/llm.yaml is ignored by Git and is the only model catalog used by both Studio and Application Agents. Start the Studio from any AgentLoom project:

agentloom

# Or inspect another checkout
agentloom --project /path/to/project

Try a request with explicit roles and acceptance criteria:

Create an Application named release_review.
Use one Supervisor and two Workers for API review and test review.
Choose model types from config/llm.yaml.
Validate it and ask before the first real Run.

Studio edits the selected Application directly and shows each Diff. Its loop is:

inspect → edit → validate → request Run permission → execute → inspect evidence → repair

If execution is not approved, Studio reports “configuration validated, not run.” It does not turn static validation into a success claim.

Application Studio

The Studio is an Applications-first control plane, not a thin log viewer.

• Application workspace: browse Effective Config, Supervisor/Worker topology, source attribution, models, Tools, Skills, Hooks, MCP, permissions, and validation.
• Agent Loop: inspect the project, modify the selected Application, display Tool and Diff cards, ask business questions, run smoke checks, and diagnose failed Runs.
• Permission boundary: Application Only permits project reads and writes inside the selected Application. Shell, global files, other Applications, and unknown new paths require a visible decision. Full Access is an explicit Session toggle and resets on exit.
• Session continuity: switching Applications keeps Studio conversation memory; /new starts fresh and /compact compresses the active context while preserving completed file changes and durable history.
• Revision safety: each Run pins its Application content hash. Later edits change the Working Revision but never hot-switch an active Running Revision.
• Run diagnostics: summaries expose terminal state, Goal progress, token usage, completion evidence, and recovery actions without dumping raw events.

Action	Key / command
Send a Studio message	Enter
Search Applications, Agents, Skills, Runs, models, permissions, and commands	Ctrl+X
Start a fresh conversation	/new
Compact the current conversation	/compact
Select a Studio model	/models
Refresh the project index	/refresh
Diagnose the selected failed Run	a
Close detail, reject a decision, or interrupt the Agent Loop	Esc

See Application Studio for screen behavior, architecture, updates, schedules, and contributor commands.

Define an Application

An Application keeps its Supervisor, Workers, prompts, optional tools, and outputs together:

applications/release_review/
├── workflows/
│   ├── release_review_agent.yaml
│   └── worker_agents/
│       ├── api_reviewer.yaml
│       └── test_reviewer.yaml
├── config/system.yaml          # optional Application overlay
├── skills/                     # optional private Skills
└── sysprompt/                  # optional prompt templates

Backend-specific execution settings belong only in runtime_options. Historical top-level smol fields are silently ignored without conversion or rejection.

A Supervisor references Worker definitions:

name: "release_review"
agent_runtime: "smolagents"
description: "Review an API release and its test evidence."
model_type: "powerful"

worker_agents:
  - path: "applications/release_review/workflows/worker_agents/api_reviewer.yaml"
  - path: "applications/release_review/workflows/worker_agents/test_reviewer.yaml"

workflow: |
  Ask both Workers for evidence, reconcile conflicts, and return one release decision.

tools: []
runtime_options:
  max_steps: 12
goal:
  enabled: true

Each Worker exposes the contract seen by its Supervisor. Omit both schemas for the default task: string input and text output; declare them when typed JSON is part of the actual contract:

name: "api_reviewer"
agent_runtime: "smolagents"
description: "Review API compatibility risks."
model_type: "fast"

input_schema:
  type: object
  properties:
    request:
      type: string
      description: "Release scope and API diff."
  required: [request]
  additionalProperties: false

output_schema:
  type: object
  properties:
    decision:
      type: string
      enum: [compatible, incompatible]
    findings:
      type: array
      items:
        type: string
  required: [decision, findings]
  additionalProperties: false

workflow: |
  Review the request, cite evidence, and return prioritized findings.

tools: []
worker_agents: []
runtime_options:
  max_steps: 8

Run the Supervisor directly:

uv run --locked --extra smol --extra code loom run applications/release_review/workflows/release_review_agent.yaml

Or ask a Skill-aware coding assistant to read agentloom-framework-skill/SKILL.md, create the files, validate them, run the Application, and inspect .agentloom evidence.

Runtime model

The Python runtime owns model routing, Worker-tool generation, concurrency, permissions, Hooks, checkpoints, and evidence. Deterministic preprocessing, validation, caching, and output writing remain ordinary Python code.

Runtime storage separates attempts from recoverable tasks:

.agentloom/
├── runs/<application_id>/<run_id>/
│   ├── manifest.json
│   ├── logs/runtime.log
│   ├── audit/
│   └── artifacts/
├── checkpoints/<application_id>/<task_id>/
│   ├── checkpoint.json
│   ├── workers/<worker>/calls/<index>/checkpoint.json
│   ├── todos.json
│   ├── goal.json
│   ├── context_store/
│   └── file-history/
└── workspaces/agents/<application_id>/<agent_path>/
    ├── insights.md
    └── tasks/<task_id>/{context.md,trace.md}

Goal, Todo, context-store, file-history, and Recall files appear only when the corresponding feature is configured or used.

Run and integrate

Run the included code-review Application without creating a new Application:

uv run --locked --extra smol --extra code loom run applications/ai_quality_analysis/workflows/code_review_agent.yaml

Use machine-readable lifecycle events when another program owns execution:

uv run --locked --extra smol --extra code loom run <workflow> --output-format json
uv run --locked --extra smol --extra code loom run <workflow> --output-format jsonl

For programmatic execution, execute_app() returns an ApplicationRunResult with output, timestamps, structured Goal state, and a RunInfo receipt:

from agentloom.app.runner import execute_app

result = execute_app("applications/release_review/workflows/release_review_agent.yaml")
print(result.output, result.run.run_id)

Framework source lives directly in src/app/, src/execution/, src/integrations/, and the other responsibility modules. Installation maps src/ to the Python package name agentloom: the import above loads src/app/runner.py. There is no extra agentloom source directory. Use uv sync --python 3.12 --locked --all-groups --extra smol --extra code to install the checkout before calling Python APIs. The old src.* imports and module commands are removed; supported commands are loom and python -m agentloom. See the architecture and migration map for module ownership and migration details.

Post-allocation failures carry the same receipt; preflight rejection emits run.rejected before storage exists. See Structured Run API.

Durable schedules use the same Application contract and Run lifecycle. Their automatic firing is a separate foreground service, so closing the Studio does not leave a hidden daemon:

agentloom schedules --project /path/to/project serve

Example Applications

Application	Demonstrates
ai_quality_analysis	Twelve specialized Workers coordinated into staged code review
unit_test_studio	Strict pytest generation with a deterministic Python entrypoint
repo_map	Deterministic preprocessing, bottom-up Agent analysis, batching, and progress persistence
goal_mode_validation	Explicit Goal completion, continuation, and checkpoint resume
self_learning_smoke	Session history, memory proposals, evidence, and review boundaries

Documentation

Document	Covers
Configuration Overview	Configuration layers, merging, and isolation
Agent Configuration	Supervisor and Worker YAML fields
Tool Catalog	Lazy implementation loading, toolsets, metadata, and extension rules
Skills	Discovery, on-demand activation, and permission boundaries
Hooks	Explicit authorization, events, transforms, and failure semantics
Goal Mode	Continuation, completion ownership, resume, and schedules
Checkpoint and Runtime Storage	Run/task identity, evidence, recovery, and retention
Self-Learning v6	History, candidates, review, approval, and promotion
Structured Run API	Python receipts, typed failures, JSON, and JSONL

Development and support

# Framework
uv run --locked --extra smol --extra code pytest tests -q

# Studio
cd studio
bun test
bun run typecheck

• Issues: github.com/linora-u/AgentLoom/issues
• Contact: raine_walker@163.com
• Studio provenance and notices: studio/upstream/README.md

If AgentLoom helps your project, consider starring the repository or contributing a focused Application, fix, or validation case.