テンプレート

概要

Shannonのテンプレートシステムは、決定論的でゼロトークンのワークフローを一般的なパターンに対して可能にします。テンプレートは、AIの分解なしに実行されるYAMLで構造化されたワークフローを定義し、繰り返し可能なタスクに対して大幅なコスト削減を提供します。

ゼロトークンコスト

テンプレートはワークフローのルーティングにLLM呼び出しをバイパスします

決定論的実行

予測可能で繰り返し可能なワークフローの動作

予算管理

ノードごとのトークン制限と自動的な劣化

DAGサポート

依存関係管理を伴う並列実行

テンプレートを使用するタイミング

テンプレートを使用する場合:

ワークフローが既知の構造で繰り返し可能な場合
分解トークンコストを排除したい場合
予測可能な実行順序が必要な場合
ワークフローの各ステージで予算管理が必要な場合

AI分解を使用する場合:

タスクの構造が不明または変動する場合
ワークフロー設計に関する複雑な推論が必要な場合
一回限りまたは非常に動的なタスク

テンプレート構造

テンプレートは次の構造のYAMLファイルです：

name: "workflow_name"
version: "1.0.0"
description: "このワークフローの機能"

defaults:
  model_tier: "medium"        # small | medium | large
  budget_agent_max: 6000      # 総トークン予算
  require_approval: false     # 人間の承認ゲート

nodes:
  - id: "step_1"
    type: "simple"            # ノードタイプ
    strategy: "react"         # 実行戦略
    tools_allowlist:          # 許可されたツール
      - "web_search"
    budget_max: 1500          # ノードごとのトークン制限
    depends_on: []            # 依存関係

  - id: "step_2"
    type: "cognitive"
    strategy: "chain_of_thought"
    budget_max: 2000
    depends_on: ["step_1"]

edges:
  - from: "step_1"
    to: "step_2"

コアフィールド

フィールド	タイプ	必須	説明
`name`	string	はい	ユニークなワークフロー識別子
`version`	string	はい	セマンティックバージョン（例: “1.0.0”）
`description`	string	いいえ	人間が読める説明
`defaults`	object	いいえ	すべてのノードのグローバル設定
`nodes`	array	はい	ワークフロー実行ユニット
`edges`	array	いいえ	明示的な依存関係接続

デフォルト設定

defaults:
  model_tier: "medium"        # すべてのノードのモデルサイズ
  budget_agent_max: 6000      # 総ワークフロートークン予算
  require_approval: false     # 実行前に人間の承認が必要

ノードタイプ

Shannonは、異なる実行パターンのために4つのノードタイプをサポートしています。

シンプルノード

単一タスクの実行と直接ツールの呼び出し。

- id: "fetch_data"
  type: "simple"
  strategy: "react"
  tools_allowlist:
    - "web_search"
  budget_max: 1000
  depends_on: []

使用例: データ取得、シンプルな変換、ツールベースの操作。

コグニティブノード

複雑な推論と多段階の分析。

- id: "analyze"
  type: "cognitive"
  strategy: "chain_of_thought"
  budget_max: 2500
  depends_on: ["fetch_data"]
  degrade_to: "react"         # 予算超過時のフォールバック
  retries: 1

使用例: 分析、推論、合成タスク。

DAGノード

内部タスク依存関係を持つ並列実行。

- id: "parallel_analysis"
  type: "dag"
  budget_max: 5000
  depends_on: ["understand"]
  metadata:
    tasks:
      - id: "collect"
        tools_allowlist: ["web_search"]
        depends_on: []
      - id: "quantitative"
        tools_allowlist: ["calculator"]
        depends_on: ["collect"]
      - id: "qualitative"
        tools_allowlist: []
        depends_on: ["collect"]
      - id: "cross_validate"
        depends_on: ["quantitative", "qualitative"]

使用例: 並列処理、ファンアウト/ファンインパターン。

スーパーバイザーノード

階層的なタスク分解と調整。

- id: "orchestrate"
  type: "supervisor"
  strategy: "reflection"
  budget_max: 3000
  depends_on: ["parallel_analysis"]

使用例: 結果の集約、品質管理、合成。

実行戦略

戦略はノードがタスクを処理する方法を定義します：

戦略	トークン範囲	説明
`react`	~500-1500	ツールベースの推論とアクションサイクル
`chain_of_thought`	~1500-3000	順次のステップバイステップの推論
`tree_of_thoughts`	~3000-8000	複数の推論ブランチを探る
`reflection`	~1000-2000	自己評価と洗練
`debate`	~2000-4000	多角的な分析

