AgentLoom

Build complex multi-agent applications with simple configuration, minimal glue code, safe runtime controls, and first-class observability.

AgentLoom helps developers turn multi-agent workflows into runnable, observable, resumable, and controllable applications.

---

Quick Start

AgentLoom is designed to get you from repository clone to a real multi-agent application quickly.

git clone <repo-url> AgentLoom
cd AgentLoom

uv sync
# If PyPI is slow or unavailable on your network:
# UV_DEFAULT_INDEX=https://mirrors.aliyun.com/pypi/simple uv sync

cp config/llm.example.yaml config/llm.yaml
# Edit config/llm.yaml and add your model credentials.

uv run loom run applications/ai_quality_analysis/workflows/code_review_agent.yaml

After the first run, you should see:

• structured terminal logs with agent names, task IDs, step duration, and token usage;
• archived run files under .logs/<agent>/<timestamp>/;
• resumable task state when checkpointing is enabled;
• optional visualization through uv run loom ui;
• optional terminal monitoring through uv run loom dashboard.

What AgentLoom Provides

AgentLoom already implements the runtime pieces needed to build and operate complex agent applications:

Area	Implemented Capabilities
Multi-agent app assembly	Supervisor / Worker roles, YAML workflow, worker_agents, direct loom run, generated entry scripts with loom create, and Python embedding through run_app().
Agent-as-Tool	Workers export as callable tools through agent_function_schema, with generated function signatures, required-input validation, docstrings, string results, and .batch(tasks).
Execution modes	Structured tool_call mode for traceable orchestration and code_act mode for flexible code-execution tasks.
Python pre/post processing	Custom tool functions and wrappers for scanning, caching, loops, retries, validation, error isolation, progress persistence, and artifact writing.
Batch concurrency	Worker concurrency: auto or fixed concurrency, tool.batch(tasks), back-pressure, circuit breaker, progress callbacks, and per-call state isolation.
Skills and Hooks	Reusable Skills, force-injected / on-demand / hidden modes, lifecycle Hooks for tools, tasks, sub-agents, sessions, compaction, setup, and config changes.
Model and context control	Per-agent model_type, multiple LLM endpoints, parameter inheritance, retry behavior, prompt customization, and multi-layer context compression.
Tool ecosystem	Built-in file, shell, search, code-edit, git, todo, skill-loading, local Python tools, and local Codex Exec tools, plus MCP client integration.
Local Codex integration	Register local codex exec as a normal function tool, with multiple aliases, fixed_args, sandbox / search pass-through, and local Codex login/permission behavior.
Code intelligence	LSP service management for definition, references, symbols, hover, and workspace symbols, with tree-sitter fallback.
Runtime safety	Path boundaries, include/exclude rules, per-agent policies, shell command/operator allowlists, shell security checks, sandbox wrapping, and shell_audit.log.
Long-task resilience	Checkpoint resume, heartbeat detection, conversation recovery, tool-call error recovery, file history, worker skip-on-resume, and task cleanup.
Observability	Rich terminal logs, plain text file logs, per-step duration, cumulative/incremental token usage, task/subtask/agent context, and run archiving under .logs/.
UI and monitoring	Web UI with SSE updates, topology graph, timeline replay, multi-run grouping, plus TUI dashboard for active and resumable tasks.
Reference applications	ai_quality_analysis, unit_test_studio, repo_map, and codex_exec_demo demonstrate direct runs, custom Python entrypoints, strict pipelines, concurrent Worker analysis, and local Codex tool calls.

Why AgentLoom

Build Complex Agent Apps With Less Code

Many agent frameworks give you components. AgentLoom gives you an application shape.

Complex agent applications often grow the same glue code again and again: Worker registration, parameter adapters, runtime entrypoints, pre/post processing, batch execution, logging, tracing, and safety controls. That code is costly because it is rarely reusable when the next agent application has a different workflow.

