agent-council

エージェント評議会

専門エージェントのパネルを招集し、あらゆる質問について議論します。評議会は、構成、プレモーテム、立場表明、反対尋問（反復）、統合という構造化されたプロトコルに従い、収束度の診断を含む意思決定の全体像を提示します。

使用する場面

次のいずれかに当てはまる場合は、評議会を呼び出してください。

• 明確な正解がなく、実質的なトレードオフがある質問
• 多角的な分析によって、隠れた前提を明らかにしたい場合
• 対立的な協働が意思決定に役立つ場合
• 推奨事項だけでなく、確信度の診断も必要な場合
• 重大な影響や取り消せない結果を伴う質問

シグナルとなる表現：「複数の視点から考えてみましょう」／「これについて議論してください：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)

モードの選択

モード	エージェント数	ラウンド数	使用する場面
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などがあります。

プロファイルソースの選択

評議会を構成する方法は3つあり、それぞれ異なるトレードオフがあります。

方法	最適な用途	多様性	セットアップ
--profiles（自動選択）	キーワードが明確な単一分野の質問	高い — プロファイルには実際のSOUL.mdの手法がある	再帰的なソースチェックアウトが必要
--profiles name1,name2	関係者がわかっている、対象を絞った議論	最も高い — 特定の手法に基づく視点を選べる	再帰的なソースチェックアウトとプロファイル名が必要
--persona-file file.json	エージェントのアイデンティティや独自分野を完全に制御	可変 — 設計方法によって異なる	JSONファイルを作成
自動（フラグなし）	デフォルト — 利用可能であればプロファイルを使い、なければ生成にフォールバック	良好 — 利用可能なプロファイルによって変化	生成ペルソナにはセットアップ不要。実在のプロファイルには再帰的なソースチェックアウトが必要

ほとんどの場合、自動選択に任せるか、--profilesに3～5個の名前を指定してください。--persona-fileは、既存のプロファイルに該当しない、特定の架空の専門知識が必要な場合にのみ使用してください。

カスタムペルソナ（フォールバック）

プロファイルライブラリを利用できない場合や、完全な制御が必要な場合は、--persona-fileを使って独自のペルソナ定義を指定してください。--profilesも--persona-fileも指定されていない場合、評議会はライブラリからプロファイルを自動選択します。ライブラリがない場合は、LLMで生成したペルソナにフォールバックします。

仕組み

パイプライン

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)

フェーズ

フェーズ	内容	方法
構成	1 回の LLM 呼び出しで、質問に合わせた N 人の専門家ペルソナを生成します	1 回の呼び出し
プレモーテム	各エージェントが、すでに意思決定が失敗した状況を独立して想像します。これにより、立場への固執によるバイアスを回避します	N 回の並列呼び出し
立場表明	各エージェントが、自身のプレモーテムを参照しながら独立した立場を形成します	N 回の並列呼び出し
相互反対尋問	各エージェントが他のすべての立場を読み、譲歩、反論、確信度の更新を行います	ラウンドごとに N 回の並列呼び出し
評価	収束を検出します。意見のばらつき、議論の新規性、譲歩率を測定し、反復するか終了するかを決定します	アルゴリズム
統合	すべてのフェーズを、LLM が生成した説明を含む構造化された意思決定の全体像にまとめます	1 回の呼び出し

収束の検出

この評議会では、ラウンド数を固定しません。相互反対尋問の各ラウンド後に、次の項目を測定します。

• 確信度のばらつき — エージェントの確信度スコアの標準偏差です。しきい値未満なら収束したと判断します。
• 議論の新規性 — これまでのラウンドで出ていない新たな議論です。ほぼゼロなら効果が薄れていることを示します。
• 譲歩率 — エージェントが立場を変えた点です。新しい議論がなく、譲歩もゼロなら行き詰まりです。

停止条件：

条件	意味
converged	ばらつきがしきい値未満で、確信度が安定しています。真の合意です。
diminishing_returns	新たな議論や譲歩がありません。これ以上明らかにできることはありません。
genuine_disagreement	ばらつきが広がり、立場が固まりました。解消できない意見の対立を要約します。
max_rounds	上限に達しました。結論は出ていないため、最終判断はプリンシパルが下す必要があります。

ブートストラップ

agent-council が PATH 上で利用できない場合、呼び出し元のエージェントは次を実行してください。

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/

利用可能なスクリプト

このスキルに含まれるスクリプトは 1 つだけです。他に確認するスクリプトはありません。

スクリプト	目的	実行方法
scripts/bootstrap.py	初回実行時のインストーラーです。agent-council がすでに PATH 上にあるか確認し、なければ現在の Python の pip を使用してスキルディレクトリからパッケージをインストールし、利用できない場合は pipx にフォールバックします。agent-council が PATH 上で見つからない場合は必ず実行してください（その場合、呼び出し元のエージェントが自動的に実行します）。CLI が利用可能になれば終了コード 0 で終了し、インストールできなかった場合は手動インストールの手順を表示して終了コード 1 で終了します。ブートストラップに失敗した場合は、上記の手動手順に従ってください。	python3 scripts/bootstrap.py

設定

環境変数	必須	デフォルト	説明
AGENT_COUNCIL_API_KEY	はい	—	LLM プロバイダーの 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

これは統合内容を否定するものではなく、品質を示すシグナルです。このセクションの主張は事実ではなく、検証が必要な仮説として扱ってください。

収束診断の読み方

確信度のばらつき表から、議論が有意義だったかどうかを判断できます。