自動劣化

予算制約に達した場合、戦略は自動的に劣化します：

tree_of_thoughts → chain_of_thought → react

明示的な劣化を設定：

- id: "explore"
  type: "cognitive"
  strategy: "tree_of_thoughts"
  budget_max: 2500
  degrade_to: "chain_of_thought"  # フォールバック戦略
  retries: 1                       # 劣化時の再試行回数

テンプレートの作成

テンプレートファイルの作成

config/workflows/examples/ またはカスタムディレクトリに YAML ファイルを作成します:

# config/workflows/examples/my_workflow.yaml
name: "my_workflow"
version: "1.0.0"
description: "カスタム分析ワークフロー"

defaults:
  model_tier: "medium"
  budget_agent_max: 5000
  require_approval: false

nodes:
  - id: "intake"
    type: "simple"
    strategy: "react"
    tools_allowlist:
      - "web_search"
    budget_max: 1500
    depends_on: []

  - id: "analyze"
    type: "cognitive"
    strategy: "chain_of_thought"
    budget_max: 2000
    depends_on: ["intake"]

  - id: "synthesize"
    type: "cognitive"
    strategy: "reflection"
    budget_max: 1500
    depends_on: ["analyze"]

edges:
  - from: "intake"
    to: "analyze"
  - from: "analyze"
    to: "synthesize"

テンプレートディレクトリの登録

テンプレートは InitTemplateRegistry を介して起動時に読み込まれます:

// オーケストレーターの初期化時
registry := templates.InitTemplateRegistry(
    "./config/workflows/builtin",
    "./config/workflows/examples",  // あなたのテンプレート
)

// すべてのテンプレートを検証
if err := registry.Finalize(); err != nil {
    log.Fatal(err)
}

サービスの再起動

docker compose -f deploy/compose/docker-compose.yml up -d --force-recreate orchestrator

利用可能なテンプレートの一覧表示

gRPC を介して:

grpcurl -plaintext -d '{}' localhost:50052 \
  shannon.orchestrator.OrchestratorService/ListTemplates

テンプレートの使用

HTTP Gateway 経由

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "現在のAI市場のトレンドを分析する",
    "context": {
      "template": "my_workflow",
      "template_version": "1.0.0"
    }
  }'

gRPC 経由

grpcurl -plaintext -d '{
  "query": "現在のAI市場のトレンドを分析する",
  "context": {
    "template": "my_workflow",
    "template_version": "1.0.0",
    "disable_ai": true
  }
}' localhost:50052 shannon.orchestrator.OrchestratorService/SubmitTask

disable_ai: true を設定すると、AI フォールバックなしでテンプレートのみの実行が強制されます。

Python SDK 経由

from shannon import ShannonClient

client = ShannonClient(base_url="http://localhost:8080")
handle = client.submit_task(
    "現在のAI市場のトレンドを分析する",
    context={
        "template": "my_workflow",
        "template_version": "1.0.0",
    },
)
result = client.wait(handle.task_id)
print(result.result)

テンプレートの例

シンプルな分析ワークフロー

迅速な要約のための二段階パイプライン:

name: "simple_analysis"
version: "1.0.0"
description: "短いブリーフのための迅速な要約ワークフロー"

defaults:
  model_tier: "medium"
  budget_agent_max: 3000
  require_approval: false

nodes:
  - id: "intake"
    type: "simple"
    strategy: "react"
    budget_max: 1000
    depends_on: []

  - id: "summarize"
    type: "cognitive"
    strategy: "chain_of_thought"
    budget_max: 1200
    depends_on: ["intake"]

edges:
  - from: "intake"
    to: "summarize"

研究要約ワークフロー

進行的な推論を伴う四段階の研究パイプライン:

name: "research_summary"
version: "1.0.0"
description: "マルチステージの研究ワークフロー"

defaults:
  model_tier: "medium"
  budget_agent_max: 6000
  require_approval: false