Worker Agents are exported as callable tools, and Supervisor Agents load and schedule them automatically. That means a complex workflow can be assembled from focused agents, a small amount of business glue code, and a direct runtime entrypoint.

AgentLoom moves the reusable parts into YAML and the runtime. YAML describes the workflow, Worker list, tools, models, permissions, and skills; Workers become callable tools; Supervisors load them automatically; Python stays focused on the application-specific parts such as preprocessing, postprocessing, caching, loops, validation, and artifact writing. Skills and Hooks package lifecycle behavior so it can be reused across applications.

You can start with:

• uv run loom run <workflow> to run an application directly;
• uv run loom create <workflow> to generate a Python entry script;
• run_app("<workflow>") to embed an AgentLoom app inside your own Python pipeline;
• tool.batch(tasks) to call the same Worker Agent across many inputs in parallel.

This is the core development-cycle win: you spend less time building orchestration plumbing and more time shaping the actual agent roles, tools, and task flow.

How AgentLoom Is Different

Common Agent Framework Pattern	AgentLoom's Approach
Component-first: users assemble low-level primitives themselves.	Application-first: run, generate, embed, monitor, and resume multi-agent apps directly.
Each complex app tends to grow a new layer of glue code.	Reusable orchestration, runtime controls, observability, and lifecycle extensions live in AgentLoom; app code handles business-specific differences.
Safety, recovery, and observability are often added later.	Runtime guardrails, checkpoints, logs, audit trails, UI, and dashboard are built into the framework path.
Logs mostly describe model calls and final output.	Logs are designed to debug agent application structure: task, subtask, agent, step, token, checkpoint, and topology.
Good for quick demos, but production-like runs need extra infrastructure.	Built for long-running, unattended tasks that need progress, recovery, and post-run analysis.

Build A multi-agent App With Less Code

AgentLoom's core model is simple:

flowchart LR
    User["Application / CLI"] --> Supervisor["Supervisor Agent"]
    Supervisor --> WorkerA["Worker Agent as Tool"]
    Supervisor --> WorkerB["Worker Agent as Tool"]
    Supervisor --> LocalTools["Local Tools"]
    Supervisor --> MCP["MCP Tools"]
    WorkerA --> Runtime["Runtime Controls"]
    WorkerB --> Runtime
    Runtime --> Logs["Logs / Checkpoints / UI"]

The important part is the boundary:

• a Worker Agent defines its purpose, tools, inputs, and output contract;
• AgentLoom turns that Worker into a callable Python tool with a real function signature;
• the Supervisor calls Workers like tools and coordinates the full task;
• business Python can still wrap the workflow for deterministic steps such as scanning, caching, validation, argument parsing, and artifact writing.

Where The Glue Code Goes

Work That Usually Becomes Glue Code	AgentLoom Placement
Reusable agent orchestration	YAML workflow and worker_agents.
Worker parameter adaptation	agent_function_schema and generated function signatures.
Project-specific pre/post processing	Python wrappers registered as tools.
Cross-application lifecycle behavior	Skills and Hooks.

The repo_map application demonstrates this hybrid style: deterministic Python scans and ranks a repository, then AgentLoom calls Worker Agents to analyze directories and produce architecture documentation.

Example Applications

The applications/ directory contains working apps that show how AgentLoom is intended to be used.

Application	What It Builds	What It Demonstrates
ai_quality_analysis	Multi-dimensional code review application.	12 Worker Agents, staged review, direct loom run, long-running codebase analysis.
unit_test_studio	Python pytest generation workflow.	Strict multi-step pipeline, custom entry script, function intake, scenario planning, test generation, refinement, delivery report.
repo_map	Repository architecture map generator.	Deterministic Python preprocessing plus Agent-driven analysis, bottom-up directory processing, tool.batch(tasks), progress persistence.
codex_exec_demo	Local Codex Exec tool-call example.	Direct loom run, normal function tool registration, fixed_args for Codex parameters, structured tool_call sequencing.

Run the default code review example:

uv run loom run applications/ai_quality_analysis/workflows/code_review_agent.yaml

