agents.py
agents.py
"""
主协调器(Coordinator)与子 Agent(Worker)
===========================================
实现实验 10-6 的核心协调机制:
1. 并行派发:Coordinator 同时启动 N 个同构 Worker,各搜一个"网站/来源"。
2. 消息总线:Worker 与 Coordinator 全部通过 ``MessageBus`` 用信封通信。
3. 实时监控(push 范式):Worker 执行中主动 ``status_update`` 上报,
Coordinator 维护任务状态表并实时刷新打印。
4. 级联终止:某 Worker 命中目标后,Coordinator 广播 ``terminate``,
其余 Worker 在循环安全点检查到信号后 ack 并优雅退出。
5. 竞态处理:多个 Worker 可能几乎同时命中,Coordinator 用 ``asyncio.Lock``
+ 幂等标志保证**只结算一次、只广播一轮终止**。
状态机:submitted -> running -> (needs_input) -> succeeded / failed / terminated
"""
from __future__ import annotations
import asyncio
import time
from dataclasses import dataclass, field
from enum import Enum
from typing import Dict, List, Optional
from llm import judge_answer, llm_available
from message_bus import BROADCAST, MessageBus, _now
from sources import Source
class TaskState(str, Enum):
SUBMITTED = "已提交"
RUNNING = "执行中"
NEEDS_INPUT = "需要输入"
SUCCEEDED = "已完成"
FAILED = "失败"
TERMINATED = "已终止"
@dataclass
class TaskRecord:
"""Coordinator 状态表里的一行:一个 Worker 的实时状态。"""
worker_id: str
source_name: str
state: TaskState = TaskState.SUBMITTED
note: str = ""
updated: float = field(default_factory=_now)
# ————————————————————————————— 子 Agent —————————————————————————————
class WorkerAgent:
"""
一个同构子 Agent:负责抓取并搜索单个来源。
通过消息总线接收 task_assigned / terminate,上报 status_update / result / ack。
"""
def __init__(self, worker_id: str, source: Source, bus: MessageBus, question: str):
self.id = worker_id
self.source = source
self.bus = bus
self.question = question
# 订阅:只关心发给自己或广播的 task_assigned 与 terminate
self.sub = bus.subscribe(worker_id, types=["task_assigned", "terminate"])
self._terminated = asyncio.Event()
async def _report(self, state: TaskState, note: str = "", type: str = "status_update"):
"""向 Coordinator 推送一条状态更新(实时监控的 push 范式)。"""
await self.bus.send(
self.id,
"coordinator",
type,
{"state": state.value, "note": note, "source": self.source.name},
)
async def _drain_signals(self) -> bool:
"""
在安全点检查是否收到 terminate 信号(非阻塞)。
收到则 ack 并返回 True,调用方据此优雅退出。
"""
while not self.sub.inbox.empty():
env = self.sub.inbox.get_nowait()
if env.type == "terminate":
self._terminated.set()
if self._terminated.is_set():
await self.bus.send(
self.id, "coordinator", "ack",
{"acked": "terminate", "source": self.source.name},
)
await self._report(TaskState.TERMINATED, "收到终止信号,安全退出")
return True
return False
async def run(self):
"""
Worker 主循环:分多步"抓取 + 搜索",每步之间都检查终止信号。
把单次抓取切成多步,是为了模拟真实 Computer Use Agent 的多轮操作,
也给级联终止提供"安全检查点"。
"""
# 等待 Coordinator 派发任务(task_assigned)
env = await self.sub.get()
while env.type != "task_assigned":
env = await self.sub.get()
await self._report(TaskState.RUNNING, "开始抓取来源")
steps = 3 # 把抓取拆成 3 步,制造可被中断的检查点
per_step = max(self.source.latency / steps, 0.05)
collected = ""
for i in range(1, steps + 1):
# —— 安全检查点:先看有没有被要求终止 ——
if await self._drain_signals():
return
# —— 执行一步抓取(模拟 Computer Use 的一轮操作耗时)——
await asyncio.sleep(per_step)
collected = self.source.content # 抓到的文本,最后一步再判断是否命中
await self._report(TaskState.RUNNING, f"抓取进度 {i}/{steps}")
# 再次检查终止(可能在最后一步耗时里收到)
if await self._drain_signals():
return
# —— 用(可选)LLM 或关键词判断是否命中答案 ——
answer = await judge_answer(self.question, collected)
if answer:
# 命中:把结果发回 Coordinator(可能与别的 Worker 竞态)
await self.bus.send(
self.id, "coordinator", "result",
{"found": True, "answer": answer, "source": self.source.name},
)
await self._report(TaskState.SUCCEEDED, f"命中:{answer}")
else:
await self.bus.send(
self.id, "coordinator", "result",
{"found": False, "source": self.source.name},
)
await self._report(TaskState.FAILED, "该来源未找到答案")
# ————————————————————————————— 主协调器 —————————————————————————————
class Coordinator:
"""
中心协调器:并行派发子 Agent、维护状态表、结算首个命中、广播级联终止。
"""
def __init__(self, bus: MessageBus, question: str):
self.bus = bus
self.question = question
# 订阅所有子 Agent 上报的消息类型
self.sub = bus.subscribe("coordinator", types=["status_update", "result", "ack"])
self.table: Dict[str, TaskRecord] = {}
self.workers: List[WorkerAgent] = []
# —— 竞态处理的关键状态 ——
self._settle_lock = asyncio.Lock() # 保证结算与终止广播互斥
self._settled = False # 幂等标志:是否已结算过
self.winner: Optional[str] = None # 第一个命中的 Worker
self.answer: Optional[str] = None
self.duplicate_hits: List[str] = [] # 记录"迟到的命中",证明竞态被正确忽略
self._acks: set[str] = set()
self._expected_workers = 0
def add_worker(self, worker: WorkerAgent):
self.workers.append(worker)
self.table[worker.id] = TaskRecord(worker.id, worker.source.name)
def _print_table(self, reason: str):
"""实时刷新并打印任务状态表。"""
print(f"\n ── 任务状态表({reason}) ──")
for rec in self.table.values():
print(
f" {rec.worker_id:<10} 源={rec.source_name:<12} "
f"状态={rec.state.value:<5} {('| ' + rec.note) if rec.note else ''}"
)
print()
async def _dispatch(self):
"""并行派发:给每个 Worker 发 task_assigned。"""
self._expected_workers = len(self.workers)
for w in self.workers:
self.table[w.id].state = TaskState.SUBMITTED
await self.bus.send(
"coordinator", w.id, "task_assigned",
{"question": self.question, "source": w.source.name},
)
self._print_table("已派发全部子 Agent")
async def _settle_if_first(self, worker_id: str, answer: str) -> bool:
"""
竞态处理核心:用锁 + 幂等标志保证只结算一次、只广播一轮终止。
返回 True 表示本次是"首个有效命中"。
"""
async with self._settle_lock:
if self._settled:
# 迟到的命中:已结算过,直接忽略(幂等)
self.duplicate_hits.append(worker_id)
print(
f" [竞态] {worker_id} 也命中,但已由 {self.winner} 结算 —— "
f"忽略此次命中,不重复广播终止。"
)
return False
# 首个命中:结算并广播一轮终止
self._settled = True
self.winner = worker_id
self.answer = answer
print(f" [结算] 首个命中来自 {worker_id} —— 加锁结算,广播一轮 terminate。")
await self.bus.send(
"coordinator", BROADCAST, "terminate",
{"reason": "answer_found", "winner": worker_id},
)
return True
async def run(self, quiet_period: float = 2.5) -> dict:
"""
协调主循环:派发 -> 监听上报 -> 结算首个命中 -> 收集 ack -> 汇总。
"""
mode = "LLM 判断" if llm_available() else "关键词判断(离线可复现)"
print(f" [协调器] 判断模式:{mode}\n")
t0 = time.monotonic() # 记录并行执行的墙钟起点
await self._dispatch()
# 启动所有 Worker 协程
worker_tasks = [asyncio.create_task(w.run()) for w in self.workers]
done_states = {TaskState.SUCCEEDED, TaskState.FAILED, TaskState.TERMINATED}
last_terminate_time: Optional[float] = None
while True:
env = await self.sub.get_nowait_or_wait(timeout=0.5)
if env is None:
# 没有新消息:若已结算且过了静默期,认为收敛,退出
if self._settled and last_terminate_time is not None:
if _now() - last_terminate_time > quiet_period:
break
# 全部 Worker 进入终态也退出
if all(r.state in done_states for r in self.table.values()):
break
continue
rec = self.table.get(env.sender_id)
if env.type == "status_update" and rec:
prev = rec.state
rec.state = TaskState(env.payload["state"])
rec.note = env.payload.get("note", "")
rec.updated = _now()
# 仅在"状态机跳变"时刷新状态表,避免每一步抓取都刷屏
if rec.state != prev:
self._print_table(f"{env.sender_id} -> {rec.state.value}")
elif env.type == "result":
if env.payload.get("found"):
is_first = await self._settle_if_first(
env.sender_id, env.payload["answer"]
)
if is_first:
last_terminate_time = _now()
elif env.type == "ack":
self._acks.add(env.sender_id)
print(f" [ack] {env.sender_id} 已确认终止({len(self._acks)} 个已 ack)")
# 等待所有 Worker 协程收尾
await asyncio.gather(*worker_tasks, return_exceptions=True)
elapsed = time.monotonic() - t0 # 并行执行的墙钟耗时(含收敛静默期)
self._print_table("最终状态")
return {
"winner": self.winner,
"answer": self.answer,
"duplicate_hits": self.duplicate_hits,
"acks": sorted(self._acks),
"settled_once": self._settled,
"terminate_broadcasts": sum(
1 for e in self.bus.history if e.type == "terminate"
),
"parallel_seconds": elapsed,
}
# ————————————————————————— 串行基线(性能对比) —————————————————————————
async def run_sequential(sources: List[Source], question: str) -> dict:
"""
串行基线:逐个来源"抓取 + 判断",命中即止。
用于对照并行执行的墙钟收益(对应书中实验要求"记录并对比并行/串行时间差异")。
这里真实地一个接一个 ``await source.fetch()``,因此耗时是**实测**而非估算——
绝不伪造数据;命中判断复用与并行版本相同的 :func:`judge_answer`。
"""
t0 = time.monotonic()
winner: Optional[str] = None
answer: Optional[str] = None
fetched = 0
for src in sources:
fetched += 1
text = await src.fetch()
ans = await judge_answer(question, text)
if ans:
winner, answer = src.name, ans
break
return {
"seconds": time.monotonic() - t0,
"winner": winner,
"answer": answer,
"fetched": fetched,
"total": len(sources),
}