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.

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.

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

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.

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.

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.

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

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

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.

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.

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 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.

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.

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.

The repository includes one root-level Agent Skill for AI coding assistants: agentloom-framework-skill/.

Use it when you want an assistant to develop with AgentLoom instead of guessing the framework shape from scratch. Ask the assistant to read agentloom-framework-skill/SKILL.md, then describe the capability you want to build or extend.

The Skill guides the assistant to clarify the goal, inputs, outputs, and acceptance criteria; decide whether a single Agent, Supervisor/Worker workflow, Tool, private Skill, Hook, or documentation change is the shortest path; create or update the relevant files; and record validation results in the README.

This Skill is a development aid for coding assistants. It is not stored under skills/, so AgentLoom runtime applications do not auto-load it as a normal runtime Skill.

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.