aiagent/Agent使用说明.md

# Agent使用说明

## 📋 概述

Agent部署后，状态变为"已发布"（published）或"运行中"（running），就可以被使用了。本文档介绍如何使用已发布的Agent。

## 🎯 使用方式

### 方式1：通过前端界面使用（推荐）

#### 步骤1：进入Agent设计器
1. 在Agent管理页面，找到已发布的Agent
2. 点击 **"使用"** 按钮（只有已发布或运行中的Agent才显示此按钮）
3. 系统会跳转到Agent设计器页面

#### 步骤2：在聊天界面使用
- Agent设计器页面右侧有一个聊天预览面板（AgentChatPreview）
- 在输入框中输入您的问题或需求
- 点击发送按钮或按 Enter 键发送
- Agent会执行工作流并返回结果

#### 功能特性：
- ✅ 实时对话：支持多轮对话
- ✅ 执行动画：左侧工作流会显示节点执行动画
- ✅ 自动滚动：新消息自动滚动到底部
- ✅ 清空对话：可以随时清空对话历史

### 方式2：通过API调用

#### API端点
```
POST /api/v1/executions
```

#### 请求格式
```json
{
  "agent_id": "agent-id",
  "input_data": {
    "query": "用户输入的问题",
    "USER_INPUT": "用户输入的问题"
  }
}
```

#### 响应格式
```json
{
  "id": "execution-id",
  "agent_id": "agent-id",
  "status": "pending",
  "input_data": {...},
  "created_at": "2024-01-19T12:00:00"
}
```

#### 获取执行结果
```
GET /api/v1/executions/{execution_id}
```

#### 轮询执行状态
```
GET /api/v1/executions/{execution_id}/status
```

### 方式3：使用测试工具

使用我们提供的测试工具 `test_workflow_tool.py`：

```bash
# 通过Agent名称和用户输入测试
python3 test_workflow_tool.py -a "Agent名称" -i "用户输入内容"

# 交互式输入
python3 test_workflow_tool.py
```

## 📝 使用示例

### 示例1：前端界面使用

1. **打开Agent管理页面**
   - 访问 `/agents` 路径
   - 找到状态为"已发布"的Agent

2. **点击"使用"按钮**
   - 系统跳转到Agent设计器页面
   - 右侧显示聊天界面

3. **发送消息**
   - 在输入框输入："生成一个导出androidlog的脚本"
   - 点击发送或按Enter键

4. **查看结果**
   - 左侧工作流显示执行动画
   - 右侧聊天界面显示Agent的回复

### 示例2：API调用

```bash
# 1. 登录获取token
curl -X POST http://localhost:8037/api/v1/auth/login \
  -d "username=admin&password=123456"

# 2. 执行Agent
curl -X POST http://localhost:8037/api/v1/executions \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-id",
    "input_data": {
      "query": "生成一个导出androidlog的脚本",
      "USER_INPUT": "生成一个导出androidlog的脚本"
    }
  }'

# 3. 获取执行结果（使用返回的execution_id）
curl -X GET http://localhost:8037/api/v1/executions/{execution_id} \
  -H "Authorization: Bearer <your_token>"
```

### 示例3：Python脚本调用

```python
import requests

# 登录
response = requests.post(
    "http://localhost:8037/api/v1/auth/login",
    data={"username": "admin", "password": "123456"}
)
token = response.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# 执行Agent
response = requests.post(
    "http://localhost:8037/api/v1/executions",
    headers=headers,
    json={
        "agent_id": "agent-id",
        "input_data": {
            "query": "用户问题",
            "USER_INPUT": "用户问题"
        }
    }
)

execution_id = response.json()["id"]

# 轮询获取结果
import time
while True:
    response = requests.get(
        f"http://localhost:8037/api/v1/executions/{execution_id}",
        headers=headers
    )
    execution = response.json()
    if execution["status"] == "completed":
        print("结果:", execution["output_data"])
        break
    elif execution["status"] == "failed":
        print("执行失败:", execution.get("error_message"))
        break
    time.sleep(2)
```

