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

Agent Platform의 관리형 에이전트 API는 표준의 격리된 Linux 샌드박스에서 작동합니다. 이 안전한 완전 관리형 실행 컨테이너에서 커스텀 에이전트는 기본적으로 추론, 워크플로 계획, bash 명령어 실행, 파일 읽기 또는 쓰기를 할 수 있습니다.

모든 샌드박스 환경은 다음과 같은 핵심 시스템과 컨트롤을 제공합니다.

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

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

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

  • 확장 가능한 통합: 표준 웹 API, 모델 컨텍스트 프로토콜 (MCP) 서버 또는 스킬 레지스트리의 스킬을 비롯한 커스텀 기능을 동적으로 가져오기를 지원합니다.

샌드박스 권한 및 보안

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

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

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

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

  • 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를 사용하여 에이전트를 만들고, 업데이트하고, 나열하고, 가져오고, 삭제하는 방법을 알아봅니다.

가이드

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