ネットワーク Egress を使い始める

Overview

このチュートリアルでは、エージェントファイルでネットワーク Egress ポリシーを宣言し、それを配置することで、エージェントの送信トラフィックを制御する方法を学習します。ネットワーク Egress を使用すると、エージェントの実行時間が到達できる外部サービスを管理できるため、必要な宛先を開かなければ、エージェントは安全に保たれます。

エージェントファイルの sandboxes ブロックで、各サンドボックスの Egress ポリシーを定義します。各サンドボックスについて、network.egress で宛先を宣言し、オプションで network.egress_mode を使用して Egressモードを設定します。配置はそのポリシーを実行中のワークスペースに適用します。現在配置されているポリシーを検査するには、agentengine egress コマンドまたはワークスペースのアウトバウンドアクセスUI を使用します。

ネットワーク Egress ポリシーの仕組みについて詳しくは、「ネットワーク Egress ポリシーの管理」ガイドを参照してください。

前提条件

始める前に、次の前提条件を満たしていることを確認してください。

agentengineCLI バージョン -alparent0.1.54 以降がインストールされており、PATH 環境変数で使用できます。詳細については、「インストールと認証のガイド」を参照してください。
agentengine auth login コマンドを使用してプラットフォームで認証できます。
エージェントを配置し、Egress ポリシーの変更を適用するには、プロジェクトオーナーのロールが必要です。

ロールと権限の詳細については、ネットワーク Egress ポリシーの管理ガイドの「ロールベースのアクセス制御」セクションを参照してください。

配置する前にエージェントに必要なシークレットを構成するには、「クラウドシークレットのプロビジョニング」ガイドを参照してください。

エージェントファイルでの Egress の構成

すべてのワークスペースは deny_allモードで開始されます。これにより、エージェントはプラットフォームの基本ポリシーに制限されます。最初に配置する前に、agent.yamlファイルで Egress ポリシーを宣言します。配置では、ファイルがエージェントの Egressモードを状態化することが想定されています。エージェントが必要とする Egress ポリシーを宣言し、適用するには、次の手順を使用します。

各サンドボックスの宛先を宣言します。

agent.yamlファイルを開き、LM プロバイダーのエンドポイントやツールを呼び出す外部 API など、それを呼び出すサンドボックスの network.egressフィールドの下に、エージェントがアクセスする必要がある各ホスト名を追加します。デフォルトでは、ツールはエージェントサンドボックスで実行されます。ツールサンドボックスで実行するように構成するツールには、代わりにツールサンドボックスで許可されているホストが必要です。次の例では、エージェントサンドボックスのホストを許可します。

sandboxes:
  agent:
    network:
      egress:
        - fqdn: api.openai.com
          ports: [443]

次の例では、ツールサンドボックスで fetch_github_object ツールを実行し、そのサンドボックスのみが github.com に到達できるようにします。 tools リストは network ブロックの横にあります。

sandboxes:
  agent:
    network:
      egress:
        - fqdn: api.openai.com
          ports: [443]
  tool:
    network:
      egress:
        - fqdn: github.com
          ports: [22]
    tools:
      - fetch_github_object

エージェントが MCP サーバーを使用する場合は、各 MCP ホスト名をサンドボックスの network.egressフィールドにも追加します。 mcp.servers でサーバーを一覧表示しても、単独ではアウトバウンドアクセスは開かれません。

`network.egress_mode`を使用してセキュリティ構造を設定します。

必要に応じて、サンドボックスに network.egress_mode キーを追加して、宛先の適用方法を選択します。次の例では、エージェントサンドボックスとツールサンドボックスの両方に allow_list を設定します。

sandboxes:
  agent:
    network:
      egress_mode: allow_list
      egress:
        - fqdn: api.openai.com
          ports: [443]
  tool:
    network:
      egress_mode: allow_list
      egress:
        - fqdn: api.openai.com
          ports: [443]

network.egress_modeを省略すると、宛先を持つサンドボックスは自動的にallow_list を使用します。使用可能なモードの詳細については、ネットワーク Egress ポリシーの管理ガイドの「モード」セクションを参照してください。

エージェントをデプロイします。

エージェントを配置して、ファイルの Egress ポリシーを有効にします。エージェントファイルの変更は、更新されたエージェントを配置するまで、現在実行中のワークスペースには影響しません。ワークスペースで、以前は別のパスを介して異なる Egressモードが使用されていた場合、プラットフォームは警告を発してから、ファイルを適用します。例、前のポリシーが deny_all に設定され、更新されたポリシーが allow_list に設定されている場合、警告は次のようになります。

agent.yaml network.egress_mode applied workspace tool mode: deny_all → allow_list

有効なポリシーを検証します。

エージェントをテストする前に、次のコマンドを実行してください。

