agent-council

Agent Council

召集一组专家 Agent，就任何问题展开辩论。委员会遵循结构化流程——构思、事前验尸、陈述立场、交叉质询（迭代进行）、综合——并生成决策全景及趋同诊断。

适用场景

符合以下任一情况时，可调用委员会：

• 问题确实存在权衡，没有明确的正确答案
• 你希望通过多视角分析揭示隐藏假设
• 决策可以从对抗式协作中受益
• 你希望获得信心诊断（而不只是建议）
• 问题影响重大，或后果不可逆

提示语：“我们来听听多方观点” / “辩论一下：X” / “专家会如何看待 X？” / “我们遗漏了什么？”

快速开始

1. 安装

# One-time setup
pip install pydantic-ai
pip install agent-council

# Or install from this skill directory:
python3 scripts/bootstrap.py

2. 配置

export AGENT_COUNCIL_API_KEY="sk-..."
export AGENT_COUNCIL_MODEL="openai:gpt-5.6-luna"

3. 运行

agent-council "Should we use Postgres or SQLite for this service?"

命令参考

agent-council [OPTIONS] <question>

Options:
  --agents, -n {3,4,5,6,7}  Number of agents (default: 5)
  --mode, -m {quick,medium,deep}  Debate depth (default: medium)
  --profiles TEXT          Comma-separated profile names from the hermes-profiles
                           library (e.g. "debugger,researcher,product-manager")
  --persona-file PATH      JSON file with custom agent personas
  --json                   Output structured JSON instead of markdown
  --verbose, -v            Show phase-by-phase progress
  --max-rounds INTEGER     Max cross-examination rounds (default: 4)
  --convergence FLOAT      Convergence threshold (default: 0.10)

模式选择

模式	Agent 数量	轮次	适用场景
quick	3	1 轮交叉质询	低风险检查，需要快速得到答案
medium（默认）	5	根据评估确定，最多 4 轮	常规决策
deep	7	根据评估确定，最多 4 轮	影响重大、存在隐藏假设

角色档案选择

在递归检出的源代码库中，委员会会从随附的 hermes-profiles 库中自动选择相关的真实专业角色档案。每份档案都有一个 SOUL.md——其中记录了真实的方法论、价值观和行事原则的身份文档，而非虚构的人设。Pip 和 wheel 安装包不包含该库；请改用生成的人设或用户提供的人设。

自动选择

未提供 --profiles 标志时，委员会会使用关键词重合度，根据档案描述与问题的匹配程度为每份档案评分，并选出相关度最高的 N 份档案。这最适用于聚焦于单一领域的问题。

显式选择

agent-council --profiles debugger,data-scientist,product-manager "What architecture should we choose?"

以逗号分隔的档案名称。可用档案包括：ceo、cfo、cmo、coo、cpo、cto、curator、data-architect、data-engineer、data-scientist、debugger、editor、frontend-engineer、ml-engineer、orchestrator、product-manager、researcher、reviewer、security-engineer、site-reliability-engineer、technical-architect、technical-writer、ux-designer、verifier、wonderer、writer 等。

选择档案来源

可通过以下三种方式为委员会配置角色，各有不同的优缺点：

方式	最适用场景	多样性	设置
--profiles（自动选择）	关键词明确的单领域问题	高——档案具有真实的 SOUL.md 方法论	需要递归检出源代码库
--profiles name1,name2	已知相关利益方的定向辩论	最高——由你挑选特定的方法论视角	需要递归检出源代码库和档案名称
--persona-file file.json	完全控制 Agent 身份、自定义领域	不定——取决于你的设计方式	创建一个 JSON 文件
自动（不传标志）	默认方式——有可用档案时使用档案，否则使用生成的人设	良好——因可用档案而异	生成的人设无需设置；真实档案需要递归检出源代码库

大多数情况下，让系统自动选择，或使用 --profiles 并指定 3-5 个名称。只有在需要现有档案无法涵盖的特定虚构专业知识时，才使用 --persona-file。

