エージェントの制御と運用 - 可観測性、ツール、MCP、シークレット、フック、信頼性

5 分

このユニットでは、次の内容について説明します。

エージェントの作業に必要な証拠と成果物を検出する
ツール、MCP 統合、シークレットを安全に制御する方法
フックがガードレールを設け、監査ログを強制する方法
再試行、エスカレーション、最小特権を使用して信頼性を設計する方法

エージェントに必要な証拠と成果物

エージェントシステムは、意味のあるすべてのアクションに対して、表示可能な成果物を生成する必要があります。成果物がないと、動作を確実に確認したり、エラーをデバッグしたり、アドホック分析を実行したりすることはできません。

GitHubでは、次のようなアーティファクトによって可観測性が実現されます。

プルリクエストとPRタイムライン
コミットとブランチの履歴
ワークフローの実行とジョブログ、
必要なチェックとスキャン結果、および
アップロードされたワークフロー成果物 (テストレポートなど)。

最小可観測性セット

適切に設計されたエージェントタスクでは、GitHubネイティブ成果物を使用して、目に見える確認可能な証拠を生成する必要があります。

通常、プル要求の説明またはディスカッションに含まれる構造化されたプラン
制約付きのプルリクエストとコミット履歴
必要なチェックのワークフロー実行リンク
アップロードされた成果物 (ログやレポートなど)
結果の確認 (承認または要求された変更)

レビューとデバッグのためのワークフロー成果物のアップロード

アーティファクトをアップロードすると、ログがスクロールする場合でも、証拠が永続的でレビュー可能になります。

レビュー担当者が結果をすばやく検証できるように、"証拠" セクションの下の PR にワークフロー実行と関連する成果物へのリンクを含めるベストプラクティスをお勧めします。

- name: Upload test results
  uses: actions/upload-artifact@v4
  with:
    name: test-results
    path: results/

信頼性は失敗を前提としています

信頼性の高いシステムでは、障害が発生すると想定しています。エージェントはタスクを誤解し、テストは失敗し、変更は既存の動作と競合します。アーキテクチャでは、障害を早期に検出し、安全な復旧パスを提供する必要があります。

実用的な信頼性パターンには、次のものが含まれます。

再試行: エージェントは、チェックが失敗したときにブランチを更新できます。
エスカレーション: 永続的なエラーが要約され、人間に渡されます。
ロールバックの準備: リスクの高い変更には、ロールバックノートとスコープ制限が含まれます。

安全なイテレーションポリシー

反復に予測可能なポリシーを使用します。

必要なチェックが失敗した場合、エージェントは PR ブランチを修正し、チェックを再実行する可能性があります。
同じ必要なチェックが 2 回失敗した場合は、次の方法で人間のレビュー担当者にエスカレートします。
- 何が失敗しましたか、
- 何が試みられたか、
- どのような証拠が存在するか、
- 推奨される次の手順は何ですか。

このポリシーは、無限ループを防ぎ、障害を実行可能にするのに役立ちます。

必要なアーキテクチャ機能としての可観測性

自律的な作業の最小可観測性セットには、次のものが含まれている必要があります。

表示されるプラン成果物、
PRおよびコミット履歴
必要なチェック用のワークフロー実行リンク
永続的な成果物（ログ/レポート/トレース）
結果と承認を確認します。

実行とコードの状態に対して証拠を追跡できるようにする

名前付け/メタデータの原則を教える:

証拠は、特定のワークフロー実行と特定のコミットに対して追跡可能である必要があります。

これにより監査やデバッグが容易になり、「どの実行がこの成果物を生成し、どのようなコード状態に基づいていたか」に答えることができます。

パターンを教える:

成果物が生成される場所をアップロードする
評価またはデプロイが行われた場所でダウンロードしてください

これにより、生成されたファイルをリポジトリにコミットし直すことなく、出力を検査可能で使用可能な状態に保ちます。

ツール、MCP 統合、シークレットを安全に制御する方法

エージェントプロファイルの構成には、次の 3 種類の制御が用意されています。

機能の境界: 許可されるツール (許可リストを優先)
可視性の境界: 対話型 UI でエージェントがユーザーが選択できるかどうかを示します
委任境界：どのサブエージェントが呼び出されるかとハンドオフがどのように行われるか設計ガイダンス：
エージェントの計画とレビューには、読み取り専用ツールセットを使用します。
実装ツールを実行エージェントに制限します。
ツールの許可リストに対する変更は、ガバナンスに依存する変更として扱います。