nodes:
  - id: "discover"
    type: "simple"
    strategy: "react"
    tools_allowlist:
      - "web_search"
    budget_max: 1500
    depends_on: []

  - id: "reason"
    type: "cognitive"
    strategy: "chain_of_thought"
    budget_max: 1500
    depends_on: ["discover"]

  - id: "explore"
    type: "cognitive"
    strategy: "tree_of_thoughts"
    budget_max: 2500
    degrade_to: "chain_of_thought"
    retries: 1
    depends_on: ["reason"]

  - id: "finalize"
    type: "cognitive"
    strategy: "reflection"
    budget_max: 1000
    depends_on: ["explore"]

edges:
  - from: "discover"
    to: "reason"
  - from: "reason"
    to: "explore"
  - from: "explore"
    to: "finalize"

並列 DAG ワークフロー

並列実行ブランチを持つ複雑なワークフロー:

name: "parallel_analysis"
version: "1.0.0"
description: "収束を伴う並列分析"

defaults:
  model_tier: "medium"
  budget_agent_max: 8000
  require_approval: false

nodes:
  - id: "understand"
    type: "simple"
    strategy: "react"
    budget_max: 1000
    depends_on: []

  - id: "parallel_analysis"
    type: "dag"
    budget_max: 5000
    depends_on: ["understand"]
    metadata:
      tasks:
        - id: "collect"
          tools_allowlist: ["web_search"]
          depends_on: []
        - id: "quantitative"
          tools_allowlist: ["calculator"]
          depends_on: ["collect"]
        - id: "qualitative"
          tools_allowlist: []
          depends_on: ["collect"]
        - id: "cross_validate"
          depends_on: ["quantitative", "qualitative"]

  - id: "report"
    type: "cognitive"
    strategy: "reflection"
    budget_max: 2000
    degrade_to: "chain_of_thought"
    depends_on: ["parallel_analysis"]

edges:
  - from: "understand"
    to: "parallel_analysis"
  - from: "parallel_analysis"
    to: "report"

テンプレートの継承

テンプレートは extends を使用して親テンプレートから継承できます。

# base_research.yaml
name: "base_research"
version: "1.0.0"

defaults:
  model_tier: "medium"
  budget_agent_max: 5000
  require_approval: false

# advanced_research.yaml
name: "advanced_research"
version: "1.0.0"
extends: ["base_research"]    # すべてのデフォルトを継承

defaults:
  budget_agent_max: 10000     # 特定の値をオーバーライド

nodes:
  # ... 追加のノード

複数の親が順番に適用され、派生テンプレートの値が優先されます。

バリデーション

テンプレートはロード時に以下の項目が検証されます。

YAML構文の正しさ
必須フィールドの存在
DAGの非循環性（循環依存がないこと）
予算階層（ノードの予算 ≤ エージェントの予算）
ツールレジストリの存在
変数参照の解決

registry := templates.InitTemplateRegistry("./templates")

// すべてのテンプレートを検証
if err := registry.Finalize(); err != nil {
    log.Fatalf("テンプレートの検証に失敗しました: %v", err)
}

ベストプラクティス

ノードは小さく集中させる

各ノードは一つのことをうまく行うべきです：

# 良い: 集中したノード
- id: "search"
  type: "simple"
  strategy: "react"
  tools_allowlist: ["web_search"]

- id: "analyze"
  type: "cognitive"
  strategy: "chain_of_thought"

ツールを明示的に許可リストに追加する

セキュリティと予測可能性のためにノードごとにツールを制限します：

# 良い: 明示的な許可リスト
tools_allowlist:
  - "web_search"
  - "calculator"

# 悪い: すべてのツールを許可
# tools_allowlist: ["*"]

予算の劣化を使用する

コスト管理のためにフォールバック戦略を設定します：

- id: "explore"
  strategy: "tree_of_thoughts"
  budget_max: 2500
  degrade_to: "chain_of_thought"
  retries: 1

共通パターンのために継承を使用する

共有デフォルトをベーステンプレートに抽出します：

extends: ["base_research"]
defaults:
  budget_agent_max: 8000  # 変更するものだけをオーバーライド

テンプレートにバージョンを付ける

セマンティックバージョニングを使用し、リクエストにバージョンを指定します：

name: "my_workflow"
version: "1.0.0"  # 破壊的変更時にインクリメント

{
  "context": {
    "template": "my_workflow",
    "template_version": "1.0.0"
  }
}

トラブルシューティング

テンプレートが見つからない

症状: template 'my_workflow' not found解決策:

登録されたディレクトリにテンプレートファイルが存在するか確認
YAML構文を検証: yamllint config/workflows/examples/my_workflow.yaml
オーケストレーターを再起動してテンプレートを再読み込み
オーケストレーターのログでロードエラーを確認