自定义人设（后备方案）

如果角色档案库不可用，或你希望完全掌控人设，请使用 --persona-file 提供自己的角色定义。若既未提供 --profiles，也未提供 --persona-file，委员会会从档案库自动选择档案；如果档案库不存在，则改用大模型生成的人设。

工作原理

流程

Compose ──► Premortem ──► Position ──► Cross-examine ──► [eval] ──► Synthesis
  (1)        (parallel)    (parallel)    (iterative loop)    ↑        (1)

                    ┌── converged ──────┐
                    ├── diminishing_ret │
    eval ───────────┼── genuine_disagr──┼──► Synthesis
                    └── continue ───────┘
                          ↓
                   Cross-examine (next round)

阶段

阶段	发生的事情	方法
构思	单次大模型调用会生成 N 个针对问题调整的专家角色	1 次调用
预演失败	每个 Agent 独立设想决策已经失败的情形 — 绕过立场承诺偏差	N 次并行调用
形成立场	每个 Agent 参考自己的预演失败结果，形成独立立场	N 次并行调用
交叉质询	每个 Agent 阅读其他所有立场并作出回应 — 让步、反对、更新信心	每轮 N 次并行调用
评估	收敛检测：衡量分歧程度、论点新颖度、让步率。决定继续循环还是停止	算法执行
综合	汇总所有阶段，形成结构化的决策全景，并附上由大模型生成的叙述	1 次调用

收敛检测

评议团不会采用固定的轮数。每轮交叉质询后，都会衡量以下指标：

• 信心分歧程度 — Agent 信心分数的标准差。低于阈值 = 已收敛。
• 论点新颖度 — 之前轮次中未出现的新论点。接近零 = 收益递减。
• 让步率 — Agent 改变立场的论点。为零且没有新论点 = 陷入停滞。

停止条件：

条件	含义
converged	分歧程度低于阈值，信心稳定。达成真正共识。
diminishing_returns	没有新论点或让步。没有更多内容可供提出。
genuine_disagreement	分歧程度扩大，立场变得坚定。总结无法消除的分歧。
max_rounds	达到轮数上限。结论不确定 — 必须由负责人决定。

引导安装

如果 agent-council 不在 PATH 中，调用 Agent 应运行：

python3 scripts/bootstrap.py

此操作会使用当前 Python 的 pip 从技能目录安装软件包；如果失败，则改用 pipx。引导安装路径不依赖 PyPI — 软件包包含在技能目录中。

如果引导安装失败： 手动运行以下任一命令：

pip install pydantic-ai
pip install agent-council

# Or from this directory:
python3 -m pip install -e /path/to/agent-council/

可用脚本

此技能仅捆绑一个脚本，无需查找其他脚本。

脚本	用途	调用方式
scripts/bootstrap.py	首次运行安装程序：检查 agent-council 是否已在 PATH 中；如果不在，则使用当前 Python 的 pip 从技能目录安装软件包，失败时改用 pipx。每当 PATH 中找不到 agent-council 时都应运行此脚本（调用 Agent 在这种情况下应自动运行）；当 CLI 可用时退出码为 0，无法安装时退出码为 1，并提供手动安装说明。如果引导安装失败，请按照上述手动步骤操作。	python3 scripts/bootstrap.py

配置

环境变量	必需	默认值	描述
AGENT_COUNCIL_API_KEY	是	—	大模型提供商的 API 密钥
AGENT_COUNCIL_MODEL	否	openai:gpt-5.6-luna	模型字符串（provider/model）
AGENT_COUNCIL_BASE_URL	否	提供商默认值	自定义 API 端点（OpenRouter、LiteLLM 等）

你可以将这些设为环境变量，也可以在运行 agent-council 的目录中创建 .env 文件：

# .env file
AGENT_COUNCIL_API_KEY=sk-...
AGENT_COUNCIL_MODEL=openai:gpt-5.6-luna

环境变量的优先级高于 .env 文件中的值。

