Skip to main content

概要

このガイドでは、Shannonをカスタマイズするための拡張可能なパターンを示し、アップグレードの互換性と関心の分離を維持します。

テンプレート

システム 1 - 低オーバーヘッドのプリビルトワークフロー

ツール

MCP、OpenAPI、またはPythonを介して機能を追加

ベンダーアダプター

コアの変更なしでのドメイン特化型統合

合成テンプレート

研究出力のフォーマットをカスタマイズ

拡張メソッドの比較

ほとんどの使用例では、テンプレートベンダーアダプターがパワーとシンプルさの最適なバランスを提供します。

分解の拡張 (システム 2)

カスタムプランニングおよび推論ロジック用 オーケストレーターは、プランニングのためにLLMサービスエンドポイント/agent/decomposeを呼び出します。

使用するタイミング

  • カスタムタスク分解戦略
  • ドメイン特化型プランニングヒューリスティック
  • LLMリクエストの前処理/後処理
  • 外部プランニングシステムとの統合

実装オプション

最適: LLMリクエストの前処理/後処理go/orchestrator/internal/activities/decompose.goにヒューリスティックを追加:
オーケストレーターのワークフローが壊れないように、レスポンススキーマはDecompositionResponseと互換性を保ってください。

テンプレートの追加/カスタマイズ (システム 1)

低オーバーヘッドの繰り返し可能なワークフロー用

使用するタイミング

  • 事前定義されたワークフロー(データ分析、コードレビューなど)
  • AIプランニングなしでの迅速なタスク実行
  • 頻繁に使用される一般的なパターン
  • パフォーマンスが重要なパス

テンプレートの作成

1

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

テンプレートを独自のディレクトリに配置:
2

テンプレートの登録

テンプレートディレクトリでレジストリを初期化:
3

テンプレートの使用

gRPC APIを介して:
HTTPゲートウェイを介して:
4

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

注意: HTTPゲートウェイのテンプレート一覧表示エンドポイントはまだ実装されていない可能性があります。テンプレートの発見にはgRPCを使用してください。

テンプレートのベストプラクティス

ツールを安全に追加

Shannonの機能を拡張するために Shannonは3つのツール統合方法をサポートしています:

MCP Tools

コード変更なしで外部HTTP APIを使用

OpenAPI Tools

OpenAPI仕様から自動生成

Built-in Tools

複雑なロジックのためのPythonツール

セキュリティの考慮事項

テンプレート内で tools_allowlist を常に使用して、使用できるツールを制限してください。
良い例:
悪い例:

実験的なツールはフラグの背後に保持

完全なツールガイド

MCP、OpenAPI、および組み込みPythonツールを追加するための完全なガイドを参照してください

ベンダー拡張

ドメイン特化型エージェントおよびAPI統合のために ベンダーアダプターパターンを使用すると、Shannonのコアコードを変更することなく、独自のAPIや専門的なエージェントを統合できます。

アーキテクチャ

ベンダー拡張を使用するタイミング

次のような場合に使用します:
  • ドメイン特化型API統合(分析、CRM、eコマース)
  • カスタムフィールド名変換
  • ドメイン知識を持つ専門的なエージェントロール
  • セッションコンテキストの注入(アカウントID、テナントID)
  • プライベート/独自のツール設定

クイックスタート

1

ベンダーアダプタを作成

2

アダプタを登録

3

設定オーバーレイを作成

4

(オプション)専門的なエージェントを作成

優雅なフォールバックで登録:
5

環境を介して使用

利点

  • ゼロShannonコア変更 - すべてのベンダーロジックが分離
  • クリーンな分離 - 一般的なインフラストラクチャとベンダー固有のもの
  • 条件付きロード - ベンダーモジュールが利用できない場合の優雅なフォールバック
  • メンテナンスが容易 - ベンダーコードが別のディレクトリに
  • 独立してテスト可能 - アダプターを単体テスト

完全なベンダーアダプターガイド

例、テスト戦略、ベストプラクティスを含む包括的なガイド

人間の承認

センシティブな操作のゲーティング用 SubmitTaskリクエストを通じてrequire_approvalをワイヤリングし、人間の介入を制御します。

設定

APIの使用

承認フロー

  1. require_approval: trueでタスクが提出される
  2. オーケストレーターが実行前に一時停止
  3. ウェブフック/UIを介して承認リクエストが送信される
  4. ユーザーがAPIを介して承認/拒否
  5. ワークフローが続行または終了
