Managed Agents에이전트 환경 구성

클라우드 환경 설정

세션을 위한 클라우드 샌드박스를 사용자 지정합니다.

환경은 에이전트가 실행되는 샌드박스 구성을 정의합니다. 환경을 한 번 생성한 다음, 세션을 시작할 때마다 해당 ID를 참조합니다. 여러 세션이 동일한 환경을 공유할 수 있지만, 각 세션은 자체적으로 격리된 샌드박스(새로운 Linux 컨테이너)를 갖습니다.

이 페이지는 type: cloud 환경을 다룹니다. 자체 인프라에서 샌드박스를 실행하려면 자체 호스팅 샌드박스를 참조하세요.

모든 Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. SDK는 베타 헤더를 자동으로 설정합니다.

환경 생성

ant beta:environments create \
  --name "python-dev" \
  --config '{type: cloud, networking: {type: unrestricted}}'

환경을 구분할 수 있도록 고유하고 설명적인 name을 사용하세요.

세션에서 환경 사용

세션을 생성할 때 환경 ID를 문자열로 전달하세요.

ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID"

구성 옵션

패키지

packages 필드는 에이전트가 시작되기 전에 샌드박스에 패키지를 미리 설치합니다. 패키지는 각각의 패키지 관리자에 의해 설치되며, 동일한 환경을 공유하는 세션 간에 캐시됩니다. 여러 패키지 관리자가 지정된 경우 알파벳 순서(apt, cargo, gem, go, npm, pip)로 실행됩니다. 선택적으로 특정 버전을 고정할 수 있습니다. 버전이 고정되지 않은 패키지는 최신 버전이 설치됩니다.

ant beta:environments create <<'YAML'
name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: unrestricted
YAML

지원되는 패키지 관리자:

필드	패키지 관리자	예시
`apt`	시스템 패키지 (apt-get)	`"ffmpeg"`
`cargo`	Rust (cargo)	`"[email protected]"`
`gem`	Ruby (gem)	`"rails:7.1.0"`
`go`	Go 모듈	`"golang.org/x/tools/cmd/goimports@latest"`
`npm`	Node.js (npm)	`"[email protected]"`
`pip`	Python (pip)	`"pandas==2.2.0"`

네트워킹

networking 필드는 샌드박스의 아웃바운드 네트워크 액세스를 제어합니다. 이는 web_search 또는 web_fetch 도구의 허용 도메인에는 영향을 미치지 않습니다.

모드	설명
`unrestricted`	일반적인 안전 차단 목록을 제외한 전체 아웃바운드 네트워크 액세스입니다. 이것이 기본값입니다.
`limited`	샌드박스 네트워크 액세스를 `allowed_hosts`에 있는 호스트로 제한합니다. 추가 액세스를 허용하려면 `allow_package_managers`와 `allow_mcp_servers`를 `true`로 설정하세요.

다음 예시는 limited 네트워킹으로 환경을 생성합니다:

ant beta:environments create <<'YAML'
name: api-access
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - api.example.com
    allow_mcp_servers: true
    allow_package_managers: true
YAML

프로덕션 배포의 경우 명시적인 allowed_hosts 목록과 함께 limited 네트워킹을 사용하세요. 에이전트에 필요한 최소한의 네트워크 액세스만 부여하는 최소 권한 원칙을 따르고, 허용된 도메인을 정기적으로 감사하세요.

limited 네트워킹을 사용할 때:

allowed_hosts는 샌드박스가 접근할 수 있는 도메인을 지정합니다. 순수 호스트 이름 또는 와일드카드 패턴(예: *.example.com)을 지정하세요. URL 스킴, 포트 또는 경로를 포함하지 마세요.
allow_mcp_servers는 allowed_hosts 배열에 나열된 것 외에 에이전트에 구성된 MCP 서버 엔드포인트에 대한 아웃바운드 액세스를 허용합니다. 기본값은 false입니다.
allow_package_managers는 allowed_hosts 배열에 나열된 것 외에 공개 패키지 레지스트리(예: PyPI 및 npm)에 대한 아웃바운드 액세스를 허용합니다. 기본값은 false입니다.

환경 수명 주기

환경은 명시적으로 보관 처리되거나 삭제될 때까지 유지됩니다.
여러 세션이 동일한 환경을 참조하더라도 각 세션은 자체 샌드박스 인스턴스를 갖습니다. 세션은 파일 시스템 상태를 공유하지 않습니다.
환경은 버전 관리되지 않습니다. 환경을 자주 업데이트하는 경우, 각 세션이 어떤 구성을 사용했는지 알 수 있도록 변경 사항을 직접 기록해 두세요.

환경 관리

# 환경 목록 조회
ant beta:environments list

# 특정 환경 조회
ant beta:environments retrieve --environment-id "$ENVIRONMENT_ID"

# 환경 아카이브(읽기 전용, 기존 세션은 계속 유지됨)
ant beta:environments archive --environment-id "$ENVIRONMENT_ID"

# 환경 삭제(참조하는 세션이 없는 경우에만 가능)
ant beta:environments delete --environment-id "$ENVIRONMENT_ID"

사전 설치된 런타임