模型字符串遵循 PydanticAI 约定：openai:gpt-5.6-luna、anthropic:claude-sonnet-4-20250514、deepseek:deepseek-v4-flash、google:gemini-2.0-flash。

输出

综合报告是一个结构化的决策全景图。在 Markdown 模式下，它包含：

1. 置信度离散度表 — 每轮的置信度指标及诊断
2. 共同风险 — 事前分析中的失效模式（先于讨论提出，未受讨论影响）
3. 共同关切 — 经交叉质询后仍被认定为真实共同风险的事项
4. 尚存分歧 — 未能解决的立场
5. 各立场的假设 — 每个立场成立所必须满足的条件
6. 负责人决策路径 — 对决策全景图的叙述式综合

使用 --json 进行程序化处理。JSON 输出遵循以下结构：

{
  "question": "string",
  "mode": "quick|medium|deep",
  "num_agents": 3,
  "rounds_completed": 2,
  "stopped_reason": "converged|max_rounds|diminishing_returns|genuine_disagreement",
  "confidence_history": [
    {"round": 1, "mean_confidence": 0.74, "dispersion": 0.061, "new_arguments": 20, "concessions_made": 17}
  ],
  "shared_risks": [{"description": "...", "severity": "low|medium|high", "phase_discovered": "premortem"}],
  "shared_concerns": ["..."],
  "disagreements": [{"topic": "...", "positions": {"agent_a": "position_a", "agent_b": "position_b"}}],
  "assumptions_per_position": {"agent_name": ["assumption1", "assumption2"]},
  "principal_path": "narrative text"
}

声明核验

每份综合输出都会包含一轮辩论后的核验扫描。另一次独立的 LLM 调用会读取叙述式综合内容，并找出辩论无法通过自身推理核实的、关于可验证外部事实（域名可用性、软件包命名空间状态、定价、统计数据）的任何声明。被标记的声明会附加在 ⚠️ 未核实的声明部分：

⚠️  Claims Not Verified
The following assertions in this synthesis could not be verified
by the council's own reasoning and should be checked before acting:
  • "Dialekt passes all five checks..." — domain availability:
    No evidence the council checked domain registries

这并不意味着否定综合结果，而是一项质量提示。本节中的声明应视为有待核实的假设，而非事实。

如何解读收敛诊断

置信度离散度表会告诉你这场辩论是否富有成效：

模式	含义	应对方式
平均置信度下降，离散度扩大	评议会发现了真实疑虑——这是良性辩论	重视共同关切；调查新发现的风险
平均置信度上升，离散度缩小	真正达成共识——Agent 彼此说服	这是最强信号；也是置信度最高的前进路径
平均置信度稳定，离散度缩小	可能是假共识——Agent 在辩论前就已达成一致	查看假设部分，寻找共同盲点
平均置信度上升，离散度扩大	两极分化——Agent 的立场变得更加坚定	单靠论证可能无法真正解决问题；寻找实验路径
stopped_reason: converged	离散度降至阈值以下	很好——按建议执行
stopped_reason: max_rounds	达到硬性上限，尚未收敛	辩论被中止；可考虑提高 --max-rounds 后再次运行，或使用 --mode quick 加快收敛
stopped_reason: diminishing_returns	没有出现新论据	评议会已穷尽其能发现的内容——做出决定
stopped_reason: genuine_disagreement	立场变得更加坚定，离散度扩大	评议会未能化解分歧。这份输出的价值恰恰在于呈现了无法调和的分歧——请仔细阅读分歧部分

常见问题

症状	原因	解决方法
辩论失败，并提示 "Exceeded maximum output retries"	模型无法为某个阶段生成有效的结构化输出	重试辩论。如果问题持续出现，请尝试更换模型，或添加 --verbose 查看哪个 Agent 失败。
辩论运行 5 分钟以上仍无输出	DeepSeek 或运行缓慢的模型搭配了多个 Agent	使用 --mode quick --agents 3 加快周转，或使用 --verbose 实时查看进度。
所有 Agent 都立即以高置信度达成一致	假共识——同一模型存在共同盲点	查看离散度诊断。尝试使用 --profiles 配置多样化身份，以强制引入方法上的多样性。
出现 "Profile X not found" 警告	配置文件名称拼写错误	运行 agent-council --profiles list（或查看上方的配置文件列表），以确认有效名称。
综合内容包含明显的事实错误	Agent 在辩论中编造了声明	查看 ⚠️ 未核实的声明部分。防护机制可以减少编造，但无法完全消除。采取行动前，请核实任何统计数据、定价或可用性声明。

