E2B 샌드박스 도구

E2B 샌드박스 도구 (E2B Sandbox Tools)

E2BExecTool, E2BPythonTool, E2BFileTool은 CrewAI 에이전트에게 격리되고 일시적인 E2B 원격 샌드박스 안에서 셸·Python·파일시스템 접근권을 부여합니다.

출처: 문서

본문

설명 (Description)

E2B 샌드박스 도구들은 CrewAI 에이전트가 E2B가 호스팅하는 격리되고 일시적인 VM에서 코드를 실행할 수 있게 해줍니다. 세 가지 도구가 공통 베이스 클래스와 연결 모델을 공유합니다:

E2BExecTool — 셸 명령 실행.
E2BPythonTool — Jupyter 스타일 코드 인터프리터에서 Python 실행(stdout, stderr, 그리고 차트·데이터프레임·HTML·SVG·PNG 같은 리치 결과를 반환).
E2BFileTool — 파일시스템 작업(읽기, 쓰기, 추가, 목록, 삭제, mkdir, info, exists), base64를 통한 바이너리 콘텐츠 포함.

호스트 환경을 노출하지 않고 에이전트에게 임의 코드 실행이나 파일 작업 능력을 주고 싶을 때 이 도구들을 사용하세요.

설치 (Installation)

crewai-tools의 e2b 엑스트라를 설치하고 E2B API 키를 설정하세요:

uv add "crewai-tools[e2b]"

export E2B_API_KEY="e2b_..."

도구 (Tools)

`E2BExecTool`

sandbox.commands.run을 통해 샌드박스 안에서 셸 명령을 실행합니다.

인자 (Arguments)

command: str — 필수. 실행할 셸 명령.
cwd: str | None — 선택. 명령의 작업 디렉터리.
envs: dict[str, str] | None — 선택. 호출별 환경 변수.
timeout: float | None — 선택. 타임아웃(초).

반환값 (Returns)

{
  "exit_code": 0,
  "stdout": "...",
  "stderr": "...",
  "error": null
}

`E2BPythonTool`

e2b_code_interpreter SDK를 사용해 Jupyter 스타일 코드 인터프리터에서 Python 코드를 실행합니다.

인자 (Arguments)

code: str — 필수. 실행할 코드.
language: str | None — 선택. 언어 식별자(기본값 Python).
envs: dict[str, str] | None — 선택. 호출별 환경 변수.
timeout: float | None — 선택. 타임아웃(초).

반환값 (Returns)

{
  "text": "...",
  "stdout": "...",
  "stderr": "...",
  "error": null,
  "results": [],
  "execution_count": 1
}

results에는 셀이 생성한 차트, 데이터프레임, HTML, SVG, PNG 출력이 포함될 수 있습니다.

`E2BFileTool`

샌드박스 안에서 파일시스템 작업을 수행합니다. 쓰기 시 부모 디렉터리를 자동 생성하며 base64로 바이너리 콘텐츠를 처리합니다.

인자 (Arguments)

action: "read" | "write" | "append" | "list" | "delete" | "mkdir" | "info" | "exists" — 필수.
path: str — 필수. 샌드박스 안의 대상 경로.
content: str | None — 선택. write / append의 콘텐츠. binary=True일 때 base64로 인코딩.
binary: bool — 선택. content를 바이너리(base64)로 취급. 기본값 False.
depth: int — 선택. list의 재귀 깊이.

공통 파라미터 (`E2BBaseTool`)

세 도구 모두 동일한 연결/수명주기 파라미터를 받습니다:

api_key: SecretStr | None — E2B_API_KEY 환경 변수로 대체.
domain: str | None — E2B_DOMAIN 환경 변수로 대체.
template: str | None — 커스텀 샌드박스 템플릿 또는 스냅샷.
persistent: bool — 기본값 False. Sandbox modes 참고.
sandbox_id: str | None — 기존 샌드박스에 연결.
sandbox_timeout: int — 유휴 타임아웃(초). 기본값 300.
envs: dict[str, str] | None — 샌드박스 생성 시 주입되는 환경 변수.
metadata: dict[str, str] | None — 샌드박스 생성 시 첨부되는 메타데이터.