## 🔑 权限说明

### 已发布Agent的使用权限

1. **所有者**：可以随时使用自己的Agent
2. **其他用户**：只有已发布（published）或运行中（running）状态的Agent才能被其他用户使用
3. **草稿状态**：只有所有者可以测试，其他用户无法使用

### API权限检查

从代码中可以看到：
```python
# 只有已发布的Agent可以执行，或者所有者可以测试
if agent.status not in ["published", "running"] and agent.user_id != current_user.id:
    raise HTTPException(status_code=403, detail="Agent未发布或无权执行")
```

## 🎨 前端界面说明

### Agent设计器页面布局

```
┌─────────────────────────────────────────────────┐
│  Agent编排设计器                    [测试运行] [发布] [返回] │
├──────────────────────┬──────────────────────────┤
│                      │                          │
│   工作流编辑器        │    Agent聊天预览          │
│   (左侧)             │    (右侧)                │
│                      │                          │
│  - 节点可视化        │  - 对话界面              │
│  - 执行动画          │  - 消息历史              │
│  - 节点配置          │  - 输入框                │
│                      │  - 实时响应              │
│                      │                          │
└──────────────────────┴──────────────────────────┘
```

### 聊天界面功能

1. **消息显示**
   - 用户消息：右侧显示，蓝色背景
   - Agent回复：左侧显示，白色背景
   - 时间戳：每条消息显示发送时间

2. **输入功能**
   - 文本输入：支持多行文本
   - Enter发送：按Enter键发送消息
   - Shift+Enter：换行
   - 发送按钮：点击发送

3. **其他功能**
   - 清空对话：清除所有消息历史
   - 加载状态：显示"正在思考..."
   - 执行动画：左侧工作流实时显示节点执行状态

## 🔧 常见问题

### Q1: 为什么看不到"使用"按钮？

**A:** "使用"按钮只对状态为"已发布"（published）或"运行中"（running）的Agent显示。如果Agent是"草稿"（draft）状态，需要先点击"部署"按钮发布。

### Q2: 如何知道Agent是否可用？

**A:** 查看Agent列表中的"状态"列：
- ✅ **已发布**（published）：可以使用
- ✅ **运行中**（running）：可以使用
- ⚠️ **草稿**（draft）：只有所有者可以测试
- ⚠️ **已停止**（stopped）：需要重新部署

### Q3: Agent执行失败怎么办？

**A:** 
1. 检查Agent的工作流配置是否正确
2. 查看执行记录中的错误信息
3. 检查LLM节点的API密钥是否配置
4. 查看后端日志获取详细错误信息

### Q4: 如何查看Agent的执行历史？

**A:** 
1. 访问"执行管理"页面（`/executions`）
2. 筛选Agent相关的执行记录
3. 点击执行记录查看详细信息

### Q5: 可以同时使用多个Agent吗？

**A:** 可以。每个Agent都是独立的，可以同时打开多个Agent设计器页面使用不同的Agent。

## 📚 相关文档

- [Agent管理功能使用说明](./Agent管理功能使用说明.md)
- [工作流调用测试总结](./工作流调用测试总结.txt)
- [API文档](./backend/API_DOCUMENTATION.md)

## 🎯 快速开始

1. **确保Agent已发布**
   - 在Agent列表中，找到要使用的Agent
   - 确认状态为"已发布"或"运行中"

2. **点击"使用"按钮**
   - 跳转到Agent设计器页面

3. **开始对话**
   - 在右侧聊天界面输入问题
   - 点击发送或按Enter键
   - 等待Agent执行并返回结果

4. **查看结果**
   - 在聊天界面查看Agent的回复
   - 在左侧工作流查看执行过程

---

**最后更新**：2026-01-19  
**适用版本**：v1.0+