パターン	意味	対応
平均確信度が低下し、ばらつきが拡大	評議会が真の疑念を掘り起こしました。健全な議論です	共通の懸念事項を重視し、新たに明らかになったリスクを調査してください
平均確信度が上昇し、ばらつきが縮小	真の収束です。エージェント同士が互いを納得させました	最も強いシグナルであり、今後の道筋として最も確信度が高いものです
平均確信度が安定し、ばらつきが縮小	偽りの合意の可能性があります。議論の前にエージェントが合意していました	前提セクションを調べ、共通の盲点がないか確認してください
平均確信度が上昇し、ばらつきが拡大	分極化です。エージェントがさらに自説に固執しました	議論だけでは解決できない問いかもしれません。実験による解決策を探してください
stopped_reason: converged	ばらつきがしきい値を下回りました	良好です。推奨事項に沿って進めてください
stopped_reason: max_rounds	収束する前に上限に達しました	議論が途中で打ち切られました。--max-rounds を増やすか、より速く収束する --mode quick を指定して、もう一度実行してください
stopped_reason: diminishing_returns	新たな論点が出なくなりました	評議会が発見できるものは出尽くしました。判断を下してください
stopped_reason: genuine_disagreement	立場が固定化し、ばらつきが拡大しました	評議会は対立を解消できませんでした。解消不能な意見の相違を明らかにする点にこそ、出力の価値があります。意見の相違セクションを注意深く読んでください

注意点

症状	原因	解決策
「Exceeded maximum output retries」で議論が失敗する	モデルがフェーズに必要な有効な構造化出力を生成できませんでした	議論を再試行してください。問題が続く場合は、別のモデルを試すか、--verbose を追加してどのエージェントが失敗したか確認してください。
出力がないまま議論に 5 分以上かかる	多数のエージェントを使った DeepSeek または応答の遅いモデル	すばやく処理するには --mode quick --agents 3 を使用するか、--verbose を指定して進捗をリアルタイムで確認してください。
すべてのエージェントが高い確信度で即座に同意する	偽りの合意です。同じモデルが同じ盲点を共有しています	ばらつき診断を確認してください。多様なアイデンティティを持つエージェントを使って方法論の多様性を高めるには、--profiles を試してください。
「Profile X not found」警告	プロファイル名の入力ミス	有効な名前を確認するには、agent-council --profiles list を実行するか、上記のプロファイル一覧を確認してください。
統合内容に明らかな事実誤認が含まれる	議論中にエージェントが主張を捏造しました	⚠️ 未検証の主張セクションを確認してください。この安全策は捏造を減らしますが、完全に排除することはできません。行動に移す前に、統計情報、価格、または利用可能性に関する主張を検証してください。

アーキテクチャ上の決定

単一モデルでの討論： すべてのエージェントが同じ LLM 設定を共有します。多様性は、異なる背景、分析手法、バイアスを持つペルソナ定義（システムプロンプト）から生まれ、異なるモデルインスタンスから生まれるものではありません。これにより、API キー 1 つ、エンドポイント 1 つ、予測可能なコストで済み、セットアップの手間を最小限に抑えられます。

制限事項： すべてのエージェントがモデルの知識のカットオフと盲点を共有します。収束診断では、確信度が高いまま変化しない場合に「誤った合意の可能性」フラグが表示されます。

参照ファイル

ファイル	読み込むタイミング
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

前提条件

• pydantic-ai パッケージを含む Python 3.10 以降。pip、pipx、または python3 scripts/bootstrap.py でインストールしてください（パッケージはこのスキルディレクトリ内に含まれているため、bootstrap に PyPI へのアクセスは不要です）。
• LLM プロバイダーの API キーを AGENT_COUNCIL_API_KEY としてエクスポートするか、.env ファイルに設定してください。必要に応じて AGENT_COUNCIL_MODEL と AGENT_COUNCIL_BASE_URL も設定できます。
• hermes-profiles ライブラリの実際の専門家プロフィールを利用できるのは、ソースを再帰的にチェックアウトした場合のみです。pip および wheel によるインストールでは、生成されたペルソナまたはユーザーが提供したペルソナが使用されます。

制限事項

• 単一モデルでの討論では、すべてのエージェントが同じ LLM 設定を共有するため、その知識のカットオフと盲点も共有します。多様性はモデルインスタンスではなく、ペルソナ定義から生まれます（「アーキテクチャ上の決定」を参照）。
• 討論では各ラウンドで多数の LLM 呼び出しが並行して行われます。低速なモデルやディープモードでは数分かかることがあります。また、検証可能な外部事実に基づいて行動する前に、すべての統合結果で ⚠️ Claims Not Verified を確認してください。
• 収束診断により、捏造や誤った合意を減らすことはできますが、完全に排除することはできません。max_rounds に達して停止した場合は討論が未決着であり、プリンシパルが結論を出す必要があります。
• これは汎用のエージェントオーケストレーションフレームワークではありません。討論のみを実行します。討論プロトコルを超えるステートマシンオーケストレーションには、langgraph を使用してください。

関連スキル

• ai-frameworks — すべての AI フレームワークスキルをまとめた包括的なバンドルです。agent-council と他のマルチエージェントアプローチ（LangGraph、AutoGen、CrewAI）を比較するときに読み込みます。
• langgraph — 討論プロトコルを超える複雑なステートマシン型のマルチエージェントオーケストレーション向け
• pydanticai — 型安全なエージェント定義を実現する基盤フレームワーク
• spec-driven-development — agent-council に評価を支援してもらう仕様の作成向け
• hermes-profiles — プロフィール選択システムを支える 39 件のプロフィールライブラリ