Primeiros passos com a saída de rede

Visão geral

Neste tutorial, você aprenderá a controlar o tráfego de saída do seu agente declarando a política de saída de rede no arquivo do seu agente e implementando-a. A saída de rede permite que você gerencie quais serviços externos o tempo de execução do seu agente pode alcançar, para que seu agente permaneça seguro, a menos que você abra os destinos necessários.

Você define a política de saída para cada sandbox no bloco sandboxes do seu arquivo de agente . Para cada sandbox, você declara destinos em network.egress e, opcionalmente, define o modo de saída usando network.egress_mode. Um sistema aplica essa política ao seu espaço de trabalho em execução. Para inspecionar a política atualmente implantada, use o comando agentengine egress ou a interface de usuário de acesso de saída do espaço de trabalho.

Para saber mais sobre como as políticas de saída de rede funcionam, consulte o guia Gerenciar políticas de saída de rede.

Pré-requisitos

Antes de começar, certifique-se de atender aos seguintes pré-requisitos:

Você tem a versão agentengine CLI 0.1.54-alfa ou posterior instalada e ela está disponível em sua variável de ambiente PATH. Para saber mais, consulte o guia Instalar e autenticar.
Você pode autenticar na plataforma usando o comando agentengine auth login.
Você tem a role de proprietário do projeto para distribuir o agente e aplicar as alterações na política de saída.

Para saber mais sobre roles e permissões, consulte a seção Controle de acesso baseado em roles do guia Gerenciar políticas de saída de rede.

Para configurar os segredos de que seu agente precisa antes de implantá-lo, consulte o guia Segredos da Provision Cloud .

Configurar saída no arquivo do agente

Todo workspace inicia no mododeny_all, que restringe seu agente à política de base da plataforma. Antes de sua primeira implantação, declare uma política de saída no seu arquivo agent.yaml. O sistema espera que o arquivo informe o modo de saída do seu agente. Use o procedimento a seguir para declarar a política de saída que seu agente precisa e aplicá-la.

Declare os destinos para cada sandbox.

Abra o arquivo agent.yaml e adicione cada nome de host que seu agente deve alcançar no campo network.egress da sandbox que o chama, incluindo o endpoint do provedor LLM e quaisquer APIs externas que suas ferramentas chamem. Por padrão, as ferramentas são executadas na sandbox do agente . As ferramentas que você configura para execução na sandbox de ferramentas precisam que seus hosts sejam permitidos lá. O exemplo a seguir permite um host para a sandbox do agente :

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

O exemplo a seguir executa a ferramenta fetch_github_object na sandbox de ferramentas e permite que apenas essa sandbox atinja github.com. A lista tools fica ao lado do bloco network:

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

Se o seu agente usar servidores MCP, adicione também cada nome de host MCP ao campo network.egress do sandbox. A listagem de um servidor em mcp.servers não abre o acesso de saída por si só.

Defina a postura de segurança com `network.egress_mode`.

Opcionalmente, adicione a chave network.egress_mode a uma sandbox para escolher como seus destinos se aplicam. O exemplo a seguir define allow_list para a sandbox do agente e a sandbox da ferramenta:

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]

Se você omitir network.egress_mode, uma sandbox que tenha destinos utilizará automaticamente allow_list. Para saber mais sobre os modos possíveis, consulte a seção Modos no guia Gerenciar políticas de saída de rede.

Implemente seu agente.

Implemente o agente para que a política de saída do arquivo entre em vigor. As alterações no arquivo do agente não afetam o espaço de trabalho atualmente em execução até que você implemente o agente atualizado. Se o seu workspace tinha anteriormente um modo de saída diferente por outro caminho, a plataforma avisa e depois aplica o arquivo. Por exemplo, se a política anterior estiver definida como deny_all e a sua política atualizada estiver definida como allow_list, o aviso será semelhante ao seguinte:

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

Verifique a política eficaz.

Antes de testar seu agente, execute o comando a seguir.

agentengine egress

Confirme se ambas as sandboxes mostram allow_list e que todos os nomes de domínio totalmente qualificados (FQDNs) esperados estão listados. Por exemplo:

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

Padrões comuns

As seções a seguir mostram configurações de saída comuns no arquivo do agente . Adicione a seção ao seu arquivo agent.yaml e redistribua após cada alteração.

Permitir uma API LLM somente para a Sandbox da Ferramenta

Adicione o nome de host LLM ao camponetwork.egress da sandbox de ferramentas. Em seguida, defina a sandbox do agente como deny_all para que somente a sandbox da ferramenta possa acessá-la:

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

Permitir uma API externa para ambos os Sandboxes

Liste o nome do host em ambas as sandboxes para que a sandbox do agente e a sandbox da ferramenta possam acessá-lo:

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

Deixe passar todo o tráfego de saída

Defina o network.egress_mode de uma sandbox como allow_all para permitir o acesso de saída aberto a essa sandbox:

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

Você não pode combinar allow_all com uma lista de destino para a mesma sandbox.

Parar de permitir um destino

Para parar de permitir um destino de saída, remova o nome do host do campo network.egress do sandbox e redistribua. Você também pode editar o arquivo utilizando o comando agentengine agent egress remove, como mostrado no seguinte exemplo:

agentengine agent egress remove api.stripe.com

A alteração entra em vigor na sua próxima implantação.

Bloquear acesso de saída

Para bloquear todas as saídas, exceto a política base, defina o network.egress_mode de cada sandbox como deny_all e redistribua:

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

Use a CLI para adicionar ou remover destinos

Os comandos agentengine agent egress add e agentengine agent egress remove são atalhos que editam o bloco network.egress de cada sandbox no arquivo de agente local. O exemplo a seguir adiciona um destino somente para a sandbox da ferramenta:

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

Esses comandos não atualizam a política em execução. Redistribua seu agente para que as alterações entrem em vigor.

Solução de problemas

Esta seção fornece dicas de solução de problemas comuns relacionados à configuração de saída de rede.

Meu agente não consegue alcançar um host externo depois que eu o adiciono

Confirme que você distribuiu seu agente depois de editar o arquivo do agente . As alterações da política no arquivo não se aplicam até que você implemente.
Execute o comando agentengine egress e confirme que o nome do host está listado para a sandbox esperada na política implantada.
Confirme que o modo é allow_list ou allow_all, não deny_all.
Depois de implementar, você também pode revisar as configurações usando a interface de usuário de acesso de saída.

O FQDN que pretendo é rejeitado

Verifique se o FQDN desejado atende aos requisitos. Para saber mais, consulte a seção Regras de nome de domínio totalmente qualificado (FQDN) do guia Gerenciar políticas de saída de rede.

Recebo um aviso quando adiciono um nome de host Atlas

A plataforma aceita nomes de host de Atlas cluster, como *.mongodb.net, e o aviso não está bloqueando. O aviso observa que um destino de saída não configura o acesso ao Atlas por conta própria. Para conceder ao seu agente acesso a um Atlas cluster, use os comandos agentengine atlas ou o bloco network.atlas_clusters no arquivo agent.yaml.

Recebo um aviso quando omiti a porta

Um destino sem porta ou com :* permite todas as portas para esse host. A plataforma salva o destino e retorna um aviso de não bloqueio. Para remover o aviso, especifique as portas que o destino precisa, até 10 portas no intervalo de 1 a 65535.

Um destino que declarei não está aparecendo

Redistribua seu agente. A plataforma lê os destinos de saída do arquivo do agente no momento da implementação, não no tempo de execução.

Voltar

Gerenciar políticas de saída da rede

Vincule seu Atlas cluster para saída de rede