# agent-scaffold-python

**Repository Path**: zhangyun-source/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-05-18
- **Last Updated**: 2026-05-18

## 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 工具集成。

## 功能特性

- **多轮对话** - 支持会话管理和历史消息存储
- **流式输出** - SSE 格式实时推送思考过程和正文内容
- **MCP 工具集成** - 支持加载 MCP 服务器提供的工具
- **本地工具** - 内置数学计算、时间查询等常用工具
- **灵活配置** - 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        # 智能体管理器
│   │   ├── tools.py        # 工具管理
│   │   └── hijack_openai.py# OpenAI 流式输出补丁
│   ├── storage/            # 数据持久化
│   │   ├── database.py     # 数据库连接
│   │   ├── session_store.py# 会话存储
│   │   └── message_store.py# 消息存储
│   └── utils/              # 工具函数
│       └── logger.py       # 日志配置
├── web/                    # Web 前端（可选）
│   ├── templates/          # HTML 模板
│   └── static/             # 静态资源
├── 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`

### 运行服务

```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
```

## 配置说明

### 配置优先级

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/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 |

**配置字段说明：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `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） |

## 内置工具

| 工具名 | 说明 | 参数 |
|--------|------|------|
| `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)