架构决策

单模型辩论： 所有 Agent 共用同一套大模型配置。多样性来自角色设定（具有不同背景、分析方法和偏见的系统提示词），而非不同的模型实例。这能最大限度地降低配置门槛——只需一个 API 密钥、一个端点，成本也可预测。

局限性： 所有 Agent 共用该模型的知识截止时间和盲点。如果信心一开始就很高且始终没有变化，收敛诊断会标记“可能存在虚假共识”。

参考文件

文件	何时加载
references/convergence.md	了解收敛检测算法时
references/debate-protocol.md	深入了解阶段结构和轮次设计时
references/configuration.md	设置提供商、排查问题和了解模型字符串时

目录结构

agent-council/
├── SKILL.md                      # This file — skill entry point
├── pyproject.toml                # Pip package definition
├── README.md
├── LICENSE                       # MIT
├── agent_council/                # Python package
│   ├── cli.py                    # CLI entry point
│   ├── config.py                 # Env var loading
│   ├── state.py                  # Typed state + Pydantic models
│   ├── convergence.py            # Convergence detection
│   ├── graph.py                  # Debate graph orchestration
│   └── phases/
│       ├── compose.py            # Persona generation
│       ├── premortem.py          # Failure pre-mortem
│       ├── position.py           # Initial positions
│       ├── cross_examine.py      # Iterative cross-examination
│       └── synthesis.py          # Decision landscape
├── scripts/
│   └── bootstrap.py              # First-run installation
├── templates/
│   └── personas.json             # Example custom personas
└── references/
    ├── convergence.md
    ├── debate-protocol.md
    └── configuration.md

前置条件

• Python 3.10+ 和 pydantic-ai 包；可通过 pip、pipx 或 python3 scripts/bootstrap.py 安装（该包随此技能目录一同提供，因此引导过程无需访问 PyPI）。
• 将 LLM 提供商的 API 密钥导出为 AGENT_COUNCIL_API_KEY（或在 .env 文件中设置）；也可选择设置 AGENT_COUNCIL_MODEL 和 AGENT_COUNCIL_BASE_URL。
• hermes-profiles 库中的真实专业人士档案仅在递归式源代码检出中可用；通过 pip 和 wheel 安装时使用生成的角色设定或用户提供的角色设定。

局限性

• 单模型辩论：所有 Agent 共用同一套大模型配置，因此也共用其知识截止时间和盲点；多样性来自角色设定，而非模型实例（参见“架构决策”）。
• 每轮辩论会并行发起许多大模型调用——使用速度较慢的模型或深度模式时，可能需要数分钟；采取行动前，请检查每份综合结果中的 ⚠️ 声明未经验证，确认可核实的外部事实。
• 收敛诊断可以减少编造内容和虚假共识，但无法完全消除；达到 max_rounds 上限意味着辩论尚无定论，须由负责人作出决断。
• 这不是通用的 Agent 编排框架：它只运行辩论——如需超出辩论协议的状态机编排，请转而使用 langgraph。

相关技能

• ai-frameworks — 涵盖所有 AI 框架技能的总览套件。比较 agent-council 与其他多 Agent 方案（LangGraph、AutoGen、CrewAI）时加载。
• langgraph — 用于超出辩论协议的复杂状态机多 Agent 编排
• pydanticai — 用于定义类型安全 Agent 的底层框架
• spec-driven-development — 用于构建可由 agent-council 协助评估的规范
• hermes-profiles — 为档案选择系统提供支持的 39 个档案库