実行コンテキストと境界

  • 5 分

エージェントがアクションを実行してツールに接続できたら、次の質問は、それらのアクションを実行する場所と方法です。

実行コンテキストは、エージェントが動作する境界を定義します。 これには、アクセスできるリポジトリ、それが動作するブランチ、タスクを実行するワークフロー、および付与されたアクセス許可が含まれます。

明確に定義された実行コンテキストがないと、エージェントの動作は予測不能で安全ではなくなります。

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

  • GitHubでの実行コンテキストの意味
  • リポジトリとブランチ スコープで境界を定義する方法
  • ワークフローで実行を分離する方法
  • アクセス許可でエージェント アクションの制御を強制する方法

実行コンテキストとは

実行コンテキストは、エージェントが動作する場所とアクセスできる内容を定義する制約のセットです。

GitHubでは、実行コンテキストには次のものが含まれます。

  • エージェントが動作しているリポジトリ
  • エージェントがターゲットとしているブランチ
  • タスクを実行しているワークフロー
  • そのワークフローに付与されたアクセス許可

このコンテキストは、可視性と機能の両方を決定します。

リポジトリ スコープ

エージェントは常にリポジトリ内で動作します。 リポジトリ内のコードの読み取りと変更のみが可能です。 問題、プル要求、およびそれに関連付けられているワークフローとやり取りします。 明示的に許可されていない限り、他のリポジトリにはアクセスできません。

リポジトリ スコープは、エージェントの動作を制限する最初の境界です。

リポジトリ スコープの構成方法

Copilot クラウド エージェントなどのエージェントの場合、この境界はリポジトリ レベルで明示的に構成されます。

これを構成するには、次のようにします。

  1. GitHubでリポジトリを開く
  2. [設定] をクリックする
  3. サイドバーの [コードとオートメーション] で Copilot をクリックします。
  4. クラウド エージェントの選択
  5. そのリポジトリのエージェントを有効にして構成する
  6. コンフィギュレーションの保存

構成が完了すると、エージェントはそのリポジトリにスコープが設定され、外部で動作することはできません。

リポジトリ内のカスタム エージェント スコープ

カスタム エージェントは同じリポジトリ境界内で動作しますが、構成を通じてスコープをさらに絞り込むことができます。

カスタム エージェント ファイル (.github/agents/security-reviewer.agent.md など) 内では、次のようなフィールドを使用してスコープが定義されます。

  • applyTo →は、エージェントが重点を置くファイルまたはディレクトリを制限します
  • ツール→エージェントが実行できるアクションを定義します。

例：

applyTo:
    - '**/*.js'
    - 'src/auth/**' tools:
    - read_file
    - search_files

カスタム エージェントを構成するには:

  1. リポジトリに .github/agents/ ディレクトリを作成する
  2. 拡張子が .agent.md のエージェント ファイルを追加する
  3. applyTo とツールを使用してスコープを定義する
  4. ファイルをコミットしてプッシュする

これにより、エージェントはリポジトリの特定の部分にのみ集中し、限られた機能で動作できます。

これが実行コンテキストにどのように適合するか

リポジトリ スコープはエージェントの動作場所を定義しますが、カスタム エージェント構成では、エージェントがその境界内でアクセスして実行できる内容を定義します。

一緒に、階層化されたコントロールを作成します。

ブランチ ベースの分離

エージェントはメインブランチで直接作業しません。

代わりに、次のようになります。

  • 選択したブランチ ypu から新しいブランチを作成する
  • そのブランチ内で変更を行う
  • ベース ブランチを対象とするプル要求を開く

これにより、変更が分離され、すべての変更がマージされる前にレビューが確実に行われます。

ブランチ ベースの分離は、重要な安全メカニズムです。

ブランチ ベースのスコープを使用するようにエージェントを構成する

ブランチ ベースのスコープで動作するように Copilot Cloud エージェントを設定するには、次の手順に従います。

  1. ベース ブランチの選択:
    • [エージェント] ページにアクセスする: GitHub リポジトリの [エージェント] ページに移動します。
  2. ベース ブランチを選択する: Copilotコーディング エージェントにタスクを委任する場合は、特定のベース ブランチを選択できます。 これにより、エージェントは、既定のブランチ (通常は "main") ではなく、選択したブランチに基づいて新しいブランチを作成できます。

カスタム エージェントはリポジトリ内で動作しますが、ブランチの動作は直接制御しません。 ブランチ ベースのスコープは、エージェントを実行するシステムによって決定されます。

どのように機能するのか

クラウド エージェントで使用する場合:

  • ブランチが自動的に作成されます。
  • 変更を適用します
  • pull request を開きます。

ワークフロー (CI) で使用する場合:

  • ワークフローによって分岐が決定されます。
  • エージェントは、そのブランチ コンテキスト内で実行されます

カスタム エージェントが制御する内容

カスタム エージェントの定義:

  • フォーカスするファイル (applyTo)
  • 実行できるアクション (ツール)
  • 動作方法 (命令)

ただし、次の定義は行われません。

  • 分岐の作成
  • プル要求の動作
  • 実行の分離

ブランチ ベースのスコープは、カスタム エージェント自体ではなく、実行コンテキストによって常に適用されます。

ブランチやプル要求の作成など、エージェントが自律的なアクションを実行できるようにする

エージェントは、有効にされてタスクが与えられると、リポジトリ内で自律的なアクションを実行できます。

