Team ガイド

チーム（Team）は、Leader Agentと複数のMember Agentが協調して動作する単位です。Leader Agentがチーム全体を統括し、Member Agentの応答を集約して最終結果を生成します。

目次

Teamとは
Agent Delegation
アーキテクチャ
チーム設定
mixseek team コマンド
集約処理
データ永続化
Round 2シミュレーション
プログラマティックな使用
トラブルシューティング
参考資料

Teamとは

Teamは以下のコンポーネントで構成されます：

Leader Agent（チーム管理者）

Leader Agentは、Pydantic AIのAgent Delegationパターンを使用して以下の責務を持つ調整者エージェントです：

タスク分析: LLMでユーザープロンプトを分析
動的Agent選択: 必要なMember AgentのみをToolで選択・実行（Agent Delegation）
応答集約: 選択されたMember Agentの応答を統合（TUMIX論文準拠）
構造化データ記録: MemberSubmissionsRecordとして記録（前ラウンド非依存）

Member Agent（専門家）

Member Agentは、単一の限定領域に特化した作業担当エージェントです：

システム標準型: plain、web-search、code-exec
ユーザー作成型: 独自の専門性を持つAgent
Tool登録: すべてLeader AgentのToolとして登録
動的実行: Leader AgentがAgent Delegationパターンで選択・実行

Agent Delegation

Agent Delegationは、Leader AgentがLLMでタスクを分析し、必要なMember Agentのみを動的に選択・実行するPydantic AIのパターンです。

Agent Delegation vs 全Agent並列実行

観点	Agent Delegation	全Agent並列実行
Member Agent選択	LLMが動的に選択	全て実行
リソース効率	高（必要なもののみ）	低（不要なAgentも実行）
柔軟性	高（タスクに応じて）	低（常に全て実行）
コスト	最小限	高い

Agent Delegationの仕組み

User Prompt
    ↓
Leader Agent（LLMが分析）
    ↓
必要なToolのみ選択・実行
    ├─→ Tool: delegate_to_analyst
    ├─→ Tool: delegate_to_summarizer
    └─→ （他のAgentはスキップ）
         ↓
選択されたMember Agentが実行され、結果を返す
    ↓
MemberSubmissionsRecord（構造化データ記録）

利点:

タスクに不要なAgentを実行しない
リソース（トークン、時間、コスト）を最小化
LLMがタスクの複雑度に応じて最適なAgentを選択

Tool動的登録

Member AgentはTOML設定から動的にToolとして登録されます：

# 各Member AgentがToolとして登録される
@leader_agent.tool
async def delegate_to_analyst(ctx: RunContext[TeamDependencies], task: str) -> str:
    """論理的な分析を実行します"""
    result = await analyst_agent.run(
        task,
        deps=ctx.deps,
        usage=ctx.usage  # 重要: Leader AgentのUsageに統合
    )
    return str(result.output)

Tool関数の __name__ と __doc__ が、LLMのTool選択時の判断材料になります。

アーキテクチャ

チーム構造（Agent Delegation）

ユーザープロンプト
    ↓
Leader Agent（調整者、LLM分析）
    ↓ Agent Delegation
    ├── Tool: delegate_to_analyst → Member Agent 1
    ├── Tool: delegate_to_web_search → Member Agent 2
    └── （不要なAgentはスキップ）
    ↓
MemberSubmissionsRecord（構造化データ）
    ↓
Round Controller（整形処理）
    ↓
Submission

責務分離

コンポーネント	責務
Leader Agent	単一ラウンド内のAgent選択と記録のみ
Round Controller	複数ラウンド間の統合・整形処理
Evaluator	評価スコア計算、Leader Board投入

チーム設定

設定ファイルの生成

チーム設定のテンプレートを生成できます：

# team.toml テンプレート生成（workspace/configs/team.toml に出力）
export MIXSEEK_WORKSPACE=/path/to/workspace
mixseek config init --component team

# または --workspace オプションで指定
mixseek config init --component team --workspace /path/to/workspace

環境変数による設定上書きも可能です：

# Leader Agentのタイムアウトを環境変数で上書き
export MIXSEEK_LEADER__TIMEOUT_SECONDS=600
mixseek team "タスク" --config team.toml

TOML設定構造

チーム全体の設定をTOMLファイルで定義します：

# team_config.toml

