# agentloop

**Repository Path**: yang-bicheng/agentloop

## Basic Information

- **Project Name**: agentloop
- **Description**: Agent execution loop framework with state machine, LLM gateway, and tool system
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-13
- **Last Updated**: 2026-05-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# agentloop

本地运行的 Agent 执行循环；LLM 走远程 API（OpenAI / Claude / OpenAI 兼容端点）。

**核心是执行循环**：状态机 + 并发工具调用 + 审批 + 上下文压缩 + 预算守护 + 中断恢复 + Spec 开发模式。

---

## 📐 架构速览

```
┌────────────┐
│    CLI     │  typer: alp run / history / show / ls-tools / spec
└─────┬──────┘
      │
┌─────▼───────────────────────────────────────────────────────────┐
│                      AgentRunner  (M6 ★)                        │
│   状态机: THINKING → ACTING → OBSERVING → ...                   │
│   预算 · 审批 · 压缩 · HITL · SIGINT/resume                     │
└──┬──────────┬──────────┬─────────┬────────────┬─────────────────┘
   │          │          │         │            │
┌──▼──┐  ┌───▼───┐  ┌───▼──┐  ┌───▼───┐  ┌────▼────┐
│ LLM │  │ Tools │  │Safety│  │ Store │  │ Strategy │
│ GW  │  │ +Exec │  │      │  │+Trace │  │          │
└─────┘  └───────┘  └──────┘  └───────┘  └──────────┘
```

- **LLM Gateway**：OpenAI / Anthropic / OpenAI 兼容 三种 provider；统一 ChatResponse
- **Tools**：`@tool` 装饰器注册，自动生成 JSON Schema；并发执行 + 互斥锁 + 超时
- **Safety**：workspace 路径沙箱 + shell 白/黑名单 + 交互审批
- **Store**：SQLite 三表（runs / steps / messages）+ JSONL trace 可回放
- **Strategy**：function_calling（默认）/ react / plan_execute

详细模块文档见 [`docs/modules/`](docs/modules/README.md)。

---

## 🚀 快速开始

### 1. 安装

```bash
pip install -e .
```

### 2. 配置 API Key（任选其一）

```bash
cp .env.example .env
# 编辑 .env 填入 OPENAI_API_KEY / ANTHROPIC_API_KEY / DEEPSEEK_API_KEY ...
```

（可选）复制配置文件，换 provider / 调整预算 / 白名单：

```bash
cp agentloop.example.yaml agentloop.yaml
```

### 3. 自检

```bash
alp doctor
```

### 4. 跑第一个任务

```bash
# 最小例子：让 Agent 读当前目录并总结
alp run "列出当前目录，告诉我这是个什么项目"

# ReAct 策略 + 自动审批
alp run "统计当前目录 python 文件行数" --strategy react --yes

# 限制可用工具
alp run "读 README.md 总结要点" --tools fs.read,final_answer --yes
```

### 5. 查看历史

```bash
alp history
alp show <run_id>
```

### 6. Spec 开发模式

```bash
alp spec req "一个 todo cli"      # → docs/spec/requirements.md
alp spec design                    # 读 req 生成 design.md
alp spec tasks                     # 读 design 生成 tasks.md
```

---

## 🔧 CLI 命令总览

| 命令 | 用途 |
|------|------|
| `alp run "<goal>"` | 运行一次 Agent |
| `alp history` | 列出历史 run |
| `alp show <run_id>` | 查看某次 run 的每步细节 |
| `alp ls-tools` | 列出已注册工具 |
| `alp doctor` | 检查配置 / API key / workspace |
| `alp spec req/design/tasks` | Spec 开发模式 |
| `alp version` | 显示版本 |

常用参数：
- `--strategy, -s`：`function_calling` / `react` / `plan_execute`
- `--yes, -y`：跳过所有审批
- `--tools`：工具白名单（逗号分隔）
- `--max-iter`：最大迭代数
- `--workspace, -w`：工作区根目录
- `--config, -c`：额外配置文件路径

---

## 🛠 Provider 配置示例

### OpenAI
```yaml
provider:
  type: openai
  model: gpt-4o-mini
  api_key_env: OPENAI_API_KEY
```

### Anthropic Claude
```yaml
provider:
  type: anthropic
  model: claude-3-5-sonnet-20241022
  api_key_env: ANTHROPIC_API_KEY
```

### DeepSeek（OpenAI 兼容）
```yaml
provider:
  type: openai_compat
  model: deepseek-chat
  base_url: https://api.deepseek.com/v1
  api_key_env: DEEPSEEK_API_KEY
```

### 阿里通义 / Moonshot / Ollama（同样 `openai_compat`）
只需改 `model` 和 `base_url`，API 协议都是 OpenAI 兼容。

---

## 📁 目录结构

```
src/agentloop/
├── __init__.py
├── __main__.py            # python -m agentloop
├── cli.py                 # M8 Typer 入口
├── config.py              # M1 配置
├── logging_setup.py       # M1 日志
├── models.py              # M2 数据模型
├── store.py               # M2 SQLite
├── trace.py               # M2 JSONL
├── llm/                   # M3
│   ├── base.py
│   ├── gateway.py
│   ├── openai_provider.py
│   ├── anthropic_provider.py
│   └── openai_compat.py
├── tools/                 # M4
│   ├── registry.py
│   ├── decorator.py
│   ├── executor.py
│   └── builtin/
│       ├── fs.py
│       ├── shell.py
│       └── meta.py
├── security/              # M5
│   ├── sandbox.py
│   └── approval.py
├── loop/                  # M6 ★
│   ├── runner.py
│   ├── context.py
│   └── budget.py
├── strategies/            # M7
│   ├── function_calling.py
│   ├── react.py
│   └── plan_execute.py
└── spec/                  # M9
    └── mode.py
```

---

## 🔒 安全模型

- **所有文件读写都必须在 workspace 之内**（路径穿越检查）
- **shell 命令**：白名单 + 黑名单双重过滤；默认要人工审批
- **审批粒度**：按工具名 + 参数
- **批准模式**：`y` 单次 / `A` 本 run 全部 / `n` 拒绝 / `q` 退出

---

## 💡 后续可扩展

- [ ] 子 Agent（`spawn_subagent` 工具）
- [ ] Resume（从 PAUSED 状态继续）
- [ ] 流式输出（provider stream=True）
- [ ] Web 搜索工具
- [ ] MCP 协议对接
- [ ] 自定义工具（在项目里 `import agentloop.tools.tool` 装饰即注册）

---

## 📜 License

MIT