Agent Loop

轻量级 AI Agent 框架 — 工具调用 · 上下文压缩 · 子智能体派生

架构

agent_loop/
├── __init__.py        # 版本
├── config.py          # 配置管理（环境变量 → frozen dataclass）
├── providers/
│   └── __init__.py    # LLM 抽象层（DashScope / OpenAI 兼容）
├── tools.py           # 工具注册表 + 内置工具（bash/read/write/edit）
├── context.py         # 上下文管理（token 估算 / 微压缩 / 自动压缩）
├── tasks.py           # 文件系统任务管理器（依赖图 + 自动解锁）
├── skills.py          # 技能加载器（解析 SKILL.md frontmatter）
├── todos.py           # 待办事项管理器
├── loop.py            # 核心对话循环引擎
└── cli.py             # CLI 入口

快速开始

# 安装依赖
pip install -e .

# 配置环境变量
cp .env.example .env
# 编辑 .env 填入 API_KEY 和 MODEL_ID

# 启动
agent-loop
# 或
python -m agent_loop.cli

核心概念

对话循环 (Agent Loop)

每次调用是一次独立的对话。模型通过工具调用与文件系统交互，直到停止调用工具或达到迭代上限。

工具注册表 (Tool Registry)

声明式注册：每个工具定义 name / description / parameters / handler，注册表自动转换为 OpenAI function-calling 格式。添加自定义工具只需创建 ToolDef 并调用 registry.register()。

上下文压缩

• 微压缩 (micro_compact): 替换早期工具返回的冗长内容为占位符
• 自动压缩 (auto_compact): token 超阈值时，LLM 生成摘要并重置对话，完整记录存档到 .transcripts/

子智能体

通过 task 工具派生子智能体，共享文件系统但不共享对话历史。支持嵌套派生（默认最大 1 层）。

任务管理

基于文件系统的多步任务编排，支持依赖关系。任务完成时自动解锁下游任务。

添加自定义工具

from agent_loop.tools import ToolDef, ToolRegistry, build_default_registry

my_tool = ToolDef(
    name="my_api",
    description="Call my custom API",
    parameters={"url": {"type": "string"}},
    required=["url"],
    handler=lambda url: f"Fetched {url}",
)

registry = build_default_registry([my_tool])

切换 LLM 后端

from agent_loop.providers import get_provider

# DashScope (默认)
provider = get_provider("dashscope")

# OpenAI 兼容（vLLM / Ollama / OpenRouter）
provider = get_provider("openai", base_url="http://localhost:11434/v1")

License

MIT