ステップ:

  1. リポジトリのエージェントを有効にします。

    • 設定 → Copilot → Cloud エージェントに移動する
    • エージェントを有効にして、リポジトリを選択する

  2. エージェントにタスクを割り当てます。

    • 問題、コパイロットチャット、またはエージェントインターフェースから
    • 例: バグを修正し、機能を実装する

  3. エージェントにタスクの実行を許可します。

    エージェントは次の内容を実行します。

    • 分岐を作成する
    • コードを変更する
    • 更新内容をコミットしてプッシュする

  4. 確認して最終処理を行います。

    コードの変更と結果に問題がなければ、プル要求をトリガーします。 pull request で変更を要求するか、先に進んでマージすることができます。

エージェントは、制御されたレビュー可能なワークフロー内で動作しながら、ブランチを作成し、コードを変更し、pull request を開くことで、リポジトリ内で自律的に動作します。

ワークフローの境界

実行は、GitHub Actionsを利用したワークフロー内で実行されます。 各ワークフローは、実行のトリガー、実行される手順、およびコードが実行される環境を定義します。 ワークフローは、制御された実行コンテナーとして機能します。 これにより、タスクがクリーンな環境で実行され、実行が繰り返し可能になり、ログと結果がキャプチャされます。 ワークフローは、CI 環境でエージェントの動作を実行する方法でもあります。

アクセス権限の境界

アクセス許可は、エージェントが実行コンテキスト内で実行できることを定義します。

ワークフローには、GITHUB_TOKENなどのトークンを使用してアクセス許可が割り当てられます。

これらのアクセス許可は、以下を許可または制限できます。

  • リポジトリの内容の読み取り
  • コードの記述
  • プル要求の作成
  • シークレットにアクセスする
  • ワークフローのトリガー

アクセス許可は常に明示的に定義し、最小化する必要があります。

GitHub Agentic ワークフローのガードレール

GitHub Agentic ワークフローは、多層防御を使用して設計されています。 主なコントロールは次のとおりです。

  • 既定で読み取り専用トークンを使用することで、エージェントがリポジトリの状態を直接変更せずに検査できるようにする
  • エージェントがアクションを提案し、別のゲートステップで許可される内容を決定できるようにする安全な出力
  • エージェントプロセスには一切のシークレットがなく、コーディングエージェントによって使用されるランタイムには機密資格情報が含まれないようにする
  • サンドボックス化されたコンテナー化された実行
  • ネットワークの分離とホワイトリスト化されたアウトバウンドアクセス
  • 書き込みアクションが適用される前に提案された出力をスキャンする脅威検出

このモデルは、過剰な特権を持つエージェント、迅速な挿入、および意図しないリポジトリの変更のリスクを軽減するのに役立ちます。

境界が重要な理由

実行コンテキストによって、エージェント システムが安全になります。

次の組み合わせによって:

  • リポジトリ スコープ
  • ブランチの分離
  • ワークフロー実行
  • アクセス許可の制御

GitHubは、エージェントが明確で強制可能な制限内で動作することを保証します。

これにより、次の問題が回避されます。

  • 運用コードに対する制御されない変更
  • 意図しないリソースへのアクセス
  • 安全でない実行または未審査の実行

ワークフローを介してエージェントを呼び出す方法

CI の一部としてエージェント駆動型タスクを実行するには、ワークフロー内でそれらを呼び出します。 このセットアップでは、ワークフローが実行境界になり、エージェントは定義された手順とアクセス許可を使用してランナー内で実行されます。

ステップ:

  1. リポジトリでワークフロー ファイルを作成または開きます。 .github/workflows/agent-task.yml

  2. ワークフローを実行するタイミングを定義します。

    on:
 workflow_dispatch: 
schedule: - cron: '0 9 * * *'

    ユース ケースに応じて、プッシュやpull_requestなどのイベントを使用することもできます。

  3. ワークフローのアクセス許可を設定します。

    permissions: 
    contents: read

    ワークフローで実行する必要がある内容に基づいてアクセス許可を調整します。

  4. ジョブとランナーを定義します。

    jobs: 
	agent-task: 
		runs-on: ubuntu-latest

  5. リポジトリを確認します。

    uses: actions/checkout@v4

  6. Node.jsを設定する:

    uses: actions/setup-node@v4 
with: node-version: '18'

  7. 認証を提供します。

    env: COPILOT_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  8. エージェント タスクを実行します。

    run: | npx @github/copilot-cli 
-p "Summarize recent changes in this repository" 
--no-ask-user (Optional)

  9. カスタム エージェントを使用する:

    run: | npx @github/copilot-cli 
--agent security-reviewer 
-p "Review this code for vulnerabilities" 
--no-ask-user

ワークフローは、エージェントの制御された実行パスになります。 タスクは、定義済みのトリガーを使用して、定義済みのリポジトリ コンテキスト内で、そのワークフローに付与されたアクセス許可のみを使用して、定義されたランナーで実行されます。

ブランチ スコープとワークフローの実行

ワークフローは、特定のブランチに対して実行されます。

エージェントはブランチに変更を加えます。

  • ワークフローの実行はそのブランチに限定されます
  • 変更は既定のブランチから分離されます
  • マージ前に検証が行われる

これにより、エージェント アクティビティが制御された実行スコープ内に確実に含まれるようにします。

重要なポイント

実行コンテキストは、エージェントが動作する場所を定義します。 リポジトリ スコープ、ブランチの分離、ワークフロー、アクセス許可などの境界により、エージェントアクションは制御され、予測可能で安全な状態が維持されます。

次に、再試行、ロールバック、エスカレーション メカニズムなど、安全な実行パスを設計する方法について説明します。