# 物流Agent

**Repository Path**: yang230147961/logistics-agent

## Basic Information

- **Project Name**: 物流Agent
- **Description**: 物流 LangChain Agent
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-05
- **Last Updated**: 2025-11-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 物流Agent


## 项目概述

物流Agent是一个基于AI Agent架构的智能应用程序，专门用于处理生产计划与库存管理相关的任务。它的核心是AI Agent，能够理解自然语言查询，调用专门的计算工具，并以友好的方式返回结果。

项目主要包括以下几个部分：
1. **AI Agent模块** - 核心智能处理单元
2. **工具模块** - 专门的计算工具（如MRP计算器）
3. **API服务** - 提供HTTP接口供外部调用
4. **前端界面** - 提供图形化用户界面方便操作


### Agent架构

我们的Agent基于LangChain框架构建，主要包含以下组件：

1. **语言模型(LLM)** - 提供智能理解和生成能力
2. **提示词(Prompt)** - 指导LLM如何处理任务
3. **工具(Tools)** - 提供专门的功能，如MRP计算
4. **执行逻辑** - 控制Agent的行为流程

## 最简Agent实现

我们从最简单的Agent开始，它可以直接处理用户查询并返回响应。

### 核心代码

在 [src/agents/mrp_agent.py](file:///Users/returnzero/AllCode/logistics-agent/src/agents/mrp_agent.py) 中，我们定义了创建Agent的函数：

```python
def create_mrp_agent():
    """
    创建一个MRP Agent，可以调用MRP计算工具
    """
    # 根据配置初始化LLM
    if LLM_PROVIDER == "ollama":
        llm = ChatOllama(
            base_url=OLLAMA_CONFIG["base_url"],
            model=OLLAMA_CONFIG["model"],
            temperature=OLLAMA_CONFIG["temperature"]
        )
    elif LLM_PROVIDER == "dashscope":
        llm = ChatOpenAI(
            openai_api_key=DASHSCOPE_CONFIG["api_key"],
            openai_api_base=DASHSCOPE_CONFIG["base_url"],
            model=DASHSCOPE_CONFIG["model"],
            temperature=DASHSCOPE_CONFIG["temperature"]
        )
    else:
        raise ValueError(f"不支持的LLM提供商: {LLM_PROVIDER}")

    # 定义工具列表
    tools = [calculate_mrp_tool]

    # 创建提示词模板
    prompt = ChatPromptTemplate.from_messages([
        ("system", SYSTEM_PROMPT),
        ("human", "{input}"),
    ])

    return {
        "llm": llm,
        "tools": tools,
        "prompt": prompt
    }
```

### 系统提示词

在 [src/config.py](file:///Users/returnzero/AllCode/logistics-agent/src/config.py) 中，我们定义了系统提示词，它告诉LLM如何扮演MRP专家的角色：

```python
SYSTEM_PROMPT = """
你是一个精通生产计划与库存管理的 MRP 专家。请使用提供的工具解答用户问题。
你可以帮助用户计算物料需求计划，包括：
1. 根据总需求量、日需求量、最优订货批量、订货提前期、订货点、订货提前期、生产开始时间、初始库存等参数计算MRP
2. 生成订单与到货信息表
3. 生成月份内每日库存计划
4. 用户提供参数不全时不进行计算，需要引导用户提供完整参数
"""
```

### 运行Agent

最简单的Agent实现可以直接处理用户查询：

```python
def run_mrp_agent(query: str):
    # 简化实现：直接调用LLM处理查询
    agent = create_mrp_agent()
    llm = agent["llm"]
    prompt = agent["prompt"]
    
    # 格式化提示词
    formatted_prompt = prompt.format_messages(input=query)
    # 修改为流式输出
    for chunk in llm.stream(formatted_prompt):
        yield chunk.content
```

这个最简实现已经可以处理自然语言查询并返回智能响应，但它还不能调用专门的计算工具。

## 增强Agent能力 - 工具调用

为了让Agent能够执行具体的计算任务，我们需要让它能够调用工具。

### 为什么需要工具？

虽然大型语言模型具有很强的理解和生成能力，但在数学计算、数据处理等精确任务上，专门的工具往往更加可靠和准确。我们的MRP计算器就是一个专门用于物料需求计划计算的工具。

### 工具定义

在 [src/tools/mrp_calculator.py](file:///Users/returnzero/AllCode/logistics-agent/src/tools/mrp_calculator.py) 中，我们使用LangChain的`@tool`装饰器定义了计算工具：

```python
@tool
def calculate_mrp_tool(
    total_demand: float,
    daily_demand: float,
    order_qty: float,
    reorder_point: float,
    lead_time_days: int,
    start_date: str,
    initial_stock: float,
    max_display_days: int = 30
) -> Tuple[List[Dict], List[Dict]]:
    """
    计算黍米酿造的 MRP 计划（物料需求计划）
    """
    # 实现具体的计算逻辑
    # ...
```

### 参数解析和检查

为了让Agent能够从自然语言查询中提取参数并检查完整性，我们实现了两个关键函数：

```python
def extract_mrp_params(query: str) -> dict:
    """
    从查询中提取MRP参数
    """
    # 使用正则表达式从自然语言中提取参数
    # ...

def check_missing_params(params: dict) -> list:
    """
    检查缺失的参数
    """
    # 检查必需的参数是否完整
    # ...
```

### 交互式Agent

我们实现了一个交互式Agent，它能够：
1. 解析用户查询中的参数
2. 检查参数完整性
3. 如果参数不完整，引导用户提供更多信息
4. 如果参数完整，调用工具执行计算

```python
def run_interactive_mrp_agent(query: str, provided_params: dict = None):
    """
    运行交互式MRP Agent来处理查询
    """
    # 合并参数
    # 检查缺失参数
    # 如果有缺失，引导用户提供
    # 如果完整，调用工具计算
```

通过添加工具调用能力，我们的Agent不仅能够理解自然语言，还能执行精确的计算任务。

## 提供服务接口

为了让Agent能够为更多用户服务，我们需要将它包装成API服务。

### 为什么需要API？

API(Application Programming Interface)使得我们的Agent可以：
1. 通过Web访问，无需安装专门的软件
2. 被其他系统集成和调用
3. 支持多种客户端，包括网页、移动应用等

### 使用FastAPI构建API

在 [src/api.py](file:///Users/returnzero/AllCode/logistics-agent/src/api.py) 中，我们使用FastAPI构建了API服务：

```python
@app.get("/calculate_mrp_stream", 
         summary="流式计算MRP计划",
         description="以流式方式计算物料需求计划，包括订单与到货信息表以及每日库存计划")
async def calculate_mrp_stream_get(...)
```

API服务的主要职责是：
1. 接收用户请求
2. 解析请求参数
3. 调用Agent处理请求
4. 返回处理结果

### 流程图：API服务架构

```mermaid
graph LR
    A[用户请求] --> B[FastAPI路由]
    B --> C[参数解析]
    C --> D[调用Agent]
    D --> E[Agent处理]
    E --> F[调用工具]
    F --> G[返回结果]
    G --> H[流式响应]
    H --> A
```

通过API服务，我们的Agent可以为Web前端和其他系统提供服务。

## 构建用户界面

为了让用户更容易使用我们的Agent，我们需要构建一个友好的用户界面。

### 为什么需要前端界面？

1. **降低使用门槛** - 用户不需要了解API细节
2. **更好的交互体验** - 可以进行对话式交互
3. **结果可视化** - 可以用表格、图表等形式展示结果

### 使用Vue.js构建前端

我们的前端基于Vue 3 + TypeScript + Vite技术栈，在 [ui/mrp-dashboard/](file:///Users/returnzero/AllCode/logistics-agent/ui/mrp-dashboard/) 目录下。

主要组件包括：
- [MRPView.vue](file:///Users/returnzero/AllCode/logistics-agent/ui/mrp-dashboard/src/views/MRPView.vue) - 主要的聊天界面
- [MRPCalculator.vue](file:///Users/returnzero/AllCode/logistics-agent/ui/mrp-dashboard/src/components/MRPCalculator.vue) - 计算器组件
- [MessageContent.vue](file:///Users/returnzero/AllCode/logistics-agent/ui/mrp-dashboard/src/components/MessageContent.vue) - 消息内容显示组件

### 前后端通信

前端通过 [mrpService.ts](file:///Users/returnzero/AllCode/logistics-agent/ui/mrp-dashboard/src/services/mrpService.ts) 与后端通信：

```typescript
export const mrpService = {
  calculateMRPStream: async (params: MRPRequest): Promise<EventSource> => {
    // 构建查询参数并创建EventSource连接
    const url = `${API_BASE_URL}/calculate_mrp_stream?${queryParams.toString()}`;
    return new EventSource(url, {
      withCredentials: true
    });
  }
};
```

### 流程图：前后端交互

```mermaid
graph LR
    A[用户] --> B[Vue前端]
    B --> C[用户输入]
    C --> D[Axios请求]
    D --> E[FastAPI后端]
    E --> F[Agent处理]
    F --> G[工具调用]
    G --> H[返回结果]
    H --> I[EventSource流式传输]
    I --> J[前端接收显示]
    J --> A
```

通过前端界面，用户可以以聊天的方式与Agent交互，获得更好的使用体验。

## 优化用户体验 - 流式输出

为了让用户感受到Agent的"思考"过程，我们实现了流式输出功能。

### 什么是流式输出？

###### 流式输出是指服务器逐步产生数据并实时发送给客户端，而不是等到所有数据都准备好后再一次性发送。这样用户可以看到Agent逐步输出结果，就像在实时打字一样。

### 实现技术：Server-Sent Events (SSE)

我们使用Server-Sent Events技术实现流式输出。在后端 [api.py](file:///Users/returnzero/AllCode/logistics-agent/src/api.py) 中：

```python
return StreamingResponse(event_generator(), media_type="text/event-stream")

async def event_generator():
    # 逐步产生数据
    for chunk in run_mrp_agent(query):
        # 发送每个字符
        yield f"data: {json.dumps({'type': 'chunk', 'content': char})}\n\n"
```

### 前端处理流式数据

在前端 [MRPView.vue](file:///Users/returnzero/AllCode/logistics-agent/ui/mrp-dashboard/src/views/MRPView.vue) 中，我们使用EventSource API接收流式数据：

```javascript
const eventSource = new EventSource(eventSourceUrl, { withCredentials: true })

eventSource.addEventListener('message', (event) => {
  // 处理接收到的数据
  handleMessageEvent(event, assistantMsg, eventSource)
})
```

### 用户体验改善

流式输出带来了几个重要的用户体验改善：

1. **即时反馈** - 用户不需要等待漫长的计算过程，可以看到实时的输出
2. **减少焦虑** - 用户知道系统正在工作，而不是卡死无响应
3. **类似打字机效果** - 字符逐个显示，更加生动有趣

### 流程图：流式输出过程

```mermaid
graph LR
    A[用户发送请求] --> B[后端开始处理]
    B --> C[产生第一批数据]
    C --> D[通过SSE发送数据]
    D --> E[前端接收并显示]
    E --> F[产生第二批数据]
    F --> G[通过SSE发送数据]
    G --> H[前端接收并显示]
    H --> I[处理完成]
    I --> J[发送结束信号]
    J --> K[前端显示最终结果]
```

通过实现流式输出，我们的Agent项目不仅功能完善，而且用户体验也得到了显著提升。

## 总结

通过以上步骤，我们构建了一个以AI Agent为核心的物流管理系统：

1. **核心智能** - 实现了能够理解自然语言并生成智能响应的AI Agent
2. **工具增强** - 通过工具调用实现精确计算能力
3. **服务化** - 通过API接口为各种客户端提供服务
4. **用户界面** - 提供友好的前端界面方便用户使用
5. **体验优化** - 实现流式输出，提升用户交互体验

### 项目演进流程图

```mermaid
graph LR
    A[AI Agent核心] --> B[工具调用能力]
    B --> C[API服务接口]
    C --> D[前端用户界面]
    D --> E[流式输出优化]
    E --> F[完整项目]
```

这种以AI Agent为核心的开发方式有以下优势：
1. **智能交互** - 用户可以用自然语言与系统交互
2. **模块化设计** - Agent、工具、界面等模块解耦，便于维护和扩展
3. **可扩展性强** - 可以轻松添加新的工具和功能
4. **用户体验好** - 提供了类人的交互方式和实时反馈

希望这个以AI Agent为核心的教程能帮助您理解物流Agent项目的构建过程。如果您想深入了解某个具体部分，可以查看相应代码文件的详细实现。


## 项目简介

这是一个基于 LangChain 构建的物流领域 AI Agent 项目，专门用于处理生产计划与库存管理相关的任务。

## 项目结构

```
logistics-agent/
├── README.md
├── requirements.txt
├── .gitignore
├── src/
│   ├── main.py           # 项目入口文件
│   ├── server.py         # API服务入口文件
│   ├── api.py            # API接口定义
│   ├── config.py         # 配置文件
│   ├── agents/           # Agent 定义目录
│   │   └── __init__.py
│   ├── tools/            # 工具函数目录
│   │   └── __init__.py
│   └── utils/            # 工具函数目录
│       └── __init__.py
├── ui/                   # 前端项目目录
│   └── mrp-dashboard/    # MRP可视化界面
├── tests/                # 测试文件目录
└── docs/                 # 文档目录
```

## 安装说明

1. 克隆项目到本地
2. 安装依赖: `pip install -r requirements.txt`
3. 配置阿里云百炼 API Key 到 config.py 文件中

## 使用说明

### 命令行方式运行

运行主程序:
```bash
cd src
python main.py
```

### API服务方式运行

启动API服务:
```bash
cd src
python server.py
```

或者指定主机和端口:
```bash
cd src
python server.py --host 0.0.0.0 --port 8080
```

服务启动后，可以通过以下URL访问:
- API文档: http://127.0.0.1:8000/docs
- API接口: http://127.0.0.1:8000

## 前端界面

项目包含一个基于 Vue 3 + TypeScript + Vite 构建的前端界面，用于可视化展示 MRP 计算结果。

### 启动前端界面

```bash
cd ui/mrp-dashboard
npm run dev
```

默认情况下，前端将在 http://localhost:5173 上运行。

### 前端功能

- 输入MRP计算所需参数
- 调用后端API进行MRP计算
- 以图表形式展示每日库存变化情况

## 贡献

欢迎提交 Issue 和 Pull Request 来改进本项目。