# Agent间通信协议

## 概述

本文档详细描述Agent Framework中各Agent之间的通信协议和数据结构。

## 消息类型

### TaskMessage (任务消息)

从调度器发往Agent的任务消息。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| task_id | str | 是 | UUID格式的任务ID |
| agent_name | str | 是 | 目标Agent名称 |
| task_type | str | 是 | 任务类型 |
| priority | int | 否 | 优先级（0-9，9最高） |
| input_data | dict | 是 | 输入参数 |
| callback_url | str | 否 | 回调URL |
| created_at | datetime | 是 | 创建时间 |
| timeout_seconds | int | 否 | 超时时间（默认300秒） |

### TaskResult (任务结果)

从Agent返回的结果消息。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| task_id | str | 是 | 对应的任务ID |
| agent_name | str | 是 | 执行任务的Agent名称 |
| status | str | 是 | 任务状态 (completed/failed/cancelled) |
| output_data | dict | 否 | 输出数据 |
| error_message | str | 否 | 错误信息 |
| started_at | datetime | 是 | 开始时间 |
| completed_at | datetime | 是 | 完成时间 |
| metrics | dict | 否 | 执行指标（耗时、token消耗等） |

### TaskProgress (进度上报)

Agent执行过程中上报的进度信息。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| task_id | str | 是 | 任务ID |
| agent_name | str | 是 | Agent名称 |
| progress | float | 是 | 进度 (0.0-1.0) |
| message | str | 是 | 进度描述 |
| updated_at | datetime | 是 | 更新时间 |

## 状态枚举

### TaskStatus (任务状态)

```python
class TaskStatus(str, Enum):
    PENDING = "pending"      # 等待执行
    RUNNING = "running"      # 执行中
    COMPLETED = "completed"  # 已完成
    FAILED = "failed"       # 执行失败
    CANCELLED = "cancelled"  # 已取消
```

### AgentStatus (Agent状态)

```python
class AgentStatus(str, Enum):
    ONLINE = "online"   # 在线
    OFFLINE = "offline" # 离线
    BUSY = "busy"       # 忙碌中
```

## 通信流程

```
1. 外部请求 → Dispatcher.dispatch(TaskMessage) → Redis Queue
2. Redis Queue → Agent消费 → 执行任务
3. Agent执行完成 → TaskResult → Dispatcher.handle_result
4. Dispatcher更新数据库 → 触发回调(如有)
```

## Agent类型

| 类型 | 说明 | 职责 |
|------|------|------|
| CITATION_DETECTOR | 引用检测Agent | 解析AI平台响应，识别品牌引用 |
| CONTENT_GENERATOR | 内容生成Agent | 生成GEO优化内容 |
| DEAI_AGENT | 去AI化Agent | 去除AI生成痕迹 |
| GEO_OPTIMIZER | GEO优化Agent | SEO和GEO优化 |
| RULE_CHECKER | 规则检查Agent | 内容合规审核 |
| COMPETITOR_ANALYZER | 竞品分析Agent | 竞品数据收集分析 |
| PERFORMANCE_TRACKER | 性能追踪Agent | 追踪内容表现 |

## 任务类型

| Agent | task_type | 说明 |
|-------|-----------|------|
| CitationDetector | citation_detect | 检测品牌引用 |
| ContentGenerator | generate | 生成内容 |
| DeAIAgent | humanize | 去AI化处理 |
| GEOOptimizer | optimize | GEO优化 |

## 心跳机制

Agent通过定时更新心跳来维持在线状态：

- 心跳超时阈值：90秒
- 超时后Agent被标记为OFFLINE
- Registry.check_health() 定期检查所有Agent状态