AgentLoom

用 YAML 构建和运行多 Agent 应用。

类型化 Worker、权限确认、断点恢复、Goal 显式完成和经审核的记忆，都以同一套运行时权威状态为准。

AgentLoom 把多 Agent 系统当成一个有执行契约的 Application。YAML 定义 Supervisor、类型化 Worker、模型、Tool、Skill、Hook、权限和 Runtime 策略。 通过 CLI 或 Python API 执行 Application，并读取结构化运行证据。

核心价值

Worker 会成为类型化工具

Supervisor 通过 worker_agents 显式选择 Worker；每个被选中的 Worker 会自动成为 以自身 name 和 description 命名、说明的可调用 Tool。简单 Worker 的 Tool 无参数， 任务来自自己的 YAML task，默认返回文本；复杂 Worker 使用 Draft 2020-12 input_schema / output_schema 声明由 Runtime 真正执行的结构化契约。

Run 产出证据，不靠解析终端猜状态

每个已分配存储的 Run 都有独立的 run_id、manifest 和带版本的生命周期事件； 启用文件日志时还会生成有界日志，并保留审计记录和产物。逻辑任务使用稳定的 task_id 恢复。CLI JSON/JSONL 和 Python API 读取同一份权威状态。预检 拒绝发生在 Run 及其存储分配之前。

长任务有明确的完成责任人

Goal Mode 让根 Supervisor 跨 continuation 和 Worker 调用持续推进同一个目标。 只有根 Supervisor 能携带证据完成 Goal；启用 checkpoint 时，中断后可恢复目标和已完成工作。

记忆有审核边界

Self-Learning v6 分开保存可搜索历史和经过证据门禁的记忆。 Fact 和 Experience 候选需通过证据门禁及作用域审批策略；提升到 Project 级别必须由人工发起。

扩展不会隐式获得权限

Skill 是按需加载的模型上下文包。Hook 是独立显式授权的 Runtime 代码。内置 Tool 的元数据可以在不导入实现的情况下发现；真正的 Tool、文件、Shell 和 MCP 权限 仍由 Agent 配置与权限策略决定。

快速开始

源码安装器使用 uv 创建独立、锁定依赖的 Python 虚拟环境，并安装当前版本的 agentloom 和 loom 命令：

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

目前支持 macOS 和 Linux Shell，需要 Git 与 Bash。安装器会通过官方安装器补齐 uv，再把虚拟环境安装到当前仓库的 .venv，命令包装和安装记录放在仓库的 .agentloom，无需手动激活环境。设置 AGENTLOOM_INSTALL_DIR=/path/to/install 可自定义安装根目录，虚拟环境位于该目录的 venv。打开新终端后验证：

agentloom --help
loom --help

默认安装 smol Runtime 和专业 code 工具。选择 Pi 时使用 ./install --runtime pi，并准备 Node 22.19+ 与 npm；安装器会下载锁定版本的 SDK 并构建桥接代码。agentloom update 会保留所选 Runtime。

创建本地模型配置：

cp config/model.example.yaml config/model.yaml

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

config/model.yaml 已被 Git 忽略，提供项目模型目录。Application 也可以在自身的 config/model.yaml 中定义模型；Agent YAML 通过 model_type 选择模型。

定义 Application

Application 将 Supervisor、Worker、提示词、可选 Tool 和输出放在一起：

applications/release_review/
├── workflows/
│   ├── release_review_agent.yaml
│   └── worker_agents/
│       ├── api_reviewer.yaml
│       └── test_reviewer.yaml
├── config/
│   ├── system.yaml             # 可选的 Application 覆盖配置
│   └── prompts/reviewer.md     # 可选的 Agent system prompt 正文
├── skills/                     # 可选的私有 Skill
└── sysprompt/                  # 可选的 runtime 提示词模板

Supervisor 引用 Worker 定义：

基座执行参数只写在 runtime_options 中。旧顶层 smol 字段静默忽略，不转换、不拒绝。

name: "release_review"
agent_runtime: "smolagents"
description: "Review an API release and its test evidence."
model_type: "powerful"
system_prompt:
  path: config/prompts/reviewer.md

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

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

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

每个 Worker 声明 Supervisor 看到的接口。省略两个 schema 时 Tool 无参数， Worker 执行自己的 YAML task 并返回文本；只有真实需要类型化 JSON 时才声明：

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

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

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

直接运行 Supervisor：

uv run loom run applications/release_review/workflows/release_review_agent.yaml

也可以让支持 Skill 的编程助手先读取 agentloom-framework-skill/SKILL.md， 再创建文件、校验配置、运行 Application，并检查 .agentloom 证据。

Runtime 模型

Python Runtime 负责模型路由、Worker Tool 生成、并发、权限、Hook、checkpoint 和 证据。确定性的预处理、校验、缓存和输出仍然使用普通 Python 代码。

Runtime 存储将执行尝试和可恢复任务分开：

.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 和 Recall 文件只会在对应能力已配置或被使用 时出现。

运行与集成

无需新建 Application，即可运行仓库内置的代码审查 Application：

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

其他程序负责调度时，使用机器可读的生命周期事件：

uv run --locked --extra smol --extra code loom run applications/ai_quality_analysis/workflows/code_review_agent.yaml --output-format json
uv run --locked --extra smol --extra code loom run applications/ai_quality_analysis/workflows/code_review_agent.yaml --output-format jsonl

在 Python 中调用 execute_app()，会返回包含输出、时间、结构化 Goal 状态和 RunInfo receipt 的 ApplicationRunResult：

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)

框架源码直接放在 src/app/、src/execution/、src/runtimes/、src/integrations/ 等职责模块中。 安装配置将 src/ 映射为 Python 包名 agentloom，所以上面的导入实际加载 src/app/runner.py，磁盘上不需要再套一层 agentloom 目录。 先运行 uv sync --managed-python --locked --all-groups，按仓库 .python-version 安装项目，再调用 Python API。 旧的 src.* 导入和模块命令已移除；命令入口为 agentloom、loom 和 python -m agentloom。 各模块职责与迁移方式见架构与迁移地图。

存储分配后的失败携带同一 receipt；若预检阶段拒绝运行，会在分配运行存储前发出 run.rejected 事件。详见结构化 Run API。

持久化 Schedule 复用相同的 Application 契约与 Run 生命周期。自动触发由单独的 前台服务负责，需要显式启动：

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

示例 Application

Application	展示能力
ai_quality_analysis	十二个专业 Worker 协作完成分阶段代码审查
repo_map	确定性预处理、自底向上 Agent 分析、批处理和进度持久化
goal_mode_validation	Goal 显式完成、自动续跑和 checkpoint 恢复
self_learning_smoke	Session 历史、记忆提案、证据和审核边界

文档

文档	内容
配置总览	配置分层、合并与隔离
Agent 配置	Supervisor 和 Worker YAML 字段
Tool Catalog	延迟实现加载、Toolset、元数据和扩展规则
Skills	发现、按需激活与权限边界
Hooks	显式授权、事件、输入转换和失败语义
Goal Mode	continuation、完成责任、恢复与调度
Checkpoint 与 Runtime 存储	Run/task 身份、证据、恢复和保留策略
Self-Learning v6	历史、候选、审核、审批与提升
结构化 Run API	Python receipt、类型化失败、JSON 与 JSONL

开发与支持

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

• Issue：github.com/linora-u/AgentLoom/issues
• 联系方式：[email protected]

如果 AgentLoom 对你的项目有帮助，欢迎 Star，或贡献一个边界清晰的 Application、 修复或验证用例。