[team]
name = "Analysis Team"
description = "Multi-agent data analysis team"
team_id = "dev-team-001"  # オプション、未指定時は自動生成

# Leader Agent設定（Agent Delegation対応）
[team.leader]
model = "google-gla:gemini-2.5-flash-lite"
system_instruction = """
タスクを分析し、適切なMember Agentを選択してください:
- delegate_to_analyst: 論理的分析が必要な場合
- delegate_to_web_search: 最新情報が必要な場合
- delegate_to_code_exec: 計算やデータ分析が必要な場合

リソース効率のため、必要最小限のAgentのみ選択してください。
"""

# Member Agents定義
[[team.members]]
name = "analyst"
type = "plain"
tool_description = "論理的な分析を実行します"
model = "google-gla:gemini-2.5-flash-lite"
system_instruction = "You are a data analyst. Analyze data using logical reasoning."
temperature = 0.2

[[team.members]]
name = "web-researcher"
type = "web_search"
tool_description = "Web検索で最新情報を取得します"
model = "google-gla:gemini-2.5-flash"
system_instruction = "You are a web researcher. Search for current information."
temperature = 0.3

[[team.members]]
name = "calculator"
type = "code_execution"
tool_description = "Pythonコードで計算を実行します"
model = "anthropic:claude-sonnet-4-5"
system_instruction = "You are a calculator. Execute Python code for numerical computations."
temperature = 0.0

Member Agent配列

[[team.members]]で複数のMember Agentを定義します：

数は可変: 1～15個（上限はTOML設定で指定可能）
異なるタイプ: plain、web_search、code_execution を組み合わせ可能
独立した設定: 各Memberが個別のmodel、temperature、instructionsを持つ
Tool自動登録: 各Memberが delegate_to_<agent_name> として自動登録

Leader Agent System Prompt

Leader AgentのSystem Promptには、各Member AgentのTool説明（tool_description）が重要です。LLMはこれを参照してAgent選択を行います。

Member Agent TOML参照パターン（DRY原則）

Member Agent設定を個別のTOMLファイルで定義し、チーム設定から参照することができます。これにより、同じMember Agent設定を複数チームで再利用できます（DRY原則）。

Member Agent単体ファイルの作成

Member Agent設定ファイルは、$MIXSEEK_WORKSPACE 配下に配置することを推奨します：

# ワークスペース構造（推奨）
$MIXSEEK_WORKSPACE/
└── agents/
    ├── analyst.toml
    ├── researcher.toml
    └── summarizer.toml

# $MIXSEEK_WORKSPACE/agents/analyst.toml

[agent]
name = "analyst"
type = "plain"
model = "google-gla:gemini-2.5-flash-lite"
temperature = 0.2
max_tokens = 2048
description = "データ分析専門エージェント"

[agent.system_instruction]
text = """あなたはデータ分析の専門家です。
与えられた情報を論理的に分析し、構造化された洞察を提供してください。

分析手法:
- データの傾向分析
- パターン認識
- 統計的洞察
- 結論の導出"""

[agent.metadata]
version = "1.0.0"
author = "MixSeek-Core"
created = "2025-10-23"

チーム設定から参照

推奨: 環境変数を事前に設定します：

# ワークスペース設定（推奨）
export MIXSEEK_WORKSPACE=$HOME/mixseek-workspace

# team-with-references.toml

[team]
name = "Reference-based Team"
description = "Team using Member Agent TOML references"
team_id = "ref-team-001"

# Member Agent 1: 既存の analyst.toml を参照
[[team.members]]
config = "agents/analyst.toml"  # → $MIXSEEK_WORKSPACE/agents/analyst.toml

# Member Agent 2: 既存の researcher.toml を参照
[[team.members]]
config = "agents/researcher.toml"  # → $MIXSEEK_WORKSPACE/agents/researcher.toml

# Member Agent 3: インライン定義も可能（参照と混在可）
[[team.members]]
name = "summarizer"
type = "plain"
tool_description = "情報を簡潔にまとめます"
model = "google-gla:gemini-2.5-flash-lite"
system_instruction = "あなたはサマライザーです"
temperature = 0.3
max_tokens = 1024

使い方

# 環境変数設定（推奨、初回のみ）
export MIXSEEK_WORKSPACE=$HOME/mixseek-workspace

# チーム実行（Member Agent TOMLを参照）
mixseek team "市場調査を実施して" \
  --config team-with-references.toml

