# agent-scaffold-python

**Repository Path**: zhangchaohuiget/agent-scaffold-python

## Basic Information

- **Project Name**: agent-scaffold-python
- **Description**: 智能体脚手架程序 - 基于LangChain和FastAPI构建的智能体服务框架
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-10
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Scaffold

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.12+-green.svg)](https://www.python.org/)

基于 LangChain 和 FastAPI 构建的智能体服务框架，支持多轮对话、流式输出、MCP 工具集成和本地 Skills 扩展。

## 功能特性

- **多轮对话** - 支持会话管理和历史消息存储
- **流式输出** - SSE 格式实时推送思考过程和正文内容
- **MCP 工具集成** - 支持加载 MCP 服务器提供的工具
- **本地 Skills** - 支持扫描本地技能包，并按需读取技能说明和参考资料
- **本地工具** - 内置数学计算、时间查询等常用工具
- **灵活配置** - YAML 配置文件 + 环境变量覆盖

## 项目结构

```
agent-scaffold/
├── main.py                 # 应用入口
├── config/                 # 配置文件目录
│   ├── config.yaml         # 主配置文件
│   ├── system_prompt.md    # 系统提示词
│   └── mcp.yaml            # MCP服务器配置（可选）
├── src/agent_scaffold/
│   ├── api/                # API 接口层
│   │   ├── routes.py       # 路由定义
│   │   ├── schemas.py      # 数据模型
│   │   └── streaming.py    # 流式响应处理
│   ├── config/             # 配置管理
│   │   ├── schema.py       # 配置模型定义
│   │   └── loader.py       # 配置加载器
│   ├── core/               # 核心业务逻辑
│   │   ├── agent.py        # 智能体管理器
│   │   ├── skills.py       # 本地 Skills 加载与工具创建
│   │   ├── tools.py        # 工具管理
│   │   └── hijack_openai.py# OpenAI 流式输出补丁
│   ├── storage/            # 数据持久化
│   │   ├── database.py     # 数据库连接
│   │   ├── session_store.py# 会话存储
│   │   └── message_store.py# 消息存储
│   └── utils/              # 工具函数
│       └── logger.py       # 日志配置
├── web/                    # Web 前端（可选）
│   ├── templates/          # HTML 模板
│   └── static/             # 静态资源
├── docs/                   # 设计文档
├── tests/                  # 测试目录
├── pyproject.toml          # 项目配置
└── uv.lock                 # 依赖锁定文件
```

## 快速开始

### 安装依赖

推荐使用 [uv](https://docs.astral.sh/uv/) 进行依赖管理：

```bash
# 安装依赖
uv sync

# 安装开发依赖
uv sync --extra dev
```

### 配置

1. 编辑 `config/config.yaml` 设置模型参数：

```yaml
model:
  name: gpt-4o              # 模型名称
  provider: openai          # 模型提供商
  api_key: "your-api-key"   # API 密钥
  base_url: "https://api.openai.com/v1"  # API 地址
  temperature: 0.7
  max_tokens: 4096
```

2. 编辑 `config/system_prompt.md` 设置系统提示词

3. （可选）配置 MCP 服务器 `config/mcp.yaml`

4. （可选）配置本地 Skills 目录：

```yaml
skills:
  enabled: true
  directories:
    - /path/to/skills
  max_resource_bytes: 50000
```

### 运行服务

```bash
# 使用 uv 运行
uv run python main.py

# 或直接运行
python main.py
```

服务启动后访问：
- API 文档: http://localhost:8000/docs
- Web 界面: http://localhost:8000/

## API 接口

### 聊天接口

```http
POST /api/chat
Content-Type: application/json

{
  "messages": [
    {"role": "user", "content": "你好"}
  ],
  "session_id": null,
  "stream": true
}
```

**响应（流式）**：

```
event: thought
data: {"event": "thought", "output": {"thought": "思考内容..."}}

event: answer
data: {"event": "answer", "output": {"delta": "文本增量", "accumulated": "累积文本"}}

event: tool_select
data: {"event": "tool_select", "output": {"tool_name": "calculate", "tool_call_id": "xxx"}}

event: tool_call
data: {"event": "tool_call", "output": {"tool_name": "calculate", "result": "42"}}

event: finish
data: {"event": "finish", "output": {"finish_reason": "stop"}}
```

### 会话管理

```http
# 获取会话列表
GET /api/sessions?limit=20&offset=0

# 获取会话详情
GET /api/sessions/{session_id}

# 删除会话
DELETE /api/sessions/{session_id}

# 健康检查
GET /api/health
```

### 管理接口

```http
# 手动重载智能体
POST /api/admin/reload-agent
```

重载会重新加载配置、重新扫描 Skills、重新加载 MCP 工具并重建 agent。该操作只影响后续新请求，不中断已经开始的流式请求。

响应：

```json
{
  "status": "success",
  "message": "agent reloaded"
}
```

注意：当前管理接口未内置鉴权，生产环境暴露前应增加访问控制。

## 配置说明

### 配置优先级

1. 环境变量（最高优先级）
2. `config/config.yaml`
3. 默认值（最低优先级）

### 环境变量

| 变量名 | 说明 | 示例 |
|--------|------|------|
| `AGENT_API_KEY` | API 密钥 | `sk-xxx` |
| `AGENT_API_BASE` | API 地址 | `https://api.openai.com/v1` |
| `AGENT_MODEL_NAME` | 模型名称 | `gpt-4o` |
| `AGENT_LOG_LEVEL` | 日志级别 | `INFO` |
| `AGENT_LOG_FILE` | 日志文件路径 | `logs/app.log` |
| `AGENT_CONFIG_DIR` | 配置文件目录 | `./config` |
| `HOST` | 服务地址 | `0.0.0.0` |
| `PORT` | 服务端口 | `8000` |

### MCP 配置

可在 `config/config.yaml` 中通过 `mcp.enabled` 控制是否加载 MCP 工具：

```yaml
mcp:
  enabled: true
  servers: []
```

在 `config/mcp.yaml` 中配置 MCP 服务器，支持三种传输方式：

```yaml
servers:
  # Stdio 方式 - 启动本地进程
  - name: math-server
    transport: stdio
    command: python
    args: ["math_server.py"]
    env:
      PYTHONPATH: "/path/to/module"
    enabled: true

  # HTTP 方式 - 连接远程 MCP 服务器
  - name: weather-server
    transport: http
    url: "http://localhost:8000/mcp"
    headers:
      Authorization: "Bearer YOUR_TOKEN"
    enabled: true

  # SSE 方式 - 通过 SSE 连接远程 MCP 服务器
  - name: remote-server
    transport: sse
    url: "http://localhost:8001/sse"
    headers:
      X-Custom-Header: "custom-value"
    enabled: true
```

**传输方式说明：**

| Transport | 必填字段 | 适用场景 |
|-----------|----------|----------|
| `stdio` | `command`, `args` | 启动本地 MCP 服务器进程 |
| `http` | `url` | Streamable HTTP 连接远程 MCP |
| `sse` | `url` | SSE 连接远程 MCP |

**配置字段说明：**

全局 MCP 配置：

| 字段 | 类型 | 说明 |
|------|------|------|
| `enabled` | bool | 是否启用 MCP 工具加载（默认 true） |
| `servers` | list | MCP 服务器列表，可直接配置或从 `mcp.yaml` 加载 |

单个 MCP 服务器配置：

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 服务器名称（必填） |
| `transport` | string | 传输方式：stdio, http, sse（默认 stdio） |
| `command` | string | 启动命令（stdio 方式必填） |
| `args` | list | 命令参数（stdio 方式） |
| `env` | dict | 环境变量（stdio 方式） |
| `url` | string | 服务器 URL（http/sse 方式必填） |
| `headers` | dict | 请求头（http/sse 方式） |
| `enabled` | bool | 是否启用（默认 true） |

### Skills 配置

本地 Skills 通过 `config/config.yaml` 配置：

```yaml
skills:
  enabled: true
  directories:
    - /path/to/skills
  max_resource_bytes: 50000
```

字段说明：

| 字段 | 类型 | 说明 |
|------|------|------|
| `enabled` | bool | 是否启用本地 Skills 工具加载 |
| `directories` | list | Skills 根目录列表，每个根目录下的一级子目录可作为一个技能包 |
| `max_resource_bytes` | int | 单次读取技能资源文件的最大字节数 |

技能包至少包含 `SKILL.md`：

```text
my-skill/
  SKILL.md
  references/
    api.md
  examples/
    basic.py
```

`SKILL.md` frontmatter 示例：

```markdown
---
name: my-skill
description: 用于处理某类任务的技能说明。
license: MIT
---

# My Skill

技能正文...
```

初始化智能体时，系统会扫描 Skills 目录并创建两个只读工具：

| 工具名 | 说明 | 参数 |
|--------|------|------|
| `load_skill` | 按技能名称读取完整 `SKILL.md` | `skill_name` |
| `load_skill_resource` | 读取技能包内被 `SKILL.md` 引用的资源文件 | `skill_name`, `resource_path` |

Skills 不会自动监听目录变化。新增、删除或修改技能元数据后，需要重启服务，或调用 `POST /api/admin/reload-agent` 手动重载。

## 内置工具

| 工具名 | 说明 | 参数 |
|--------|------|------|
| `calculate` | 数学表达式计算 | `expression`: 数学表达式 |
| `get_current_time` | 获取当前时间 | 无 |

## 开发指南

### 运行测试

```bash
uv run pytest
```

### 代码风格

- 使用 Python 3.12+ 类型注解
- 遵循 PEP 8 编码规范
- 使用 Pydantic 进行数据验证

### 添加自定义工具

在 `src/agent_scaffold/core/tools.py` 中添加：

```python
from langchain_core.tools import tool

@tool
def my_custom_tool(param: str) -> str:
    """工具描述"""
    return f"处理结果: {param}"

def get_local_tools() -> list:
    return [calculate, get_current_time, my_custom_tool]
```

## 技术栈

- **FastAPI** - Web 框架
- **LangChain** - 智能体框架
- **LangGraph** - 状态图编排
- **Pydantic** - 数据验证
- **aiosqlite** - 异步 SQLite
- **loguru** - 日志处理

## License

[MIT License](LICENSE)