MCP サーバー: ツールを安全に拡張する

MCP サーバーはツール機能を拡張します。次のパターンを教えます。

トランスポートの形状: 一部の MCP サーバーはリモートエンドポイントです。その他はローカルプロセスです。
認証: トークンは、保護されたシークレット境界を介して実行時に挿入する必要があります。
名前空間の制御: 広範なワイルドカードではなく、狭いツールサブセットを有効にすることを好みます。

運用ガイダンス:

MCPツールの追加や拡張は影響範囲を広げる可能性があり、リスクの高い依存関係として慎重に検討する必要があります。

シークレットと環境の制約 (リポジトリコンテンツからシークレットを保持する)

シークレットは次の場所に配置しないでください。

命令ファイル、
コミットされた構成ファイル
あるいは、プレーンテキスト形式のワークフロー YAML。

その代わりに：

実行時の挿入を目的とした保護されたシークレット境界を使用する
シークレットを必要とするコンポーネントにのみシークレットを渡す
公開を減らすために、シークレットの可用性をスコープ (たとえば、環境別) にします。

原則を教える:

"エージェントのランタイム環境には、独自のシークレット境界があります。リポジトリ CI シークレットが自動的に継承されるとは考えないでください。

フックがガードレールを設け、監査ログを強制する方法

GitHub Copilot エージェントでは、フックはリポジトリに格納されている構成ファイルとして定義されます (例: .github/hooks/)。各フックは、実行するタイミングと実行するアクションを指定します。

フックは、エージェントの実行中に特定のポイントでカスタムコマンドを実行します。これにより、チームはポリシーを適用し、アクションを検証し、監査データを自動的にキャプチャできます。

簡略化された例:

{
  "name": "block-high-risk-command",
  "trigger": "pre-tool-use",
  "run": "if [[ \"$TOOL\" == \"delete\" ]]; then echo 'Blocked unsafe command'; exit 1; fi"
}

処理のしくみ

ツールが実行される前にフックが実行されます (ツールの使用前)
要求されたアクションを検査します
アクションがブロックされたパターンと一致する場合、実行は停止されます

一般的なフックパターン

アクション前フック 実行前に安全でないアクションを検証またはブロックする
ポストアクションフックを使用して、ツールの使用状況、出力、または決定をログに記録し、監査を行う
エラーフック エラーをキャプチャし、エスカレーションまたはアラートをトリガーする

フックは何を可能にしますか?

セキュリティポリシーの適用 (安全でないコマンドのブロックなど)
コンプライアンスとデバッグのための監査ログの追加
外部システムとの統合 (アラート、監視、承認)
フックは、モデルの推論とは無関係に動作する強制可能な制御ポイントを提供します。命令に依存する代わりに、実行時に特定のルールが常に適用されるようにします。

再試行、エスカレーション、最小特権を使用して信頼性を設計する方法

前に説明したように、エージェントは最終的に失敗しますが、これらの障害をキャッチし、人間の介入がそれを確実にキャッチできるシステムを構築できます。たとえば、障害を確実にキャッチする方法をいくつか次に示します。

一時的な障害に対する制限付き再試行
繰り返し発生するエラーのエスカレーションパス
リスクの高い変更に対するロールバックの準備
被害範囲を減らすための最小特権のアクセス許可

教えるロールバックセーフパターン:

機密性の高い構成をデプロイする際には、"ブランチの最新" ではなく、明示的な参照（コミット／タグ）を操作してください。

最小特権のリマインダー:

既定でワークフローのアクセス許可を制限し、必要な場合にのみ昇格します。

ワークフローアクセス許可の最小特権

最小限の特権を使用すると、問題が発生した場合のリスクが軽減されます。また、アクセス許可を超える自動化がアーキテクチャの脆弱性になることを防ぎます。

permissions:
  contents: read
  pull-requests: write

この構成により、リポジトリのコンテンツを読み取り、PR コンテキスト (コメント、状態) を更新しながら、既定で広範な書き込みアクセスを防ぐことができます。

フィードバック

このページはお役に立ちましたか?