# Member Agent単体テスト
mixseek member "データを分析して" \
  --config $MIXSEEK_WORKSPACE/agents/analyst.toml

パス解釈ルール

config フィールドで指定されたパスは、以下の優先順位で解釈されます：

絶対パス: そのまま使用される

[[team.members]]
config = "/absolute/path/to/agent.toml"

相対パス + MIXSEEK_WORKSPACE 設定あり: 環境変数を起点に解釈

export MIXSEEK_WORKSPACE=$HOME/my-workspace

[[team.members]]
config = "agents/analyst.toml"  # → $MIXSEEK_WORKSPACE/agents/analyst.toml

相対パス + MIXSEEK_WORKSPACE 未設定: カレントディレクトリを起点に解釈（警告ログ出力）
```
[[team.members]]
config = "agents/analyst.toml"  # → ./agents/analyst.toml
```

推奨: MIXSEEK_WORKSPACE 環境変数を設定することで、ワークスペース起点でのパス解釈が明確になります。

# 環境変数設定（推奨）
export MIXSEEK_WORKSPACE=$HOME/mixseek-workspace

# ワークスペース構造
$MIXSEEK_WORKSPACE/
├── agents/
│   ├── analyst.toml
│   └── researcher.toml
└── teams/
    └── team.toml

利点

DRY原則: Member Agent設定を1箇所で管理
再利用性: 同じagent.tomlを複数チームで使用
一貫性: specs/027のMember Agent設定と統一
テスト容易性: Member Agent単体でテスト可能
ワークスペース管理: MIXSEEK_WORKSPACE 起点で統一的に管理

注意事項

config キーが存在する場合、既存TOMLファイルを読み込む
参照先ファイルが存在しない場合、エラー終了（フォールバック禁止、Article 9準拠）
相対パスの解決:
- MIXSEEK_WORKSPACE 設定時: 環境変数を起点に解決（推奨）
- MIXSEEK_WORKSPACE 未設定: カレントディレクトリを起点に解決（警告ログ出力）
config とインライン定義（agent_name 等）は混在可能

Member Agent の具体例

ここでは、実際のプロジェクトで使用できる Member Agent の具体的な設定例を紹介します。

Web Search Agent

最新情報を収集する Web Search Agent の設定例：

[[team.members]]
name = "web_search"
type = "web_search"
tool_description = "Web検索で最新情報を収集します。市場動向、技術トレンド、統計データなどリアルタイム情報が必要な場合に使用します。"
model = "google-gla:gemini-2.5-flash-lite"
temperature = 0.3
max_tokens = 6144  # Web検索は大量データを処理するため高めに設定

[team.members.system_instruction]
text = """あなたは Web 検索に特化した研究エージェントです。

専門能力:
- リアルタイム情報収集とWeb検索
- 複数ソースからの情報統合
- 信頼性の高い情報検証と評価
- 権威あるソースの優先的活用

検索戦略:
- 関連するキーワードと複数の検索角度を使用
- 公式ドキュメント、学術論文、信頼できるメディアを優先
- 複雑なトピックは段階的に調査
- 検索結果を批判的に評価し、信頼性を判断

情報処理:
- 検索結果の重要度に応じて優先順位付け
- 矛盾する情報については明確に指摘
- 情報の新しさと信頼性を常に評価
- 必要に応じて引用元を明示

日本語での自然な表現を使用し、最高品質の研究成果を提供してください。"""

[team.members.tool_settings.web_search]
max_results = 15           # 検索結果の最大数
timeout = 60               # 検索タイムアウト（秒）
include_raw_content = true # 生コンテンツを取得

用途: 市場調査、技術リサーチ、競合分析、最新ニュース収集

重要な設定:

max_tokens = 6144: Web検索結果は大量のテキストを返すため、高めに設定
temperature = 0.3: 正確性を重視する低温度設定
max_results = 15: 包括的な情報収集のため、多めの結果を取得

サポートされるモデル: Web Search Agent はすべてのモデルプロバイダーで利用可能です：

Google Gemini: model = "google-gla:gemini-2.5-flash-lite"
Anthropic Claude: model = "anthropic:claude-sonnet-4-5-20250929"
OpenAI: model = "openai:gpt-4o"

Logical Analyst Agent

論理的・構造的な分析を行う Agent の設定例：

