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

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

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

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

• Bash 터미널: 터미널 명령어를 실행하고, 맞춤 스크립트를 실행하고, 로컬 파일을 처리할 수 있는 안전한 환경을 제공합니다.

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

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

샌드박스 권한 및 보안

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

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

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

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

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

실행 및 수명 주기 관리

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

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

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

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

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

사전 설치된 소프트웨어

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

에이전트는 네트워크 액세스가 사용 설정된 경우 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/

샌드박스 기본 제공 도구

관리 환경에서 실행할 때 에이전트는 다음과 같은 여러 기본 도구에 액세스할 수 있습니다.

다음 단계