Managed Deep Agents에 샌드박스 추가하기

Managed Deep Agents에 샌드박스 추가하기

관리형 딥 에이전트를 위한 격리된 파일시스템과 셸을 구성할 수 있어요.

샌드박스는 관리형 딥 에이전트에게 파일 작업, 코드 실행, 명령 실행을 위한 격리된 파일시스템과 셸을 제공합니다.

Managed Deep Agents는 공개 베타 상태이며 LangSmith Cloud의 미국 지역에서만 사용할 수 있어요.

샌드박스 선언을 sandbox/ 아래에 넣으세요. 스냅샷을 프로비저닝하려는 경우에만 sandbox/setup.sh를 추가합니다:

my-agent/
  agent.ts
  sandbox/
    index.ts
    setup.sh   # optional

전체 프로젝트 레이아웃은 프로젝트 구조를 참고하세요.

출처: 문서

본문

샌드박스 구성하기 (Configure a sandbox)

에이전트가 파일을 쓰거나, 코드를 실행하거나, 셸 명령을 실행해야 할 때 샌드박스를 사용하세요.

mda init은 샌드박스 선언을 스캐폴딩합니다. Managed Deep Agents는 sandbox/ 디렉터리가 있을 때만 샌드박스를 활성화합니다.

mda init은 setup.sh를 만들지 않습니다. 스냅샷이 패키지를 설치하거나, 트리를 복제하거나, 이미지를 변경해야 하는 경우 해당 파일을 직접 추가하세요.

Managed Deep Agents는 이 백엔드에 LangSmith Sandboxes를 사용합니다. 재사용은 항상 영구 스레드당 샌드박스 하나입니다.

defineSandbox로 샌드박스를 선언합니다:

import { defineSandbox } from "managed-deepagents";

export const sandbox = defineSandbox({
  idleTtlSeconds: 600,
  defaultTimeout: 600,
});
옵션 (Option) 기본값 (Default) 설명 (Description)
idleTtlSeconds 600 샌드박스와 그 내용이 삭제되기 전의 비활성 초. 삭제는 복구할 수 없음.
defaultTimeout 600 각 명령에 허용되는 초.

스냅샷 프로비저닝하기 (Provision a snapshot)

sandbox/setup.sh가 있으면 mda deploy와 mda dev가 스크립트를 한 번 실행하고 결과 환경을 스냅샷으로 저장합니다. 복제된 저장소와 설치된 패키지 같은 그 실행의 수정 사항이 스냅샷에 유지됩니다. 새 스레드는 setup.sh를 실행하는 대신 해당 스냅샷을 복제합니다. 스냅샷은 setup.sh가 변경될 때까지 재사용되며, 그 시점에 재구축됩니다.

스크립트는 bash -e로 실행됩니다. 0이 아닌 종료는 스냅샷과 배포 또는 mda dev 세션을 실패시킵니다. LangSmith는 실패한 스냅샷으로 라이브 배포를 업데이트하지 않습니다. 이전에 성공한 스냅샷이 계속 제공됩니다.

#!/usr/bin/env bash
set -euo pipefail

apt-get update && apt-get install -y jq
mkdir -p /workspace

배포가 전달하는 프로젝트 .env 값은 setup.sh가 실행될 때 환경 변수로 사용할 수 있습니다. 예를 들어 비공개 저장소를 복제하는 데 사용되는 토큰 등입니다. 스냅샷을 복제하는 스레드 샌드박스는 해당 변수를 상속하지 않습니다. setup.sh가 실행되는 동안 파일시스템에 비밀을 쓰지 마세요. 디스크에 있는 모든 것은 모든 스레드의 이미지 일부입니다.

setup.sh를 편집하고 재배포해도 라이브 스레드의 /workspace가 지워지지 않습니다. 해당 상자는 이미 가진 파일을 유지합니다. 새 스레드가 새 스냅샷을 복제합니다.

베이크 베이스 선택하기 (Choose a bake base)

베이크 베이스가 없으면 LangSmith의 기본 샌드박스 템플릿이 시작점입니다. 다른 것으로 시작하려면 다음 중 정확히 하나를 설정하세요:

옵션 (Option) 용도 (Use)
snapshotName LangSmith 스냅샷 이름. 태그 허용.
snapshotId LangSmith 스냅샷 ID.
dockerImage 게시된 Docker 이미지. 
import { defineSandbox } from "managed-deepagents";

export const sandbox = defineSandbox({
  idleTtlSeconds: 600,
  dockerImage: "python:3.12-slim",
});

비공개 이미지의 경우 이미지와 registry를 전달하세요. Managed Deep Agents는 베이크 시 배포 소유 Host 레지스트리를 만들거나 업데이트합니다. 변수 이름만 컴파일되며, 자격증명 값은 빌드나 스냅샷에 들어가지 않습니다.

passwordEnv에 비밀번호 이름을 지정합니다:

import { defineSandbox } from "managed-deepagents";

export const sandbox = defineSandbox({
  dockerImage: "ghcr.io/acme/agent-base:1",
  registry: {
    url: "ghcr.io",
    username: "octocat",
    passwordEnv: "GHCR_TOKEN",
  },
});

GHCR_TOKEN을 프로젝트 .env 또는 프로세스 환경에 넣으세요. 베이크 후 Managed Deep Agents는 해당 값을 실행 중인 Agent Server로 전달하지 않습니다.

에이전트가 샌드박스를 사용하는 방식 (How the agent uses the sandbox)

에이전트는 ls, read_file, write_file, edit_file, delete, glob, grep 같은 내장 파일시스템 도구를 사용하고 execute로 셸 명령을 실행합니다. 지시사항을 사용해 에이전트가 어디에서 작업해야 하고 무엇을 수정해서는 안 되는지 지정하세요.

샌드박스 비활성화하기 (Disable the sandbox)

프롬프트, 메모리, 도구만 필요한 에이전트처럼 옵트아웃하려면 sandbox/ 디렉터리를 삭제하세요.

기존 배포의 경우 mda delete로 배포를 삭제하면 이와 연관된 관리 샌드박스, {deployment}--setup-* 레시피 스냅샷, 존재하는 경우 배포 소유 레지스트리도 삭제됩니다.

배포 (Deployment)

Managed Deep Agents는 샌드박스 이름 지정, 레시피 베이크, 재사용, 복구, 정리를 소유합니다. 각 영구 스레드는 현재 레시피 스냅샷에서 복제된 자체 샌드박스를 얻습니다. 플랫폼 수준 수명주기 세부정보는 샌드박스를 참고하세요.

샌드박스를 사용할 때 (When to use a sandbox)

목표 (Goal) 사용 (Use)
격리된 상태에서 파일 쓰기, 코드 실행 또는 셸 명령 실행 샌드박스
스레드 간 영구 지식 저장 메모리
파일시스템 없는 항상 켜져 있는 동작 지시사항

자세한 내용은 프로젝트 구조를 참고하세요.

더 알아보기 (Learn more)