클라우드 샌드박스에는 일반적인 런타임이 기본으로 포함되어 있습니다. 사전 설치된 언어, 데이터베이스 및 유틸리티의 전체 목록은 클라우드 샌드박스 참조를 참조하세요.

다음 단계

클라우드 샌드박스 참조

클라우드 샌드박스에서 사용할 수 있는 사전 설치된 패키지, 데이터베이스 및 유틸리티입니다.

세션 시작

세션을 생성하여 에이전트를 실행하고 작업을 시작하세요.

Was this page helpful?

Managed Agents에이전트 환경 구성

클라우드 환경 설정

세션을 위한 클라우드 샌드박스를 사용자 지정합니다.

이 페이지는 type: cloud 환경을 다룹니다. 자체 인프라에서 샌드박스를 실행하려면 자체 호스팅 샌드박스를 참조하세요.

모든 Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. SDK는 베타 헤더를 자동으로 설정합니다.

환경 생성

ant beta:environments create \
  --name "python-dev" \
  --config '{type: cloud, networking: {type: unrestricted}}'

환경을 구분할 수 있도록 고유하고 설명적인 name을 사용하세요.

세션에서 환경 사용

세션을 생성할 때 환경 ID를 문자열로 전달하세요.

ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID"

구성 옵션

패키지

ant beta:environments create <<'YAML'
name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: unrestricted
YAML

지원되는 패키지 관리자:

필드	패키지 관리자	예시
`apt`	시스템 패키지 (apt-get)	`"ffmpeg"`
`cargo`	Rust (cargo)	`"[email protected]"`
`gem`	Ruby (gem)	`"rails:7.1.0"`
`go`	Go 모듈	`"golang.org/x/tools/cmd/goimports@latest"`
`npm`	Node.js (npm)	`"[email protected]"`
`pip`	Python (pip)	`"pandas==2.2.0"`

네트워킹

모드	설명
`unrestricted`	일반적인 안전 차단 목록을 제외한 전체 아웃바운드 네트워크 액세스입니다. 이것이 기본값입니다.
`limited`	샌드박스 네트워크 액세스를 `allowed_hosts`에 있는 호스트로 제한합니다. 추가 액세스를 허용하려면 `allow_package_managers`와 `allow_mcp_servers`를 `true`로 설정하세요.

다음 예시는 limited 네트워킹으로 환경을 생성합니다:

ant beta:environments create <<'YAML'
name: api-access
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - api.example.com
    allow_mcp_servers: true
    allow_package_managers: true
YAML

limited 네트워킹을 사용할 때:

allowed_hosts는 샌드박스가 접근할 수 있는 도메인을 지정합니다. 순수 호스트 이름 또는 와일드카드 패턴(예: *.example.com)을 지정하세요. URL 스킴, 포트 또는 경로를 포함하지 마세요.
allow_mcp_servers는 allowed_hosts 배열에 나열된 것 외에 에이전트에 구성된 MCP 서버 엔드포인트에 대한 아웃바운드 액세스를 허용합니다. 기본값은 false입니다.
allow_package_managers는 allowed_hosts 배열에 나열된 것 외에 공개 패키지 레지스트리(예: PyPI 및 npm)에 대한 아웃바운드 액세스를 허용합니다. 기본값은 false입니다.

환경 수명 주기

환경은 명시적으로 보관 처리되거나 삭제될 때까지 유지됩니다.
여러 세션이 동일한 환경을 참조하더라도 각 세션은 자체 샌드박스 인스턴스를 갖습니다. 세션은 파일 시스템 상태를 공유하지 않습니다.
환경은 버전 관리되지 않습니다. 환경을 자주 업데이트하는 경우, 각 세션이 어떤 구성을 사용했는지 알 수 있도록 변경 사항을 직접 기록해 두세요.

환경 관리

# 환경 목록 조회
ant beta:environments list

# 특정 환경 조회
ant beta:environments retrieve --environment-id "$ENVIRONMENT_ID"

# 환경 아카이브(읽기 전용, 기존 세션은 계속 유지됨)
ant beta:environments archive --environment-id "$ENVIRONMENT_ID"

# 환경 삭제(참조하는 세션이 없는 경우에만 가능)
ant beta:environments delete --environment-id "$ENVIRONMENT_ID"

사전 설치된 런타임

다음 단계

클라우드 샌드박스 참조

클라우드 샌드박스에서 사용할 수 있는 사전 설치된 패키지, 데이터베이스 및 유틸리티입니다.

세션 시작

세션을 생성하여 에이전트를 실행하고 작업을 시작하세요.

Was this page helpful?

환경 생성

세션에서 환경 사용

구성 옵션

패키지

네트워킹

환경 수명 주기

환경 관리

사전 설치된 런타임

다음 단계

환경 생성

세션에서 환경 사용

구성 옵션

패키지

네트워킹

환경 수명 주기

환경 관리

사전 설치된 런타임

다음 단계

환경 생성

세션에서 환경 사용

구성 옵션

패키지

네트워킹

환경 수명 주기

환경 관리

사전 설치된 런타임

다음 단계

환경 생성

세션에서 환경 사용

구성 옵션

패키지

네트워킹

환경 수명 주기

환경 관리

사전 설치된 런타임

다음 단계