agentengine egress

両方のサンドボックスに allow_list が表示されていること、および、予想されるすべての完全修飾ドメイン名（FQDN）がリストされていることを確認します。（例: ）。

[agent] Mode: allow_list
      FQDN            PORTS  SOURCE
      api.openai.com  443    manifest
[tool] Mode: allow_list
      FQDN            PORTS  SOURCE
      api.openai.com  443    manifest

一般的なパターン

次のセクションでは、エージェントファイル内の一般的な Egress 構成を示します。セクションを agent.yamlファイルに追加し、変更ごとに再配置します。

ツールサンドボックスのみの LM APIを許可する

ツールサンドボックスの network.egressフィールドに LM ホスト名を追加します。次に、エージェントサンドボックスを deny_all に設定して、ツールサンドボックスのみがそれに到達できるようにします。

sandboxes:
  agent:
    network:
      egress_mode: deny_all
  tool:
    network:
      egress_mode: allow_list
      egress:
        - fqdn: api.openai.com
          ports: [443]

両方のサンドボックスで外部API を許可する

エージェントサンドボックスとツールサンドボックスが到達できるように、両方のサンドボックスの下にホスト名を一覧表示します。

sandboxes:
  agent:
    network:
      egress:
        - fqdn: api.stripe.com
          ports: [443]
  tool:
    network:
      egress:
        - fqdn: api.stripe.com
          ports: [443]

すべてのアウトバウンドトラフィックを通過させる

サンドボックスの network.egress_mode を allow_all に設定して、そのサンドボックスでオープンなアウトバウンドアクセスを許可します。

sandboxes:
  agent:
    network:
      egress_mode: allow_all
  tool:
    network:
      egress_mode: allow_all

同じサンドボックスの宛先リストと allow_all を組み合わせることはできません。

宛先の許可を停止する

アウトバウンド宛先の許可を停止するには、サンドボックスの network.egressフィールドからホスト名を削除して再配置します。次の例に示すように、agentengine agent egress remove コマンドを使用してファイルを編集することもできます。

agentengine agent egress remove api.stripe.com

変更は次回の配置で有効になります。

アウトバウンドアクセスのロックダウン

基本ポリシーを除くすべての Egress をブロックするには、各サンドボックスの network.egress_mode を deny_all に設定して再デプロイします。

sandboxes:
  agent:
    network:
      egress_mode: deny_all
  tool:
    network:
      egress_mode: deny_all

CLI を使用した目的先の追加または削除

agentengine agent egress add コマンドと agentengine agent egress remove コマンドは、ローカルエージェントファイル内の各サンドボックスの network.egress ブロックを編集するショートカットです。次の例では、ツールサンドボックスのみの宛先追加します。

agentengine agent egress add --component tool api.openai.com:443

これらのコマンドでは実行中のポリシーは更新されません。変更を有効にするには、エージェントを再配置します。

トラブルシューティング

このセクションでは、ネットワーク Egress の構成に関連する一般的な問題のトラブルシューティングのヒントを提供します。

追加後、エージェントが外部ホストに到達できない

エージェントファイルを編集した後、エージェントが配置されたことを確認します。ファイル内のポリシー変更は、を配置するまで適用されません。
agentengine egress コマンドを実行し、配置されたポリシー内の期待されるサンドボックスにホスト名がリストされていることを確認します。
モードがdeny_all ではなく、allow_list または allow_all であることを確認します。
配置した後、アウトバウンドアクセスUIを使用して設定を確認することもできます。

必要な FQDN が拒否される

必要な FQDN が要件を満たしていることを確認します。詳細については、ネットワーク Egress ポリシーの管理ガイドの「完全修飾ドメイン名（FQDN）ルール」セクションを参照してください。

Atlas ホスト名を追加するときに警告が発せられる

プラットフォームは、*.mongodb.net などの Atlas クラスターのホスト名を受け入れ、警告は非ブロッキングです。警告には、Egress 宛先が単独で Atlas アクセスを構成しないことが示されています。エージェントに Atlas クラスターへのアクセスを許可するには、agentengine atlas コマンドまたは agent.yamlファイルの network.atlas_clusters ブロックを使用します。

ポートを省略すると警告が発せられる

ポートのない宛先または :* の宛先では、そのホストへのすべてのポートが許可されます。プラットフォームは宛先を保存し、非ブロッキング警告を返します。警告を削除するには、宛先に必要なポート、1 から 65535 の範囲で最大 10 ポートを指定します。

宣言した宛先が表示されない

エージェントを再配置します。プラットフォームは、実行時にではなく配置時に、エージェントファイルから Egress 宛先を読み取ります。

戻る

ネットワーク Egress ポリシーの管理

ネットワーク Egress 用の Atlas クラスターのリンク