"""
实验 10-6 演示入口:同时从多个网站搜集信息的 Agent
=================================================
一条命令即可运行:
python demo.py
演示内容(对应书中强调的机制):
(a) 消息总线的发布/订阅:日志里可见带信封的消息流(BUS 前缀);
(b) N 个子 Agent 并行执行,主协调器实时刷新任务状态表;
(c) 某子 Agent 命中后触发级联终止,其余 Agent 收到 terminate 并优雅退出(ack);
(d) 多个子 Agent 几乎同时命中时,只结算一次、只广播一轮终止(幂等 + 加锁);
(e) (--compare)并行 vs 串行的墙钟耗时实测对比,验证并行化的性能收益。
默认使用离线的关键词判断,保证结果可复现;
若配置了 OPENAI_API_KEY 且未设 USE_LLM=0,子 Agent 会改用真实 LLM 做判断。
命令行参数详见 `python demo.py --help`;不传任何参数即为原有默认行为
(10 个子 Agent、内置问题、离线关键词判断、详细 BUS 日志)。
"""
from __future__ import annotations
import argparse
import asyncio
import json
import os
import time
try:
from dotenv import load_dotenv
load_dotenv()
except Exception: # noqa: BLE001 —— 没装 python-dotenv 也能跑
pass
from agents import Coordinator, WorkerAgent, run_sequential
from llm import llm_available
from message_bus import MessageBus
from sources import DEMO_SOURCES, QUESTION, build_sources
def _parse_args() -> argparse.Namespace:
"""解析命令行参数;不传任何参数时行为与之前完全一致(10 Agent、离线、详细日志)。"""
parser = argparse.ArgumentParser(
prog="demo.py",
formatter_class=argparse.RawDescriptionHelpFormatter,
description=(
"实验 10-6:多个同构子 Agent 并行搜索 + 中心协调的演示。\n"
"展示消息总线发布/订阅、并行派发、实时状态监控、级联终止与竞态处理;\n"
"默认离线关键词判断(结果可复现),不传参数即为原有默认行为。"
),
epilog=(
"示例:\n"
" python demo.py # 默认:10 个 Agent、内置问题、离线可复现\n"
" python demo.py --agents 6 # 改为 6 个并行 Agent\n"
" python demo.py --compare # 额外实测并行 vs 串行的墙钟耗时\n"
" python demo.py --output result.json # 把结论写入 JSON 文件\n"
" python demo.py --use-llm --model gpt-5.6-luna # 用真实 LLM 判断(需配 key)"
),
)
parser.add_argument(
"-q",
"--query",
default=QUESTION,
metavar="问题",
help="研究问题(默认使用内置问题)。注意:离线关键词判断是针对内置来源调校的,"
"自定义问题通常应搭配 --use-llm 的真实 LLM 判断才有意义。",
)
parser.add_argument(
"-n",
"--agents",
type=int,
default=len(DEMO_SOURCES),
metavar="N",
help=f"并行子 Agent 的数量(默认 {len(DEMO_SOURCES)},对应书中约 10 个并行 Agent)。"
"N>=2 时始终包含两个含答案的源以稳定演示竞态与级联终止。",
)
parser.add_argument(
"--model",
default=None,
metavar="MODEL",
help="LLM 模型名(等价于设置环境变量 OPENAI_MODEL;仅在 --use-llm 且配置了 "
"OPENAI_API_KEY 或 OPENROUTER_API_KEY 时生效)。默认沿用环境变量或 gpt-5.6-luna。",
)
parser.add_argument(
"-o",
"--output",
default=None,
metavar="PATH",
help="把最终结论(含并行/串行耗时、winner、竞态统计)以 JSON 写入该路径。默认不写文件。",
)
parser.add_argument(
"--compare",
action="store_true",
help="并行运行结束后,再实测一遍串行基线并打印墙钟耗时对比(验证并行化收益)。默认不运行串行基线。",
)
parser.add_argument(
"--use-llm",
action="store_true",
help="强制启用真实 LLM 判断(等价于环境变量 USE_LLM=1;仍需配置 "
"OPENAI_API_KEY 才会真正生效,否则自动回退离线关键词判断)。默认不启用。",
)
parser.add_argument(
"--quiet",
action="store_true",
help="减少消息总线的逐条 BUS 日志打印(任务状态表/结论/自检不受影响)。默认打印全部日志。",
)
return parser.parse_args()
async def main(args: argparse.Namespace):
if args.agents < 1:
raise SystemExit("错误:--agents 至少为 1")
if args.use_llm:
# 仅设置意图开关;是否真正调用 LLM 仍取决于 llm.llm_available()
# (还需配置 OPENAI_API_KEY),未配置时会自动回退离线关键词判断。
os.environ["USE_LLM"] = "1"
if args.model:
os.environ["OPENAI_MODEL"] = args.model
sources = build_sources(args.agents)
print("=" * 78)
print("实验 10-6 · 同时从多个网站搜集信息的 Agent(并行搜索 + 中心协调)")
print("=" * 78)
print(f"任务问题:{args.query}")
print(f"并行来源数:{len(sources)} 个模拟'网站'(子 Agent 数 = 来源数)")
answer_srcs = [s.name for s in sources if s.holds_answer]
print(f"含答案的源:{answer_srcs}(其中前两个延迟相同,用于演示竞态)")
print("-" * 78)
bus = MessageBus(verbose=not args.quiet)
coordinator = Coordinator(bus, args.query)
# 并行装配 N 个同构子 Agent,每个绑定一个来源
for i, src in enumerate(sources):
w = WorkerAgent(f"worker-{i:02d}", src, bus, args.query)
coordinator.add_worker(w)
result = await coordinator.run()
print("=" * 78)
print("演示结论(自动校验)")
print("=" * 78)
total_msgs = len(bus.history)
print(f"1) 消息总线共传递 {total_msgs} 条带信封消息(发布/订阅正常工作)。")
print(f"2) {len(coordinator.workers)} 个子 Agent 并行执行,状态表全程实时刷新。")
print(f"3) 首个命中并结算的 Worker:{result['winner']}")
print(f" 答案:{result['answer']}")
print(f" 收到 terminate 并 ack 的 Worker:{result['acks']}")
print(f"4) terminate 广播轮数:{result['terminate_broadcasts']}(应为 1,证明只广播一轮)")
print(f" 迟到/并发的重复命中被忽略:{result['duplicate_hits'] or '无(本次无并发迟到命中)'}")
print(f" 是否只结算一次:{result['settled_once']}")
print(f"5) 并行执行墙钟耗时:{result['parallel_seconds']:.2f}s(含收敛静默期)")
# —— (e) 并行 vs 串行的墙钟对比:实测,绝不伪造 ——
seq = None
if args.compare:
print("-" * 78)
print("并行 vs 串行 墙钟对比(--compare,串行基线为实测)")
print("-" * 78)
seq = await run_sequential(sources, args.query)
print(
f" 串行:命中前逐个抓取了 {seq['fetched']}/{seq['total']} 个源,"
f"墙钟耗时 {seq['seconds']:.2f}s,winner={seq['winner']}"
)
print(f" 并行:墙钟耗时 {result['parallel_seconds']:.2f}s,winner={result['winner']}")
if seq["seconds"] > 0 and result["parallel_seconds"] > 0:
speedup = seq["seconds"] / result["parallel_seconds"]
saved = seq["seconds"] - result["parallel_seconds"]
print(f" 加速比 ≈ {speedup:.2f}×,节省约 {saved:.2f}s(并行让最快的源立即结束全局搜索)。")
# —— 结论落盘(可选)——
if args.output:
summary = {
"question": args.query,
"num_agents": len(coordinator.workers),
"sources": [s.name for s in sources],
"judge_mode": "llm" if llm_available() else "keyword_offline",
"total_bus_messages": total_msgs,
"winner": result["winner"],
"answer": result["answer"],
"duplicate_hits": result["duplicate_hits"],
"acks": result["acks"],
"settled_once": result["settled_once"],
"terminate_broadcasts": result["terminate_broadcasts"],
"parallel_seconds": round(result["parallel_seconds"], 3),
"sequential_baseline": (
{
"seconds": round(seq["seconds"], 3),
"fetched": seq["fetched"],
"winner": seq["winner"],
}
if seq
else None
),
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
}
with open(args.output, "w", encoding="utf-8") as f:
json.dump(summary, f, ensure_ascii=False, indent=2)
print(f"\n[已写入] 结论 JSON -> {args.output}")
# —— 断言式自检:仅在离线可复现模式下强断言(LLM 模式命中与否取决于模型)——
if not llm_available():
assert result["winner"] is not None, "应至少有一个 Worker 命中"
assert result["terminate_broadcasts"] == 1, "级联终止只能广播一轮"
assert result["settled_once"] is True, "必须完成且只结算一次"
print("\n[自检通过] 单次结算 + 单轮终止广播 + 级联 ack 均符合预期。")
else:
print("\n[提示] 当前为真实 LLM 判断模式,是否命中取决于模型,不做强断言。")
if __name__ == "__main__":
asyncio.run(main(_parse_args()))