geo/docs/02-模块说明/agent-protocol.md

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 (任务状态)

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

AgentStatus (Agent状态)

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状态