バリデーションエラー

症状: Template validation failed: circular dependency解決策:

depends_on フィールドにサイクルがないか確認
DAGノードが非循環のタスク依存関係を持つことを確認
edges がループを作成していないか確認

予算超過

症状: ノードの実行が早期に停止するか、予期せず劣化する解決策:

影響を受けるノードの budget_max を増加
優雅なフォールバックのために degrade_to を設定
総予算とノード予算の合計を確認

ツールが利用できない

症状: tool 'my_tool' not registered解決策:

ツールがツールレジストリに登録されているか確認
tools_allowlist でツール名のスペルを確認
LLMサービスがツールをロードしていることを確認

合成テンプレート

合成テンプレートは、すべてのエージェントが作業を完了した後に Shannon が最終出力をどのようにフォーマットするかを制御します。これらの Go テンプレートは config/templates/synthesis/ ディレクトリに配置され、結果を返す前に Orchestrator によってレンダリングされます。

利用可能なテンプレート

テンプレート	用途
`normal_default.tmpl`	非研究タスクのデフォルト
`research_comprehensive.tmpl`	詳細な研究レポート
`research_concise.tmpl`	簡潔な研究サマリー
`research_with_facts.tmpl`	事実に基づく引用付き研究
`domain_analysis_digest.tmpl`	ドメイン分析フォーマット
`swarm_default.tmpl`	Swarm マルチエージェント出力
`test_bullet_summary.tmpl`	箇条書きテスト形式

基本コントラクト

すべての合成テンプレートは _base.tmpl から動作ルールを継承します：

引用の処理

CitationAgent が有効な場合：合成内容にインライン [n] 引用を含めない — Citation Agent が別途追加します
CitationAgent が無効な場合：AvailableCitations リストに一致するインライン [n] を使用

時間的参照

CurrentDate フィールドがすべてのテンプレートに注入され、時効性のあるコンテンツで「現時点で」という表現が可能になります。

構造化アーティファクト

テンプレートは構造化されたアーティファクト（テーブル、コードブロック、JSON）を保持する必要があります — 散文に平坦化してはいけません。

ソースセクション

テンプレートに「ソース」セクションを含めてはいけません。システムがソース引用を自動的に追加します。

テンプレートデータ

すべての合成テンプレートは、以下のフィールドを持つ SynthesisTemplateData 構造体を受け取ります：

type SynthesisTemplateData struct {
    Query                string   // 元のユーザークエリ
    QueryLanguage        string   // 検出された言語（例: "en"、"ja"）
    ResearchAreas        []string // エージェントが調査したトピック
    AvailableCitations   string   // フォーマットされた引用リスト
    CitationCount        int      // 利用可能な引用の総数
    MinCitations         int      // 含めるべき最小引用数
    LanguageInstruction  string   // 出力言語の指示
    AgentResults         string   // 統合されたエージェント出力
    TargetWords          int      // 目標ワード数
    IsResearch           bool     // 研究タイプのタスクかどうか
    SynthesisStyle       string   // 選択された合成スタイル
    CitationAgentEnabled bool     // Citation Agent がアクティブかどうか
    CurrentDate          string   // 現在の日付（時間的コンテキスト）
    NewsCount            int      // 見つかったニュース項目数
}

合成テンプレートの選択

Orchestrator はタスクタイプと設定に基づいて合成テンプレートを選択します：

タスクコンテキスト経由
ワークフローテンプレート経由

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "量子コンピューティングのトレンドを調査",
    "context": {
      "synthesis_style": "research_comprehensive"
    }
  }'

name: "my_research"
version: "1.0.0"
defaults:
  model_tier: "medium"
  synthesis_style: "research_with_facts"

synthesis_style が指定されていない場合、Shannon は研究タスクには research_comprehensive を、それ以外のタスクには normal_default を自動的に選択します。

サンプルワークフロー

Shannon は config/workflows/examples/ ディレクトリに 8 つのサンプルワークフローテンプレートを同梱しています。これらはすぐに使える出発点およびリファレンス実装として機能します。

ワークフローカタログ