Run Repo Map with a custom Python entrypoint:

uv run python applications/repo_map/repo_map_app.py /path/to/project \
  --output_dir /tmp/repo-map-output \
  --exclude_dirs vendor \
  --exclude_dirs build

Generate pytest tests for selected functions:

uv run python applications/unit_test_studio/studio_runner.py \
  /path/to/your/project \
  "src/utils.py:parse_config,src/core.py:run_pipeline" \
  --output_dir tests/generated

Run the local Codex Exec tool example:

uv run loom run applications/codex_exec_demo/workflows/use_codex_exec_demo.yaml

Core Concepts

Agent As Tool

Worker Agents can be exported as callable tools. AgentLoom generates function signatures, validates required inputs, builds the task payload, and returns a string result. The same Worker can also expose .batch(tasks) for parallel execution.

Supervisor / Worker

A Supervisor Agent coordinates the task. Worker Agents specialize in one part of the job. This keeps responsibilities explicit and makes the workflow easier to debug.

Workflow

A workflow describes what an agent should accomplish and how the Supervisor should use its Workers. AgentLoom uses the workflow to build the runtime task specification and keep long-running runs aligned.

Skills And Hooks

Skills add reusable knowledge or behavior. Hooks attach logic around task lifecycle, sub-agent lifecycle, tool calls, and other runtime events. They can be used for validation, memory, policy enforcement, result transformation, and visualization collection.

Execution Modes

AgentLoom supports structured tool calling for controlled orchestration and code execution mode for more flexible programming tasks. Each agent can choose the mode that fits its role.

Local Codex Tool

AgentLoom includes src.tools.codex.codex_tool.codex, which exposes local codex exec as a normal function tool. Register it in Agent YAML with module/function; no dedicated system.yaml Codex section is required.

Use fixed_args to lock inputs such as prompt, cwd, sandbox, and search. Fixed inputs are bound by the framework and removed from the LLM-visible tool schema; unfixed inputs remain available for the LLM to provide. sandbox: "" omits --sandbox and lets the local Codex CLI configuration decide permissions. search: "true" passes --search; search is off by default. Before running the tool, make sure codex is on PATH and codex login status succeeds.

CLI Reference

Command	Purpose
uv run loom run <workflow>	Run an AgentLoom application.
uv run loom create <workflow>	Generate a Python entry script for an application.
uv run loom ui	Open the Web visualization panel.
uv run loom dashboard	Open the terminal task dashboard.
uv run loom list-tasks	List resumable checkpoint tasks.
uv run loom clean-tasks	Clean old checkpoint data.

Documentation

Document	Description
Configuration Overview	Configuration layers, merge rules, and model configuration isolation.
Agent Configuration	Supervisor/Worker fields, tools, model selection, workflows, and skills.
LLM Configuration	Model types, provider settings, inheritance, retries, and prompt cache settings.
System Configuration	Runtime settings, permissions, logging, execution environments, and tools.
Skills Configuration	Skill package format, loading, invocation controls, and built-in skills.
Hooks Reference	Lifecycle events, hook types, matching, and execution behavior.
Checkpoint Resume	Checkpoint layout, resume behavior, and long-task recovery.

Development Skills

The tools/skills/ directory provides optional development skills for AI coding assistants working on AgentLoom applications:

Skill	Purpose
create-app	Generate an AgentLoom application scaffold.
create-skill	Create a custom AgentLoom skill.
workflow-review	Review Agent/Tool boundaries, orchestration contracts, and resilience design.
shell-security	Configure shell execution safety policies.
update-skills	Keep development skills aligned with source and docs changes.

These are development aids, not required runtime dependencies.

Support & Contributing

AgentLoom is built as a practical framework for complex agent automation. Issues, feature ideas, docs improvements, and example applications are welcome.

• Open an issue: GitHub Issues
• Contact: raine_walker@163.com
• If the project helps you, a GitHub star makes it easier for others to find.