[[team.members]]
name = "logical_analyst"
type = "plain"
tool_description = "論理的・構造的な分析を実行します。因果関係の整理、フレームワーク適用、データに基づいた結論導出が必要な場合に使用します。"
model = "google-gla:gemini-2.5-flash-lite"
temperature = 0.2
max_tokens = 4096

[team.members.system_instruction]
text = """あなたは論理的分析に特化したエージェントです。

専門能力:
- 構造的な問題分解と整理
- 因果関係の明確化
- 論理的フレームワークの適用
- エビデンスベースの結論導出

分析手法:
1. 問題の定義と範囲の明確化
2. 重要なファクター・変数の抽出
3. ファクター間の関係性分析
4. 論理的推論と仮説検証
5. 包括的な結論と提言

思考プロセス:
- 段階的で追跡可能な推論
- 根拠とデータに基づいた主張
- 前提条件と制約の明示
- 矛盾や課題の率直な指摘

回答スタイル:
- 明確で構造的な説明
- 図表や箇条書きを活用
- 曖昧な表現を避ける
- アクションにつながる提言

日本語で論理的に整理された分析を提供してください。"""

用途: 戦略立案、リスク分析、意思決定支援、ビジネス分析

重要な設定:

temperature = 0.2: 決定的で一貫性のある分析のため、極めて低い温度
type = "plain": 外部ツールを使わない純粋な LLM 分析

Data Analyst Agent

数値データ分析を行う Agent の設定例：

[[team.members]]
name = "data_analyst"
type = "plain"
tool_description = "数値データの分析、統計的検証、データドリブンな洞察を提供します。定量的な裏付け、トレンド分析、データに基づいた予測が必要な場合に使用します。"
model = "google-gla:gemini-2.5-flash-lite"
temperature = 0.4
max_tokens = 4096

[team.members.system_instruction]
text = """あなたはデータ分析に特化したエージェントです。

専門能力:
- 数値データの分析と解釈
- 統計的手法の適用
- データからのパターン発見
- 定量的な洞察の提供
- データドリブンな予測

分析手法:
1. データの構造と特性の理解
2. 適切な分析手法の選択
3. 統計的指標の計算と解釈
4. トレンドやパターンの抽出
5. データに基づいた洞察と提言

思考プロセス:
- 数値的根拠に基づいた分析
- 適切な可視化と説明
- 統計的な有意性の評価
- 限界や前提条件の明示
- 実務的な解釈と応用

回答スタイル:
- 明確で分かりやすい数値の説明
- データの意味を実務的に解釈
- アクションにつながる洞察を提供
- 専門用語は適切に説明

日本語でデータに基づいた客観的な分析を提供してください。"""

用途: 数値データ分析、統計的検証、トレンド分析、予測モデル構築

重要な設定:

temperature = 0.4: 正確性と柔軟性のバランスを取った中程度の温度
type = "plain": 数値データの解釈に特化

複数 Agent の組み合わせ例

実践的なチーム構成では、複数の Member Agent を組み合わせます：

Research Team（研究重視）

[team]
team_id = "team-research"
team_name = "Research Team"

[team.leader]
temperature = 0.3
system_instruction = """
タスクを分析し、適切な Member Agent に委譲してください:
- delegate_to_web_search: 最新情報が必要な場合
- delegate_to_logical_analyst: 論理的分析が必要な場合
"""

[[team.members]]
# Web Search Agent の設定（上記参照）

[[team.members]]
# Logical Analyst Agent の設定（上記参照）

用途: 信頼性の高いリサーチと論理的分析が必要なタスク

Balanced Team（バランス型）

[team]
team_id = "team-balanced"
team_name = "Balanced Team"

[team.leader]
temperature = 0.5
system_instruction = """
タスクを分析し、適切な Member Agent に委譲してください:
- delegate_to_web_search: 最新情報収集
- delegate_to_logical_analyst: 論理的整理・構造化
- delegate_to_data_analyst: 数値分析・統計的検証
"""

[[team.members]]
# Web Search Agent の設定

[[team.members]]
# Logical Analyst Agent の設定

[[team.members]]
# Data Analyst Agent の設定

用途: 多角的な視点と包括的な分析が必要な複雑なタスク

Member Agent 設定のベストプラクティス