テンプレート	説明	ノード数	パターン
`simple_analysis.yaml`	クイックサマリー	2	シーケンシャル（intake + summarize）
`research_summary.yaml`	マルチステージ研究	4	劣化付きシーケンシャル
`research_summary_enterprise.yaml`	エンタープライズ研究	4+	大規模モデルのシーケンシャル
`market_analysis.yaml`	市場調査	3+	ツール付きシーケンシャル
`market_analysis_playbook.yaml`	市場プレイブック変種	3+	プレイブック駆動
`complex_dag.yaml`	マルチ並列 DAG	5+	DAG ファンアウト/ファンイン
`parallel_dag_example.yaml`	並列実行デモ	4+	DAG 並列ブランチ
`parallel_items_example.yaml`	バッチアイテム処理	3+	並列アイテム

YAML 構造リファレンス

すべてのサンプルワークフローは次の構造に従います：

name: workflow_id
description: "説明"

defaults:
  model_tier: small|medium|large    # すべてのノードのモデルサイズ
  budget_agent_max: 3000            # 総トークン予算
  require_approval: false           # ヒューマンインザループゲート

nodes:
  - id: node_id
    type: simple|cognitive|dag      # 実行タイプ
    strategy: react|chain_of_thought|tree_of_thoughts
    depends_on: [other_node_ids]    # DAG 依存関係
    budget_max: 1000                # ノードごとのトークン制限

edges:
  - from: node1
    to: node2

パターン劣化

サンプルワークフローは、リソースが制約された場合の Shannon の自動劣化動作を示しています：

DAG        → sequential        （利用可能なエージェントが不足した場合）
tree_of_thoughts → chain_of_thought  （予算が制約された場合）
multi-node → single-node       （最小環境でのフォールバック）

劣化は自動的に行われ、ログに記録されます。フォールバックがいつ発動したかを監視するには、Orchestrator のログで strategy_degraded イベントを確認してください。

ラーニングルーター

有効にすると、Learning Router は過去の成功した実行に対するクエリの類似性に基づいてワークフローテンプレートを自動的に選択します。これにより、呼び出し側がテンプレートを明示的に指定する必要がなくなります。

# 環境変数でラーニングルーターを有効化
ORCHESTRATOR_LEARNING_ROUTER_ENABLED=true

# ルーターは受信クエリを過去のパターンとマッチングし
# 最もパフォーマンスの良いテンプレートを自動的に選択します

Learning Router は時間とともに改善されます。新規デプロイメントでは、十分な実行履歴（通常 50 回以上の成功タスク）が蓄積されるまで、テンプレートを明示的に指定することを推奨します。

次のステップ

カスタムツール

テンプレート用のツールを追加

Shannonの拡張

他の拡張方法

設定

環境とYAML設定

アーキテクチャ

Shannonの設計を理解する

概要

Agent構築

拡張と統合

​概要

ゼロトークンコスト

決定論的実行

予算管理

DAGサポート

​テンプレートを使用するタイミング

​テンプレート構造

​コアフィールド

​デフォルト設定

​ノードタイプ

​シンプルノード

​コグニティブノード

​DAGノード

​スーパーバイザーノード

​実行戦略

​自動劣化

​テンプレートの作成

​テンプレートの使用

​HTTP Gateway 経由

​gRPC 経由

​Python SDK 経由

​テンプレートの例

​シンプルな分析ワークフロー

​研究要約ワークフロー

​並列 DAG ワークフロー

​テンプレートの継承

​バリデーション

​ベストプラクティス

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

​合成テンプレート

​利用可能なテンプレート

​基本コントラクト

​テンプレートデータ

​合成テンプレートの選択

​サンプルワークフロー

​ワークフローカタログ

​YAML 構造リファレンス

​パターン劣化

​ラーニングルーター

​次のステップ

カスタムツール

Shannonの拡張

設定

アーキテクチャ

概要

テンプレートを使用するタイミング

テンプレート構造

コアフィールド

デフォルト設定

ノードタイプ

シンプルノード

コグニティブノード

DAGノード

スーパーバイザーノード

実行戦略

自動劣化

テンプレートの作成

テンプレートの使用

HTTP Gateway 経由

gRPC 経由

Python SDK 経由

テンプレートの例

シンプルな分析ワークフロー

研究要約ワークフロー

並列 DAG ワークフロー

テンプレートの継承

バリデーション

ベストプラクティス

トラブルシューティング

合成テンプレート

利用可能なテンプレート

基本コントラクト

テンプレートデータ

合成テンプレートの選択

サンプルワークフロー

ワークフローカタログ

YAML 構造リファレンス

パターン劣化

ラーニングルーター

次のステップ