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() 超时后请求取消并等待取消处理,实际返回可能晚于预算。取消也无法证明外部操作未执行。生产环境分别限制并发、单次时长和整次任务预算,并对各子结果单独保留证据与状态。

主管的“可送审”只是一项流程状态。实际批准、发布及写入要由有权限的服务依据最新状态、证据和审批执行。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现主管协调模式

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通