tool_description の重要性
- Leader Agent が Agent 選択時に参照する唯一の情報
- 明確で具体的な説明を記載
- 「いつ使うべきか」を明示
temperature 設定の指針
- 正確性重視: 0.2-0.3（Logical Analyst, Web Search）
- バランス型: 0.4-0.5（Data Analyst）
- 創造性重視: 0.7-0.8（Creative tasks）
max_tokens の設定
- Web Search: 6144（大量データ処理）
- その他の Agent: 4096（標準的な分析）
system_instruction の構造
- 専門能力の明示
- 具体的な手法の説明
- 思考プロセスの定義
- 回答スタイルの指定

詳細な設定例は examples/orchestrator-sample/configs/agents/ を参照してください。

mixseek team コマンド

概要

mixseek teamは、Leader Agentの機能を開発・テスト環境で検証するためのCLIコマンドです。

⚠️ 重要: このコマンドは開発・テスト専用です。本番環境ではOrchestration Layerを使用してください。

基本的な使い方

mixseek team <prompt> --config <team.toml>

必須引数

<prompt>: チーム全体に送信するユーザープロンプト

必須オプション

--config PATH: チーム設定TOMLファイルパス

オプション

--output-format FORMAT, -f: 出力形式（json、text）[default: text]
--save-db: DuckDBに保存（デバッグ用）
--evaluate: Leader Agentの最終応答を評価
--workspace PATH: 評価器設定ファイルの場所（デフォルト: $MIXSEEK_WORKSPACE または cwd）
--evaluate-config PATH, -e: カスタム評価設定ファイル（--workspace より優先）
--logfire: Logfire observability有効化（fullモード）
--logfire-metadata: Logfire有効化（metadataモード）
--logfire-http: Logfire有効化（httpモード）
--verbose: 詳細出力
--timeout SECONDS: 実行タイムアウト [default: 60]

Logfireオプション詳細:

--logfire: すべてキャプチャ（開発推奨、fullモード）
--logfire-metadata: メトリクスのみ（本番推奨）
--logfire-http: full + HTTPリクエスト/レスポンスキャプチャ（デバッグ）

詳細は Observability を参照してください。

使用例

環境変数の設定（推奨）

Member Agent参照パスを使用する場合、MIXSEEK_WORKSPACE を事前に設定することを推奨します：

# ワークスペースディレクトリを設定
export MIXSEEK_WORKSPACE=$HOME/mixseek-workspace

# ワークスペース初期化（初回のみ）
mixseek init

基本的な実行（Agent Delegation動作確認）

# チーム設定を指定して実行
mixseek team "Pythonの特徴を分析し、3つのポイントにまとめてください" \
  --config examples/team-example.toml \
  --verbose

出力例（structured形式、Agent Delegation動作）:

⚠️  WARNING: This is a development/testing command only.
⚠️  For production use, use Orchestration Layer instead.

Agent Delegation Results:
========================================
Team: Analysis Team
Selected Member Agents: 2/3  ← Agent Delegationで2つのみ選択
  ✓ analyst (plain) - 4523 input, 1876 output tokens
  ✓ web-researcher (web_search) - 5012 input, 2134 output tokens
  - calculator (code_execution) - SKIPPED  ← 不要なAgentはスキップ

Total Usage:
  Input tokens: 9535
  Output tokens: 4010
  Requests: 2  ← 2つのAgentのみ実行
  Estimated cost: $0.0142

MemberSubmissionsRecord:
========================================
## analyst の応答:

Pythonの主な特徴を分析すると...

---

## web-researcher の応答:

最新のPythonトレンドについて...

JSON出力

# JSON形式で出力（自動化スクリプト用）
mixseek team "データを分析して" \
  --config team.toml \
  --output-format json

出力例:

{
  "warning": "Development/testing command only",
  "team_name": "Analysis Team",
  "team_id": "dev-team-001",
  "round_number": 1,
  "total_count": 3,
  "selected_count": 2,
  "success_count": 2,
  "failure_count": 0,
  "submissions": [
    {
      "agent_name": "analyst",
      "agent_type": "plain",
      "content": "分析結果...",
      "status": "SUCCESS",
      "usage": {...}
    },
    {
      "agent_name": "web-researcher",
      "agent_type": "web_search",
      "content": "検索結果...",
      "status": "SUCCESS",
      "usage": {...}
    }
  ],
  "total_usage": {
    "input_tokens": 9535,
    "output_tokens": 4010,
    "requests": 2
  }
}

データベース保存（デバッグ用）