샌드박스 모드 (Sandbox modes)

모드	활성화 방법	샌드박스 수명
Ephemeral (기본값)	`persistent=False`	매 `_run` 호출마다 새 샌드박스가 생성되고 종료됩니다.
Persistent	`persistent=True`	첫 호출에서 지연 생성되고 `atexit`로 프로세스 종료 시 종료됩니다.
Attach	`sandbox_id="sbx_..."`	기존 샌드박스에 연결되며 절대 종료하지 않습니다.

일회성 작업에는 ephemeral 모드를 사용하세요 — 폭발 반경(blast radius)을 최소화합니다. 에이전트가 여러 도구 호출에 걸쳐 상태를 유지해야 할 때(예: 셸 세션 + 동일 파일에 대한 파일시스템 작업)는 persistent 모드를 사용하세요. 외부 시스템이 샌드박스 수명주기를 관리할 때는 attach 모드를 사용하세요.

예제 (Examples)

일회성 Python (ephemeral)

from crewai_tools import E2BPythonTool

tool = E2BPythonTool()
result = tool.run(code="print(sum(range(10)))")

Persistent 셸 + 파일시스템 세션

from crewai_tools import E2BExecTool, E2BFileTool

exec_tool = E2BExecTool(persistent=True)
file_tool = E2BFileTool(persistent=True)

프로세스가 종료되면 두 도구가 atexit를 통해 샌드박스를 정리합니다.

기존 샌드박스에 연결하기

from crewai_tools import E2BExecTool

tool = E2BExecTool(sandbox_id="sbx_...")

연결한 샌드박스는 도구가 종료하지 않습니다.

커스텀 템플릿, 타임아웃, 환경 변수, 메타데이터

from crewai_tools import E2BExecTool

tool = E2BExecTool(
    persistent=True,
    template="my-custom-template",
    sandbox_timeout=600,
    envs={"MY_FLAG": "1"},
    metadata={"owner": "crewai-agent"},
)

전체 에이전트 예제

from crewai import Agent, Crew, Process, Task
from crewai_tools import E2BPythonTool

python_tool = E2BPythonTool()

analyst = Agent(
    role="Data Analyst",
    goal="Run Python in a sandbox to answer analytical questions",
    backstory="An analyst who delegates computation to an isolated E2B sandbox.",
    tools=[python_tool],
    verbose=True,
)

task = Task(
    description="Compute the mean of [1, 2, 3, 4, 5] and return the result.",
    expected_output="The numerical mean.",
    agent=analyst,
)

crew = Crew(agents=[analyst], tasks=[task], process=Process.sequential)
result = crew.kickoff()

보안 고려사항 (Security considerations)

이 도구들은 에이전트에게 샌드박스 안에서 임의의 셸·Python·파일시스템 접근권을 부여합니다. 샌드박스가 호스트로부터 실행을 격리하긴 하지만, 여전히 도구 출력을 신뢰할 수 없는 것으로 취급하고 프롬프트 인젝션을 염두에 두고 설계해야 합니다:

Ephemeral 모드가 주요 폭발 반경 통제 수단입니다 — 매 _run 호출마다 새 VM을 받습니다. 영속 상태가 필요하지 않다면 이를 선호하세요.
Persistent 및 attach 샌드박스는 호출을 넘나들며 상태가 누적됩니다. 그 안에 시드된 모든 것(자격 증명, 토큰, 파일)은 이후의 모든 도구 호출에서 접근 가능하며, 입력이 신뢰할 수 없는 콘텐츠의 영향을 받은 호출도 포함됩니다.
에이전트가 읽거나 유출할 수 있는 장수명 샌드박스에 비밀을 넣지 마세요. 단기 자격 증명과 필요한 최소 범위를 사용하세요.
sandbox_timeout은 유휴 시간을 제한하지만 총 실행 시간을 제한하지는 않습니다. 워크로드에 맞는 가장 작은 값으로 설정하세요.

더 알아보기 (Learn more)

Daytona Sandbox Tools — 다른 샌드박스 실행 도구 알아보기
AI & ML Tools 개요 — AI/ML 관련 도구 전체 살펴보기

E2B 샌드박스 도구