# AgentSkeleton

**Repository Path**: lucy_cy/agent-skeleton

## Basic Information

- **Project Name**: AgentSkeleton
- **Description**: 一个开源的项目，基于LangGraph + FastAPI 搭建的 Agent骨架，适合用于二次开发。详情见README.md
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-17
- **Last Updated**: 2026-04-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Backend Skeleton

一个基于 **FastAPI + LangGraph + PostgreSQL** 的 Agent 后端开发骨架项目。

这个项目的目标不是做成完整产品，而是提供一个适合二次开发的后端底座，用来快速扩展不同类型的 Agent 应用，并作为面试项目展示 Agent 架构设计与后端工程能力。

## 项目亮点

- 支持 **双范式 Agent 架构**
  - **ReAct**：适合即时交互，基于 Tool Calling 动态选择工具
  - **Workflow**：适合结构化任务，支持先规划再执行
- 支持 **动态 Workflow 编排**
  - 根据用户目标自动生成 `WorkflowSpec`
  - 将工作流编译为可执行节点图
  - 可完成搜索、分析、导出等多步骤任务
- 支持 **强约束工作流生成**
  - Workflow 规划使用 Function Call 产出结构化结果
  - 比单纯 prompt + JSON 输出更稳定
- 具备基础后端工程能力
  - JWT 鉴权
  - 会话管理
  - LangGraph checkpoint 持久化
  - 结构化日志
  - 限流
  - Prometheus 指标暴露
- 内置基础 **评测 Harness**
  - 用于对 Agent 输出进行自动化评估、汇总与生成报告

## 核心架构

### 1. ReAct 范式

适合开放式、即时交互场景。

流程大致为：

`用户请求 -> LLM 推理 -> Tool Calling -> 返回结果`

### 2. Workflow 范式

适合结构化、多步骤任务。

流程大致为：

`用户目标 -> Planner -> WorkflowSpec -> Compiler -> Runner -> Result`

当前内置基础节点：

- `fetch`
- `llm`
- `export`

后续扩展能力时，主要通过新增节点完成二次开发。

## 技术栈

- **FastAPI**：Web API
- **LangGraph**：Agent 运行时与状态图编排
- **PostgreSQL**：业务数据与 checkpoint 持久化
- **DeepSeek API**：LLM 能力
- **SQLModel / SQLAlchemy**：数据库访问
- **structlog**：结构化日志
- **slowapi**：限流
- **Prometheus / Grafana**：监控与可观测性

## 目录结构

```text
app/
  api/v1/                # 路由层
  core/                  # 配置、日志、中间件、LangGraph、Workflow 等核心能力
  models/                # ORM 模型
  schemas/               # 请求/响应模型与状态定义
  services/              # 业务服务层
  utils/                 # 工具函数
evals/                   # 基础评测 harness
docs/                    # 项目文档
requests/                # 本地接口调试示例
```

## 快速启动

### 1. 安装依赖

```bash
uv sync
```

### 2. 启动开发环境

```bash
$env:UV_CACHE_DIR='.uv-cache'; uv run uvicorn app.main:app --reload --port 8000
```

默认服务地址：

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

### 3. Docker 启动

只启动 API 与数据库：

```bash
docker compose up -d
```

如果需要完整开发环境（包含监控）：

```bash
docker compose --profile observability up -d
```

## 常用命令

```bash
uv sync
uv run uvicorn app.main:app --reload --port 8000
uv run ruff check .
uv run ruff format .
uv run python evals/main.py --interactive
uv run python evals/main.py --quick
```

## 项目定位

这个项目更适合被理解为：

> 一个支持 **ReAct + Workflow 双范式** 的 Agent 后端开发骨架。

它强调的是：

- Agent 架构设计
- Workflow 动态编排
- 后端工程化能力
- 可扩展的二次开发底座

而不是完整的前端产品形态。