开始使用网络出口

Overview

在本教程中，您学习；了解如何通过在代理文件中声明网络出口策略并进行部署来控制代理的出站流量。网络出口允许您管理代理的运行时可以访问哪些外部服务，因此除非您打开代理所需的目标，否则代理会保持安全。

您可以在代理文件的 sandboxes区块中为每个沙箱定义出口策略。对于每个沙箱，您可以在 network.egress 中声明目标，并可以选择使用 network.egress_mode设立出口模式。部署会将该策略应用于正在运行的工作区。要检查当前部署的策略，请使用 agentengine egress 命令或工作区出站访问用户界面。

如需进一步学习；了解网络出口策略的工作原理，请参阅“管理网络出口策略”指南。

先决条件

开始之前，请确保满足以下先决条件：

您已安装 agentengine CLI版本 0.1.54-alpha 或更高版本，并且可在 PATH 环境变量中使用。要学习；了解更多信息，请参阅《安装和身份验证指南》。
您可以使用 agentengine auth login 命令向平台进行身份验证。
您具有项目所有者角色，可以部署代理并应用出口策略更改。

要学习；了解有关角色和权限的更多信息，请参阅《管理网络出口策略》指南中的基于角色的访问控制部分。

要在部署代理之前配置代理所需的密钥，请参阅《预配云密钥》指南。

在代理文件中配置出口

每个工作区都以 deny_all模式启动，该模式将您的代理限制为平台基本策略。在首次部署之前，请在 agent.yaml文件中声明出口策略。部署期望该文件说明代理的出口模式。使用以下过程声明代理所需的出口策略并应用。

声明每个沙箱的目标。

打开 agent.yaml文件，在调用该文件的沙箱的 network.egress字段下添加代理必须访问的每个主机名，包括 LLM提供商程序端点和工具调用的任何外部 API。默认下，工具在代理沙箱中运行。配置为在工具沙箱中运行其主机。以下示例为代理沙箱提供了托管：

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。要学习；了解有关可能模式的更多信息，请参阅 Manage Network Egress Policies（管理网络出口策略）指南中的 Modes（模式）部分。

部署您的代理。

部署代理，使文件的出口策略生效。在部署更新的代理之前，对代理文件的更改不会影响当前正在运行的工作区。如果您的工作区之前有通过其他路径的不同出口模式，平台会发出警告，然后应用文件。示例，如果将先前的策略设立为 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

常见模式

以下部分介绍了代理文件中的常见出口配置。将此部分添加到 agent.yaml文件中，并在每次更改后重新部署。

仅允许工具沙盒使用 LLM API

将 LLM 主机名添加到工具沙箱的 network.egress字段。然后，将代理沙箱设立为 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

更改会在下一次部署时生效。

锁定出站访问

要区块除基本策略之外的所有出口，请将每个沙箱的 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

这些命令不会更新运行策略。重新部署代理以使更改生效。

故障排除

本部分提供与网络出口配置相关的常见问题的故障排除提示。

添加外部主机后，代理无法访问外部主机

编辑代理文件后，确认已部署代理。在部署之前，文件中的策略更改不会应用。
运行 agentengine egress 命令并确认已部署策略中预期沙箱的主机名已列出。
确认模式为 allow_list 或 allow_all，而不是 deny_all。
部署后，您还可以使用出站访问用户用户界面查看设置。

我想要的 FQDN 被拒绝

验证所需的 FQDN 是否符合要求。要学习；了解更多信息，请参阅《管理网络出口策略》指南中的完全限定域名 (FQDN) 规则部分。

添加Atlas主机名时收到警告

平台接受Atlas 集群主机名，例如 *.mongodb.net，并且警告是非阻塞的。该警告指出，出口目标不会自行配置Atlas访问权限。要授予代理访问权限Atlas 集群的权限，请使用 agentengine atlas 命令或 agent.yaml文件中的 network.atlas_clusters区块。

省略端口时收到警告

没有端口或有 :* 的目标允许到该托管的所有端口。平台会保存目的地并返回非阻塞警告。要删除警告，请指定目标所需的端口，最多为 1 到 65535范围内的 10 端口。

我声明的目标没有出现

重新部署代理。平台会在部署时（而非运行时）从代理文件中读取出口目标。