Agent Platform 샌드박스 환경의 관리형 에이전트 API

Agent Platform의 관리형 에이전트 API는 표준 격리 Linux 샌드박스에서 작동합니다. 이 안전한 완전 관리형 실행 컨테이너에서 커스텀 에이전트는 즉시 추론하고, 워크플로를 계획하고, bash 명령어를 실행하고, 파일을 읽거나 쓸 수 있습니다.

모든 샌드박스 환경은 다음과 같은 핵심 시스템과 제어 기능을 제공합니다.

  • 영구 파일 시스템: 멀티턴 상호작용 전반에서 파일, 에이전트 로직, 실행 상태를 안전하게 유지합니다.

  • Bash 터미널: 터미널 명령어 실행, 커스텀 스크립트 실행, 로컬 파일 처리를 위한 안전한 환경을 제공합니다.

  • 네트워크 격리: 기본적으로 외부 네트워크 액세스를 사용 중지합니다. 네트워크 allowlist를 명시적으로 선언하여 에이전트가 공개 인터넷 리소스에 액세스하거나 외부 라이브러리를 다운로드하도록 허용할 수 있습니다.

  • 확장 가능한 통합: 표준 웹 API, 모델 컨텍스트 프로토콜(MCP) 서버, 스킬 레지스트리의 스킬을 포함한 커스텀 기능을 동적으로 가져올 수 있습니다.

샌드박스 권한 및 보안

표준 엔터프라이즈 보안 경계를 유지하기 위해 원격 샌드박스는 다음 권한 모델에 따라 작동합니다.

  • 네트워크 격리: 기본적으로 샌드박스는 외부 네트워크 액세스 없이 작동합니다. 환경 구성에서 도메인 허용 목록을 설정하여 연결을 명시적으로 사용 설정합니다. 허용 목록 예시는 네트워크 액세스 구성을 참조하세요.

  • 최소 권한 실행: 네트워크 액세스가 사용 설정되면 컨테이너에 관리자 사용자 인증 정보 또는 권한이 없습니다. 기본적으로 공개적으로 액세스할 수 있는 인터넷 위치만 쿼리할 수 있습니다.

  • Cloud Storage 및 Skill Registry 마운트의 데이터 범위 지정: Cloud Storage 또는 Skill Registry에서 외부 데이터 소스를 연결하면 에이전트 구성에 지정된 특정 디렉터리 또는 기술에만 액세스하도록 설계된 범위 축소 승인 토큰이 환경에 제공됩니다. 샌드박스에는 주변 사용자 인증 정보가 포함되어 있지 않으며 프로젝트의 다른 저장소나 파일에 액세스할 수 없습니다.

  • MCP 사용자 인증 정보 범위 지정: 백엔드 인증 토큰이 포함된 모델 컨텍스트 프로토콜(MCP) 서버의 헤더 구성은 구성에 정의된 특정 MCP 엔드포인트에 액세스할 때만 전송됩니다.

실행 및 수명 주기 관리

다음 표준 매개변수는 샌드박스 실행 및 수명 주기를 제어합니다.

  • 샌드박스 환경: 에이전트는 조정을 위해 Antigravity 하네스를 사용하여 완전 관리형 샌드박스 환경에서 실행됩니다.

  • 샌드박스 TTL(수명): 샌드박스 환경의 표준 TTL(수명)은 7일입니다. 새로운 상호작용이 있을 때마다 이 타이머가 자동으로 재설정되어 활성 상태의 상담사가 계속 대기할 수 있습니다.

  • 에이전트 구성 지속성: 백엔드는 에이전트 구성을 영구적으로 저장하며, Agents API에 명시적인 DELETE 요청을 보낼 때까지 유지됩니다.

  • 에이전트 공동작업: 상호작용 중에 동일한 env_id를 제공하면 여러 에이전트가 동일한 환경을 공유합니다.

사전 설치된 소프트웨어

샌드박스에는 표준 Linux 유틸리티 세트가 포함되어 있습니다.

카테고리 패키지/도구
UNIX 도구
  • bc
  • curl
  • fd-find
  • gawk
  • gcloud CLI
  • git
  • htop
  • iproute2
  • jq
  • lsof
  • procps
  • ripgrep
  • rsync
  • tree
  • unzip
  • wget
  • which
Python 3.11 패키지
  • ast-grep-cli
  • beautifulsoup4
  • google-genai
  • numpy
  • pandas
  • pyyaml
  • requests
Node.js 20 전역 패키지
  • create-next-app
  • create-vite
  • typescript

에이전트는 네트워크 액세스가 사용 설정된 경우 pip install 또는 npm install를 사용하여 런타임에 추가 패키지를 설치할 수 있습니다. 이러한 패키지는 환경 스냅샷에 유지되며 동일한 env_id를 재사용하는 상호작용에 계속 사용할 수 있습니다.

기능 마운트 아키텍처

에이전트의 base_environment.sources 내에 있는 스킬 레지스트리와 같은 소스에서 외부 스킬을 구성하면 이러한 리소스가 샌드박스 파일 시스템에 직접 연결됩니다. 시스템은 각 기술을 지정된 타겟 디렉터리에 배치하여 원래 기술 패키지 디렉터리 구조를 유지합니다. 이러한 구성을 통해 에이전트가 개별 기술 파일을 검색할 수 있습니다.

소스 구성 예시

다음 예시에서는 기술 레지스트리에서 세 가지 기술을 연결합니다.

"sources": [
  {
    "type": "skill_registry",
    "source": "projects/{projectID}/locations/{location}/skills/pdf-skill",
    "target": "/.agent/skills/"
  },
  {
    "type": "skill_registry",
    "source": "projects/{projectID}/locations/{location}/skills/finance-skill",
    "target": "/.agent/skills/"
  },
  {
    "type": "skill_registry",
    "source": "projects/{projectID}/locations/{location}/skills/git-skill",
    "target": "/.agent/other-skills/"
  }
]

마운트 후 샌드박스 파일 시스템 구조

샌드박스 환경이 프로비저닝되면 파일이 컨테이너 내에 다음과 같이 마운트되고 구조화됩니다.

/ (root)
└── .agent/
    ├── skills/                    <-- Mount Target for pdf-skill & finance-skill
    │   ├── pdf-skill/             <-- Preserved skill directory
    │   │   ├── SKILL.md
    │   │   └── scripts/
    │   └── finance-skill/         <-- Preserved skill directory
    │       ├── SKILL.md
    │       └── scripts/
    └── other-skills/              <-- Mount Target for git-skill
        └── git-skill/             <-- Preserved skill directory
            ├── SKILL.md
            └── scripts/

샌드박스 기본 제공 도구

관리형 환경에서 실행되는 경우 에이전트는 여러 기본 도구에 액세스할 수 있습니다.

도구 이름 설명
bash 샌드박스 터미널에서 셸 명령어를 실행하고 출력을 반환합니다.
file_system 파일의 콘텐츠를 읽고 쓰고 삭제하며 디렉터리의 콘텐츠를 나열합니다.

다음 단계

개요

자율 에이전트를 빌드하기 위한 구성 기반의 REST 중심 환경인 Agent Platform의 관리형 에이전트 API에 대해 알아봅니다.

가이드

REST API를 사용하여 에이전트를 만들고, 업데이트하고, 나열하고, 가져오고, 삭제하는 방법을 알아봅니다.

가이드

런타임에 에이전트와 상호작용하고, 세션 상태를 관리하고, 구성을 동적으로 재정의하는 방법을 알아봅니다.