AI Agent / 系统课时
实现主管协调模式
实现主管协调模式
主管协调模式把多 Agent 协作变成一个明确的控制闭环:主管接收目标,选择专业 Agent,传递必要上下文,验收结果,再决定结束、返工或继续分派。本节用一个可运行的最小协调器演示这条链路。
学习目标
- 理解主管 Agent 与专业 Agent 的职责分工
- 能实现“分派任务 → 收集结果 → 验收 → 决策”的最小闭环
- 能识别循环失控、上下文膨胀和权限扩散等常见风险
主管模式的控制闭环
主管 Agent 应位于控制平面:它理解用户目标和当前状态,但不直接承担所有专业工作。专业 Agent 只接收完成当前子任务所需的输入,并返回结构清楚的结果;主管基于结果决定下一步,而不是让 Agent 彼此自由调用形成不可控网络。

实现一个最小可运行协调器
把代码保存为 collab_supervisor.py,与上一课的角色定义放在同一目录。主管程序并发执行价格与 SLA 核查。两位专家只接收各自的输入,并返回结构化结论。样例里的证据判定来自可信的测试数据,结果只有满足必需条件时才会进入审查。
python
import asyncio
import math
from dataclasses import dataclass
from collab_roles import Principal, assignment, can_call
REQUIRED = {"research": ("read_quote", "quote_ref"), "risk": ("read_sla", "sla_ref")}
@dataclass(frozen=True)
class Claim:
case_id: str
evidence_ref: str
decision: str
async def run_check(role, worker, inputs, principal, evidence, timeout):
tool, ref_key = REQUIRED[role]
ref = inputs[ref_key]
record = evidence.get(ref)
if (
record is None or record["case_id"] != inputs["case_id"]
or not can_call(role, tool, principal, record["tenant_id"])
):
return "denied"
try:
claim = await asyncio.wait_for(worker(inputs), timeout=timeout)
except TimeoutError:
return "timeout"
except Exception:
return "failed"
if (
not isinstance(claim, Claim) or claim.case_id != inputs["case_id"]
or claim.evidence_ref != ref or claim.decision not in ("clear", "blocked")
or claim.decision != record["decision"]
):
return "invalid_evidence"
return claim.decision
async def supervise(workers, data, principal, evidence, timeout=0.1):
if not math.isfinite(timeout) or timeout <= 0:
raise ValueError("positive timeout required")
jobs = [(role, workers[role], assignment(role, data)) for role in REQUIRED]
results = await asyncio.gather(*[
run_check(role, worker, inputs, principal, evidence, timeout)
for role, worker, inputs in jobs
])
detail = dict(zip(REQUIRED, results))
if "blocked" in results:
return "blocked", detail
if all(result == "clear" for result in results):
return "ready_for_review", detail
return "incomplete", detail
async def research(inputs):
return Claim(inputs["case_id"], inputs["quote_ref"], "clear")
async def risk(inputs):
return Claim(inputs["case_id"], inputs["sla_ref"], "clear")
async def slow_risk(inputs):
await asyncio.Event().wait()
async def main():
principal = Principal("team-a", frozenset({"read_quote", "read_sla"}))
data = {"case_id": "case-42", "quote_ref": "quote-1", "sla_ref": "sla-1"}
evidence = {
"quote-1": {"case_id": "case-42", "tenant_id": "team-a", "decision": "clear"},
"sla-1": {"case_id": "case-42", "tenant_id": "team-a", "decision": "clear"},
}
print(await supervise({"research": research, "risk": risk}, data, principal, evidence))
print(await supervise({"research": research, "risk": slow_risk}, data, principal, evidence))
if __name__ == "__main__":
asyncio.run(main())预期输出
text
('ready_for_review', {'research': 'clear', 'risk': 'clear'})
('incomplete', {'research': 'clear', 'risk': 'timeout'})区分程序编排和模型协调
OpenAI Agents SDK 可以用 Agent.as_tool() 让主管保留最终答复的控制权,模型会按运行过程选择是否调用专家。必须执行的检查应由编排层调度或独立验证实际调用记录。下一课的 SDK 移交则把对话控制交给接手专家。
asyncio.gather() 调度两个异步任务,并按传入顺序返回结果。任务必须能在异步等待时交还执行权,同步阻塞会拖住其他检查。wait_for() 超时后请求取消并等待取消处理,实际返回可能晚于预算。取消也无法证明外部操作未执行。生产环境分别限制并发、单次时长和整次任务预算,并对各子结果单独保留证据与状态。
主管的“可送审”只是一项流程状态。实际批准、发布及写入要由有权限的服务依据最新状态、证据和审批执行。
按自己的节奏,确认真正理解。