# SimpleAgentLoop

**Repository Path**: xiaoyun2003/simple-agent-loop

## Basic Information

- **Project Name**: SimpleAgentLoop
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-05-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Simple Agent Loop

一个用于教学演示的 Python Agent Loop 项目。它使用 `while` 循环驱动模型思考、工具调用和最终回复，支持 OpenAI 兼容的 Chat Completions 接口，并提供一个流式聊天页面。

![Agent Loop 技术架构配图](docs/assets/agent-loop-cover.png)

## 功能

- OpenAI SDK 请求：通过 `OPENAI_BASE_URL`、`OPENAI_API_KEY`、`OPENAI_CHAT_MODEL` 对接 OpenAI 或兼容服务。
- while agent loop：模型可多轮决定是否调用工具，工具返回结果后继续推理。
- 简单工具调用：当前内置时间查询、文件列表、文本文件读取、文件发送、图片生成、命令执行。
- 流式聊天：浏览器通过 `fetch()` 读取 SSE 事件，逐步显示 Agent 回复。
- 工具过程展示：每条 Agent 消息上方显示可折叠工具过程，下方显示回复正文。
- 附件展示：`send_file` 可发送工作区文件，`gen_image` 可用 `gpt-image-2` 生成图片并展示。
- 教学注释和文档：核心模块保留注释，并在 `docs/` 中说明设计。

## 界面预览

工具调用过程默认折叠，只展示状态、工具名和摘要，点击「详情」可展开参数和结果。

![命令工具折叠展示](docs/assets/741568d75d48d840df9e1e87d18871ac.png)

`gen_image` 生成的图片会作为附件直接展示在 Agent 消息中。

![图片生成展示](docs/assets/13eae3391275f6d81caf3bf47f84d839.png)

## 技术架构

Agent Loop 的核心是「模型决策 -> 工具执行 -> 结果回填 -> 模型继续生成」。

![Agent Loop 控制流](docs/assets/agent-loop-control-flow.png)

消息协议依赖 `assistant.tool_calls` 和 `role=tool` 消息形成闭环。

![Agent Loop 消息协议](docs/assets/message-protocol.png)

前端通过 SSE 事件实时展示工具过程、附件和文本增量。

![SSE 流式事件](docs/assets/streaming-sse-events.png)

工具系统把模型可见的 Schema 和后端真实执行的 Handler 分离，并在执行边界上做限制。

![Tool Registry 与安全边界](docs/assets/tool-registry-sandbox.png)

## 快速开始

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
```

编辑 `.env`：

```env
OPENAI_API_KEY=你的 API Key
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
OPENAI_CHAT_MODEL=qwen3.6-plus
OPENAI_THINKING_ENABLED=false
OPENAI_REQUEST_TIMEOUT_MS=120000
OPENAI_MAX_OUTPUT_TOKENS=16000
OPENAI_IMAGE_BASE_URL=https://yunwu.ai/v1
OPENAI_IMAGE_API_KEY=你的图片 API Key
OPENAI_IMAGE_MODEL=gpt-image-2
OPENAI_IMAGE_SIZE=1536x1024
OPENAI_IMAGE_QUALITY=high
```

项目仍兼容 `LLM_BASE_URL`、`LLM_API_KEY`、`LLM_MODEL` 这组旧变量；如果两组同时存在，会优先读取 `OPENAI_*`。

启动：

```powershell
python main.py
```

打开浏览器访问：

```text
http://127.0.0.1:8000
```

也可以使用：

```powershell
uvicorn app.server:app --reload --host 127.0.0.1 --port 8000
```

## 目录结构

```text
SimpleAgentLoop/
  app/
    agent_loop.py     # while 循环、工具调用、事件输出
    attachments.py    # 文件附件登记和下载 ID
    config.py         # .env 加载和运行配置
    llm_client.py     # openai SDK 流式请求
    server.py         # FastAPI 页面和 /api/chat 接口
    tools.py          # 工具定义、schema、执行逻辑
  static/
    index.html        # 聊天页面
    styles.css        # 页面样式
    app.js            # 流式读取和 UI 更新
  docs/
    TECHNICAL_DESIGN.md
    DESIGN_SPEC.md
  tests/
    test_tools.py
```

## 示例提问

```text
现在几点？
```

```text
列出当前项目根目录的文件。
```

```text
运行命令 python --version，并告诉我结果。
```

```text
把 README.md 作为文件发送给我。
```

```text
生成一张 16:9 的教学插图：一个简单 agent loop 在调用工具。
```

## 安全说明

`run_command` 工具可以执行本机命令，`send_file` 可以把工作区文件暴露给浏览器，适合教学演示和受控环境。默认会把工作目录和文件路径限制在 `WORKSPACE_DIR` 内，并启用一个基础的危险命令拦截器。生产环境中应增加鉴权、审批、沙箱、审计日志和更严格的命令/文件策略。

详细设计见 [docs/TECHNICAL_DESIGN.md](docs/TECHNICAL_DESIGN.md)，界面与交互规范见 [docs/DESIGN_SPEC.md](docs/DESIGN_SPEC.md)。

深入讲解文章见 [docs/CSDN_AGENT_LOOP_BLOG.md](docs/CSDN_AGENT_LOOP_BLOG.md)。