概要
このガイドでは、Shannonをカスタマイズするための拡張可能なパターンを示し、アップグレードの互換性と関心の分離を維持します。テンプレート
システム 1 - 低オーバーヘッドのプリビルトワークフロー
ツール
MCP、OpenAPI、またはPythonを介して機能を追加
ベンダーアダプター
コアの変更なしでのドメイン特化型統合
合成テンプレート
研究出力のフォーマットをカスタマイズ
拡張メソッドの比較
分解の拡張 (システム 2)
カスタムプランニングおよび推論ロジック用 オーケストレーターは、プランニングのためにLLMサービスエンドポイント/agent/decomposeを呼び出します。
使用するタイミング
- カスタムタスク分解戦略
- ドメイン特化型プランニングヒューリスティック
- LLMリクエストの前処理/後処理
- 外部プランニングシステムとの統合
実装オプション
- 軽量 (Go)
- フルカスタム (Python)
最適: LLMリクエストの前処理/後処理
go/orchestrator/internal/activities/decompose.goにヒューリスティックを追加:テンプレートの追加/カスタマイズ (システム 1)
低オーバーヘッドの繰り返し可能なワークフロー用使用するタイミング
- 事前定義されたワークフロー(データ分析、コードレビューなど)
- AIプランニングなしでの迅速なタスク実行
- 頻繁に使用される一般的なパターン
- パフォーマンスが重要なパス
テンプレートの作成
1
テンプレートファイルの作成
テンプレートを独自のディレクトリに配置:
2
テンプレートの登録
テンプレートディレクトリでレジストリを初期化:
3
テンプレートの使用
gRPC APIを介して:HTTPゲートウェイを介して:
4
利用可能なテンプレートの一覧表示
テンプレートのベストプラクティス
共通のデフォルトに `extends` を使用
共通のデフォルトに `extends` を使用
`registry.Finalize()` で検証
`registry.Finalize()` で検証
ツールを許可リストに保持
ツールを許可リストに保持
ツールを安全に追加
Shannonの機能を拡張するために Shannonは3つのツール統合方法をサポートしています:MCP Tools
コード変更なしで外部HTTP APIを使用
OpenAPI Tools
OpenAPI仕様から自動生成
Built-in Tools
複雑なロジックのためのPythonツール
セキュリティの考慮事項
良い例:実験的なツールはフラグの背後に保持
完全なツールガイド
MCP、OpenAPI、および組み込みPythonツールを追加するための完全なガイドを参照してください
ベンダー拡張
ドメイン特化型エージェントおよびAPI統合のために ベンダーアダプターパターンを使用すると、Shannonのコアコードを変更することなく、独自のAPIや専門的なエージェントを統合できます。アーキテクチャ
ベンダー拡張を使用するタイミング
次のような場合に使用します:- ドメイン特化型API統合(分析、CRM、eコマース)
- カスタムフィールド名変換
- ドメイン知識を持つ専門的なエージェントロール
- セッションコンテキストの注入(アカウントID、テナントID)
- プライベート/独自のツール設定
クイックスタート
1
ベンダーアダプタを作成
2
アダプタを登録
3
設定オーバーレイを作成
4
(オプション)専門的なエージェントを作成
5
環境を介して使用
利点
- ✅ ゼロShannonコア変更 - すべてのベンダーロジックが分離
- ✅ クリーンな分離 - 一般的なインフラストラクチャとベンダー固有のもの
- ✅ 条件付きロード - ベンダーモジュールが利用できない場合の優雅なフォールバック
- ✅ メンテナンスが容易 - ベンダーコードが別のディレクトリに
- ✅ 独立してテスト可能 - アダプターを単体テスト
完全なベンダーアダプターガイド
例、テスト戦略、ベストプラクティスを含む包括的なガイド
人間の承認
センシティブな操作のゲーティング用 SubmitTaskリクエストを通じてrequire_approvalをワイヤリングし、人間の介入を制御します。
設定
APIの使用
承認フロー
require_approval: trueでタスクが提出される- オーケストレーターが実行前に一時停止
- ウェブフック/UIを介して承認リクエストが送信される
- ユーザーがAPIを介して承認/拒否
- ワークフローが続行または終了
レガシー管理エンドポイント
http://localhost:8081/approvals/decisionは非推奨です。代わりにゲートウェイエンドポイントを使用してください。フィーチャーフラグと設定
コード変更なしでのランタイム設定 多くの動作はconfig/features.yamlと環境変数を介して制御され、GetWorkflowConfigを通じて読み込まれます。
一般的なフィーチャーフラグ
環境変数のオーバーライド
動的設定の読み込み
合成テンプレート(出力カスタマイズ)
Shannonが最終的な研究回答をフォーマットする方法をカスタマイズするために 合成テンプレートは、マルチエージェントの研究結果がどのようにフォーマットされ、提示されるかを制御します。特にDeep Researchワークフローに役立ちます。使用するタイミング
- 特定のドメイン(市場調査、学術、エグゼクティブサマリー)向けに出力フォーマットをカスタマイズ
- 引用スタイルを強制
- 回答の構造と長さを制御
- ドメイン固有のフォーマットルールを注入
テンプレートメソッド
名前付きテンプレートの使用
config/templates/synthesis/にテンプレートを作成:
逐語的オーバーライド
テンプレートファイルを作成せずに一度限りのカスタムフォーマットを行うため:最小出力長制御
最小出力長を強制する:テンプレート選択ロジック
選択はコンテキストとワークフロー信号に基づく:context.synthesis_templateが設定されている場合 → その名前のテンプレートを使用。- それ以外の場合、以下のいずれかが真であれば:
context.workflow_type == "research"context.force_research == truecontext.synthesis_style == "comprehensive"context.research_areasが空でない →research_comprehensive.tmplを使用。
- それ以外で
context.synthesis_style == "concise"の場合 →research_concise.tmplを使用。 - それ以外の場合 →
normal_default.tmplを使用。
利用可能なテンプレート
ベストプラクティス
- 常に
_base.tmplを拡張する - 引用契約が維持されることを保証 - 繰り返し使用するフォーマットには名前付きテンプレートを使用
- 一回限りのカスタマイズにはオーバーライドを使用
- 本番使用前にサンプルクエリでテンプレートをテスト
テンプレートディレクトリ
テンプレートは
config/templates/synthesis/ にあります。そのディレクトリの README.md でテンプレート作成ガイドラインを確認してください。ベストプラクティスの要約
関心の分離
関心の分離
- 一般的なインフラストラクチャ: オープンソースにコミット
- ベンダー固有のコード: 別のディレクトリにプライベートに保持
- 設定オーバーレイ: ドメイン固有の設定を分離
- 条件付きインポート: オプションモジュールのための優雅なフォールバック
アップグレード互換性
アップグレード互換性
- 安定したインターフェースを使用 (ToolRegistry, TemplateRegistry など)
- コアサブシステムのフォークを避ける
- カスタマイズは別のディレクトリに保持
- 実験的な変更にはフィーチャーフラグを使用
セキュリティファースト
セキュリティファースト
- テンプレート内でツールをホワイトリスト化
- 危険な操作には承認を有効に
- 外部APIにはドメインホワイトリストを使用
- 秘密情報は環境変数に保持
テスト
テスト
- ベンダーアダプタを単体テストで孤立させる
- Shannonサービスとの統合テスト
- ワークフローの決定論のためにリプレイテストを使用
registry.Finalize()でテンプレートを検証
拡張決定ツリー
次のステップ
カスタムツール
MCP、OpenAPI、および組み込みツールを追加
ベンダーアダプタ
ドメイン固有の統合を構築
設定
完全な設定リファレンス
アーキテクチャ
Shannonのアーキテクチャを理解する