# DuckDBに保存してデバッグ
export MIXSEEK_WORKSPACE=/path/to/workspace

mixseek team "テストプロンプト" \
  --config team.toml \
  --save-db \
  --verbose

保存されるデータ:

Message History: Pydantic AI形式で保存
MemberSubmissionsRecord: 構造化データをJSON型で保存
Leader Board: 評価スコア、フィードバック（Orchestration Layer使用時）

Leader Agent応答の評価

--evaluate オプションを使用して、Leader Agentの最終応答を自動評価できます。

# 基本的な評価
mixseek team "最新のAI技術トレンドを調査・分析してまとめてください" \
  --config $MIXSEEK_WORKSPACE/configs/team-inline-agents.toml \
  --evaluate

カスタム評価設定を使用する場合：

# チームごとに異なる評価基準を適用
mixseek team "Your task" \
  --config team.toml \
  --evaluate \
  --config $MIXSEEK_WORKSPACE/configs/evaluator.toml

評価結果は、チーム実行結果の後に表示されます：

=== Evaluation Results ===
Overall Score: 85.67

Metric Scores:
  clarity_coherence: 88.0
    Comment: 回答は明確で一貫性があります...
  coverage: 85.0
    Comment: 主要なポイントを包括的にカバーしています...
  relevance: 84.0
    Comment: ユーザーの質問に適切に答えています...

評価コメントの表示:

デフォルト: 500文字まで表示
--verbose: 全文表示

評価失敗時の動作:

評価が失敗しても、チーム実行結果は正常に表示されます
評価失敗は警告として表示され、exit code には影響しません

独立した評価の実行:

Leader Agentの応答を後から評価することもできます。

mixseek evaluate "質問" "Leader Agentの応答テキスト"

詳細は Evaluator仕様を参照してください。

集約処理（aggregated_content）

Member応答の統合

Leader Agentは、Agent Delegationで選択されたMember Agentの応答を以下の形式で記録します：

## <agent_name> の応答:

<応答内容>

---

## <agent_name> の応答:

<応答内容>

注意: 選択されなかったMember Agentの応答は含まれません（Agent Delegationによるリソース効率化）。

自動エラー除外

失敗したMember Agent（タイムアウト、API エラー等）の応答は自動的に除外されます：

3 Member Agent定義:
  ✓ analyst: 成功（Agent Delegationで選択）
  ✓ web-researcher: 成功（Agent Delegationで選択）
  - slow-agent: タイムアウト

MemberSubmissionsRecord:
  → analystとweb-researcherの2応答のみ含む
  → slow-agentは除外

データ永続化

DuckDB並列書き込み

Leader Agentは、DuckDBのMVCC（Multi-Version Concurrency Control）により、複数チームの並列実行時もロック競合なしでデータを保存します：

複数チーム並列実行:
  Team 1 → Leader Agent → DuckDB保存（スナップショット1）
  Team 2 → Leader Agent → DuckDB保存（スナップショット2）
  Team 3 → Leader Agent → DuckDB保存（スナップショット3）
  ↓ ロック待機なし（MVCC）

保存されるデータ

round_historyテーブル

team_id, team_name, round_number
message_history: Pydantic AI Message HistoryをJSON型で保存
submissions_record: MemberSubmissionsRecordをJSON型で保存

leader_boardテーブル

team_id, team_name, round_number
evaluation_score: 評価スコア（0.0-1.0）
submission_content: 集約済みコンテンツ
usage_info: リソース使用量（JSON型）

asyncio.to_thread戦略

DuckDBは同期APIのみのため、asyncio.to_threadでスレッドプールに退避して真の並列実行を実現：

# 内部実装（参考）
async def save_aggregation(self, record, message_history):
    """非同期保存"""
    await asyncio.to_thread(
        self._save_sync,  # 同期版メソッド
        record,
        message_history
    )

スレッドローカルコネクション

各チームが独立したDuckDBコネクションを使用：

# 内部実装（参考）
self._local = threading.local()

def _get_connection(self):
    if not hasattr(self._local, 'conn'):
        self._local.conn = duckdb.connect(self.db_path)
    return self._local.conn

プログラマティックな使用

Python APIでのLeader Agent使用

from mixseek.agents.leader import create_leader_agent, load_team_config, TeamDependencies
from mixseek.storage.aggregation_store import AggregationStore
from pathlib import Path

