네트워크 이그레스 시작하기

개요

이 튜토리얼에서는 에이전트 파일 에 네트워크 송신 정책을 선언하고 배포하여 에이전트의 아웃바운드 트래픽을 제어하는 방법을 학습 . 네트워크 송신을 사용하면 에이전트의 런타임이 도달할 수 있는 외부 서비스를 관리 할 수 있으므로 필요한 대상을 열지 않는 한 에이전트 안전하게 보호할 수 있습니다.

에이전트 파일 의 sandboxes 차단 에서 각 샌드박스에 대한 송신 정책을 정의합니다. 각 샌드박스에 대해 network.egress에서 대상을 선언하고 선택적으로 network.egress_mode를 사용하여 송신 모드 를 설정하다 . 배포 해당 정책을 실행 작업 공간에 적용합니다. 현재 배포된 정책을 검사하려면 agentengine egress 명령 또는 작업 공간 아웃바운드 액세스 UI 사용합니다.

네트워크 이그레스 정책의 작동 방식에 대해 자세히 학습 보려면 네트워크 이그레스 정책 관리 가이드 참조하세요.

전제 조건

시작하기 전에 다음 전제 조건을 충족하는지 확인하세요.

agentengine CLI 버전 0.1.54-alpha 이상이 설치되어 있고 PATH 환경 변수에서 사용할 수 있습니다. 자세한 학습 은 설치 및 인증 가이드 참조하세요.
agentengine auth login 명령을 사용하여 플랫폼에 인증할 수 있습니다.
에이전트 를 배포 하고 이그레스 정책 변경 사항을 적용 할 수 있는 프로젝트 소유자 역할 있습니다.

역할 및 권한에 대해 자세히 학습 네트워크 이그레스 정책 관리 가이드 의 역할 기반 액세스 제어 섹션을 참조하세요.

배포 전에 에이전트 에 필요한 시크릿을 구성하려면 Provision Cloud Secrets 가이드 참조하세요.

에이전트 파일에서 이그레스 구성

모든 작업 공간은 에이전트 를 플랫폼 기본 정책으로 제한하는 deny_all 모드 에서 시작합니다. 처음 배포 전에 agent.yaml 파일 에서 송신 정책을 선언합니다. 배포 파일 에 에이전트 의 송신 모드 상태 있을 것으로 예상합니다. 다음 절차에 따라 에이전트 에 필요한 송신 정책을 선언하고 적용 .

각 샌드박스의 대상을 선언합니다.

agent.yaml 파일 열고 LLM 제공자 엔드포인트 및 도구에서 호출하는 외부 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 서버를 사용하는 경우 샌드박스의 network.egress 필드 에도 각 MCP 호스트 이름을 추가합니다. 서버 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을 사용합니다. 사용 가능한 모드에 대해 자세히 학습 네트워크 이그레스 정책 관리 가이드 의 모드 섹션을 참조하세요.

에이전트를 배포합니다.

파일의 송신 정책이 적용되도록 에이전트 배포합니다. 에이전트 파일 변경해도 업데이트된 에이전트 배포 때까지는 현재 실행 작업 공간에 영향을 주지 않습니다. 이전에 작업 공간에 다른 경로를 통해 다른 송신 모드 있었던 경우 플랫폼은 경고를 보낸 다음 파일 적용합니다. 예시 들어, 이전 정책이 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 허용

도구 샌드박스의 network.egress 필드 에 LLM 호스트 이름을 추가합니다. 그런 다음 도구 샌드박스만 연결할 수 있도록 에이전트 샌드박스를 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 명령을 실행하고 배포된 정책의 예상 샌드박스에 호스트 이름이 나열되어 있는지 확인합니다.
모드 deny_all가 아닌 allow_list 또는 allow_all인지 확인합니다.
를 배포 후에는 아웃바운드 액세스 UI 사용하여 설정을 검토 할 수도 있습니다.

원하는 FQDN이 거부됨

원하는 FQDN이 요구 사항을 충족하는지 확인합니다. 자세한 학습 은 네트워크 이그레스 정책 관리 가이드 의 FQDN(정규화된 도메인 이름) 규칙 섹션을 참조하세요.

Atlas 호스트 이름을 추가할 때 경고가 표시됨

이 플랫폼은 *.mongodb.net와 같은 Atlas cluster 호스트 이름을 허용하며 경고는 비차단입니다. 경고에는 송신 대상이 자체적으로 Atlas 액세스 구성하지 않는다고 명시되어 있습니다. 에이전트 에 Atlas cluster 에 대한 액세스 부여하려면 agentengine atlas 명령 또는 agent.yaml 파일 의 network.atlas_clusters 차단 사용합니다.

포트를 생략하면 경고가 표시됩니다.

포트가 없거나 :*이 있는 대상은 해당 호스팅하다 에 대한 모든 포트를 허용합니다. 플랫폼은 대상을 저장하고 비차단 경고를 반환합니다. 경고를 제거 하려면 대상에 필요한 포트를 1 ~ 65535 범위 에서 최대 10 포트로 지정합니다.

선언한 대상이 표시되지 않음

에이전트 재배포합니다. 플랫폼은 런타임이 아닌 배포 시 에이전트 파일 에서 송신 대상을 읽습니다.

돌아가기

네트워크 이그레스 정책 관리

네트워크 송신을 위한 Atlas 클러스터 연결