ゲートウェイエンドポイント(推奨):
レガシー管理エンドポイントhttp://localhost:8081/approvals/decisionは非推奨です。代わりにゲートウェイエンドポイントを使用してください。
承認ゲートは実行前にルーターで強制されます。

フィーチャーフラグと設定

コード変更なしでのランタイム設定 多くの動作はconfig/features.yamlと環境変数を介して制御され、GetWorkflowConfigを通じて読み込まれます。

一般的なフィーチャーフラグ

環境変数のオーバーライド

動的設定の読み込み

合成テンプレート(出力カスタマイズ)

Shannonが最終的な研究回答をフォーマットする方法をカスタマイズするために 合成テンプレートは、マルチエージェントの研究結果がどのようにフォーマットされ、提示されるかを制御します。特にDeep Researchワークフローに役立ちます。

使用するタイミング

  • 特定のドメイン(市場調査、学術、エグゼクティブサマリー)向けに出力フォーマットをカスタマイズ
  • 引用スタイルを強制
  • 回答の構造と長さを制御
  • ドメイン固有のフォーマットルールを注入

テンプレートメソッド

名前付きテンプレートの使用

config/templates/synthesis/にテンプレートを作成:
API経由で使用:

逐語的オーバーライド

テンプレートファイルを作成せずに一度限りのカスタムフォーマットを行うため:
synthesis_template_overrideを使用する際は、ベーステンプレートの引用契約をバイパスします。オーバーライドテキストに引用ルール([n]形式)を含める必要があります。

最小出力長制御

最小出力長を強制する:

テンプレート選択ロジック

選択はコンテキストとワークフロー信号に基づく:
  1. context.synthesis_template が設定されている場合 → その名前のテンプレートを使用。
  2. それ以外の場合、以下のいずれかが真であれば:
    • context.workflow_type == "research"
    • context.force_research == true
    • context.synthesis_style == "comprehensive"
    • context.research_areas が空でない → research_comprehensive.tmpl を使用。
  3. それ以外で context.synthesis_style == "concise" の場合 → research_concise.tmpl を使用。
  4. それ以外の場合 → normal_default.tmpl を使用。

利用可能なテンプレート

ベストプラクティス

  1. 常に _base.tmpl を拡張する - 引用契約が維持されることを保証
  2. 繰り返し使用するフォーマットには名前付きテンプレートを使用
  3. 一回限りのカスタマイズにはオーバーライドを使用
  4. 本番使用前にサンプルクエリでテンプレートをテスト

テンプレートディレクトリ

テンプレートは config/templates/synthesis/ にあります。そのディレクトリの README.md でテンプレート作成ガイドラインを確認してください。

ベストプラクティスの要約

  • 一般的なインフラストラクチャ: オープンソースにコミット
  • ベンダー固有のコード: 別のディレクトリにプライベートに保持
  • 設定オーバーレイ: ドメイン固有の設定を分離
  • 条件付きインポート: オプションモジュールのための優雅なフォールバック
  • 安定したインターフェースを使用 (ToolRegistry, TemplateRegistry など)
  • コアサブシステムのフォークを避ける
  • カスタマイズは別のディレクトリに保持
  • 実験的な変更にはフィーチャーフラグを使用
  • テンプレート内でツールをホワイトリスト化
  • 危険な操作には承認を有効に
  • 外部APIにはドメインホワイトリストを使用
  • 秘密情報は環境変数に保持
  • ベンダーアダプタを単体テストで孤立させる
  • Shannonサービスとの統合テスト
  • ワークフローの決定論のためにリプレイテストを使用
  • registry.Finalize() でテンプレートを検証

拡張決定ツリー

拡張決定木 - 拡張タイプ(テンプレート、MCP/OpenAPIツール、組み込みツール、ベンダーアダプター、カスタム分解)と複雑性レベル(低、中、高)の選択を導く決定木 / Extension Decision Tree - Decision tree guiding selection of extension type (Templates, MCP/OpenAPI Tools, Built-in Tools, Vendor Adapters, Custom Decomposition) and complexity level (Low, Medium, High)

次のステップ

カスタムツール

MCP、OpenAPI、および組み込みツールを追加

ベンダーアダプタ

ドメイン固有の統合を構築

設定

完全な設定リファレンス

アーキテクチャ

Shannonのアーキテクチャを理解する