# TOML読み込み
team_config = load_team_config(Path("team.toml"))

# Member Agents作成（省略）
member_agents = {...}

# Leader Agent作成（Agent Delegation対応）
leader_agent = create_leader_agent(team_config, member_agents)

# 依存関係初期化
deps = TeamDependencies(
    team_id=team_config.team.team_id,
    team_name=team_config.team.name,
    round_number=1
)

# Leader Agent実行（Agent Delegationでタスク分析）
result = await leader_agent.run("市場調査を実施して", deps=deps)

# 構造化データ記録（MemberSubmissionsRecord）
record = MemberSubmissionsRecord(
    team_id=deps.team_id,
    team_name=deps.team_name,
    round_number=deps.round_number,
    submissions=deps.submissions  # Agent Delegationで記録された応答
)

# DuckDB保存（開発・テスト用）
store = AggregationStore()
messages = result.all_messages()
await store.save_aggregation(record, messages)

# 結果確認
print(f"Selected Agents: {len(deps.submissions)}/{len(team_config.members)}")
for submission in deps.submissions:
    print(f"  {submission.agent_name}: {submission.status}")

Leader Board取得

import pandas as pd

# ランキング取得
leaderboard_df = await store.get_leader_board(limit=10)

# チーム統計取得
stats = await store.get_team_statistics("team-001")
print(f"Average score: {stats['avg_score']}")
print(f"Total tokens: {stats['total_input_tokens']}")

トラブルシューティング

Member Agent config ファイルが見つからない

症状:

FileNotFoundError: Referenced agent config not found: /path/to/workspace/agents/analyst.toml
Workspace: /path/to/workspace
Original path: agents/analyst.toml

原因:

相対パスが正しくない
MIXSEEK_WORKSPACE が正しく設定されていない
Member Agent TOMLファイルが存在しない

解決方法:

# 1. MIXSEEK_WORKSPACEを確認
echo $MIXSEEK_WORKSPACE

# 2. ファイルの存在確認
ls -la $MIXSEEK_WORKSPACE/agents/analyst.toml

# 3. 環境変数が未設定の場合は設定
export MIXSEEK_WORKSPACE=$HOME/mixseek-workspace

# 4. ファイルが存在しない場合は作成
mkdir -p $MIXSEEK_WORKSPACE/agents
# analyst.toml を作成...

パス解釈の確認:

相対パス agents/analyst.toml の場合、$MIXSEEK_WORKSPACE/agents/analyst.toml として解釈されます
絶対パス /abs/path/agent.toml の場合、そのまま使用されます
MIXSEEK_WORKSPACE 未設定の場合、カレントディレクトリ起点で解釈されます（警告ログ出力）

環境変数未設定エラー

症状:

ERROR: MIXSEEK_WORKSPACE environment variable is not set.

解決方法:

export MIXSEEK_WORKSPACE=/path/to/workspace
mixseek init  # ワークスペース初期化

全Member Agent失敗

症状:

ERROR: All 3 Member Agents failed. Team disqualified.

原因:

Member Agentのタイムアウト
API認証エラー
設定不正

解決方法:

# 詳細ログで原因確認
mixseek team "prompt" --config team.toml --verbose

# タイムアウト延長
mixseek team "prompt" --config team.toml --timeout 120

Member Agent設定エラー

症状:

Error: No member agents defined in team configuration

解決方法: [[team.members]]セクションを確認

# 最低1つのMember Agentが必要
[[team.members]]
name = "agent-1"
type = "plain"
tool_description = "一般的なタスクを実行します"
model = "google-gla:gemini-2.5-flash-lite"
system_instruction = "You are a helpful agent"

Agent Delegationで全Agentスキップ

症状:

Selected Member Agents: 0/3
ERROR: No Member Agents were selected by Leader Agent

原因:

Leader AgentのSystem Promptが不適切
Tool descriptionが不明確
タスクとMember Agentの専門性が不一致

解決方法:

[team.leader]
system_instruction = """
タスクを分析し、適切なMember Agentを選択してください。
各Agentの説明を参照し、タスクに必要なAgentを必ず1つ以上選択してください。

- delegate_to_<agent_name>: [明確な説明]
"""

[[team.members]]
tool_description = "具体的で明確な説明（LLMが判断しやすいように）"

Invalid –load-from-db format

症状:

ERROR: Invalid --load-from-db format: team-001
Expected format: team-id:round (e.g., team-001:1)

解決方法: コロン（:）でteam_idとround番号を区切る

--load-from-db team-001:1  # 正しい形式

Previous round not found in database

症状:

ERROR: Previous round not found in database
Team ID: team-001
Round: 1

解決方法:

team_idが正しいか確認:

duckdb -c "SELECT DISTINCT team_id FROM round_history;" $MIXSEEK_WORKSPACE/mixseek.db

round番号が正しいか確認:

duckdb -c "SELECT team_id, round_number FROM round_history WHERE team_id='team-001';" $MIXSEEK_WORKSPACE/mixseek.db

参考資料

仕様書

Leader Agent仕様 - 機能要件、成功基準
データモデル - MemberSubmission、MemberSubmissionsRecord
API契約 - AggregationStore仕様
クイックスタート - 最速セットアップ

実装知見

Pydantic AI + DuckDB統合 - 10の技術的知見

オーケストレーションとの違い

Team実行 vs Orchestrator実行

MixSeek-Coreでは、単一チーム実行（本ガイド）と複数チーム並列実行（Orchestrator）の2つの実行モードがあります。

観点	Team実行 (`mixseek team`)	Orchestrator実行 (`mixseek exec`)
実行単位	単一チーム	複数チーム並列
設定ファイル	team.toml	orchestrator.toml + 複数のteam.toml
結果	1つのSubmission	最高スコアのSubmission + ランキング
評価	1チームの評価	全チームの評価とランキング
DuckDB記録	round_history + leader_board	全チームのround_history + leader_board
用途	チーム開発・デバッグ	複数チームの競争的実行

いつどちらを使うか

Team実行を使う場合:

単一チームの動作確認
チーム設定のテスト
Member Agentの追加・削除テスト
開発・デバッグ

Orchestrator実行を使う場合:

複数チームの競争的評価
最高品質のSubmissionを選択
本番環境での実行
A/Bテスト

実行例の比較

Team実行:

# 単一チーム実行
mixseek team "最新のAI技術トレンドを調査してください" \
  --config team.toml

# 結果: 1つのSubmission + 評価

Orchestrator実行:

# 複数チーム並列実行
mixseek exec "最新のAI技術トレンドを調査してください" \
  --config orchestrator.toml

# 結果: ランキング + 最高スコアのSubmission

詳細は Orchestratorガイドを参照してください。

外部リソース

TUMIX論文: https://arxiv.org/html/2510.01279v1
Pydantic AI: https://ai.pydantic.dev/
DuckDB: https://duckdb.org/

Team ガイド

目次

Teamとは

Leader Agent（チーム管理者）

Member Agent（専門家）

Agent Delegation

Agent Delegation vs 全Agent並列実行

Agent Delegationの仕組み

Tool動的登録

アーキテクチャ

チーム構造（Agent Delegation）

責務分離

チーム設定

設定ファイルの生成

TOML設定構造

Member Agent配列

Leader Agent System Prompt

Member Agent TOML参照パターン（DRY原則）

Member Agent単体ファイルの作成

チーム設定から参照

使い方

パス解釈ルール

利点

注意事項

Member Agent の具体例

Web Search Agent

Logical Analyst Agent

Data Analyst Agent

複数 Agent の組み合わせ例

Research Team（研究重視）

Balanced Team（バランス型）

Member Agent 設定のベストプラクティス

mixseek team コマンド

概要

基本的な使い方

必須引数

必須オプション

オプション

使用例

環境変数の設定（推奨）

基本的な実行（Agent Delegation動作確認）

JSON出力

データベース保存（デバッグ用）

Leader Agent応答の評価

集約処理（aggregated_content）

Member応答の統合

自動エラー除外

データ永続化

DuckDB並列書き込み

保存されるデータ

round_historyテーブル

leader_boardテーブル

asyncio.to_thread戦略

スレッドローカルコネクション

プログラマティックな使用

Python APIでのLeader Agent使用

Leader Board取得

トラブルシューティング

Member Agent config ファイルが見つからない

環境変数未設定エラー

全Member Agent失敗

Member Agent設定エラー

Agent Delegationで全Agentスキップ

Invalid –load-from-db format

Previous round not found in database

参考資料

仕様書

実装知見

関連ドキュメント

オーケストレーションとの違い

Team実行 vs Orchestrator実行

いつどちらを使うか

実行例の比較

外部リソース