diff --git a/skills/plz-3d-explain/assets/example-agent-sandbox.en.html b/skills/plz-3d-explain/assets/example-agent-sandbox.en.html index 80a2f17..cfe12f8 100644 --- a/skills/plz-3d-explain/assets/example-agent-sandbox.en.html +++ b/skills/plz-3d-explain/assets/example-agent-sandbox.en.html @@ -390,17 +390,17 @@
You also have to decide when to create a sandbox and when to clear it away. One common design is to keep one sandbox per conversation. The sandbox is created the first time the code execution tool is called in the conversation, and later turns reuse the same sandbox. That way, variables made in an earlier turn are still there in the next turn.
-If there are no calls for a while, the sandbox is reclaimed to give back its resources. Instead of deleting it, you can also pause it. The memory and disk state is saved as a snapshot and revived on the next call. For example, the E2B documentation says a paused sandbox keeps its file system and memory together, and that reviving it takes about 1 second.
+You also have to decide when to create a sandbox and when to clear it away. One common design is to keep one sandbox per conversation. The sandbox is created the first time the code execution tool is called in the conversation, and later turns reuse the same sandbox. Reusing the sandbox alone does not make Python variables persist. This example assumes the same Python process, or interpreter execution context, stays alive across turns. If a new Python process starts on each turn, its variables are lost even inside the same VM or container. Files can remain in the sandbox file system, but variables live in process memory.
+If there are no calls for a while, the sandbox is reclaimed to give back its resources. Instead of deleting it, you can also pause it. If the file system and the memory of the running process are saved in a snapshot and then revived, the variables in the same interpreter can continue too. Restoring only the file system or starting a new Python process does not restore those variables. For example, the E2B documentation says a paused sandbox keeps its file system and memory together, and that reviving it takes about 1 second.
There is also an upper limit on how many sandboxes can run at the same time. Once the limit is reached, new requests wait until a slot opens. The model below is an example with a limit of 3 and an idle time of 30 minutes. These numbers are values chosen for the explanation.
# Turn 1: create a new sandbox and read a spreadsheet
df = pd.read_excel("/work/sales.xlsx")
-# Turn 2: same sandbox, so df is still there
+# Turn 2: same Python process, so df is still there
pivot = df.pivot_table(index="month", values="amount")
# 30 minutes later: pause and save a snapshot
-# Turn 3: after reviving, keep using df and pivot
- A sandbox has a lifetime: it is created, reused, paused, revived, and cleared away. Keeping state is more convenient, but it holds resources for longer.
+# Turn 3: after restoring process memory, keep using df and pivot +Files live in the sandbox file system; variables live in Python process memory. To keep using variables, reuse the same interpreter or restore that process memory.
샌드박스를 언제 만들고 언제 치울지도 정해야 합니다. 흔한 설계 하나는 대화마다 샌드박스를 하나씩 두는 것입니다. 대화에서 코드 실행 도구가 처음 불릴 때 샌드박스를 만들고, 이후 턴에서는 같은 샌드박스를 다시 씁니다. 그러면 앞 턴에서 만든 변수가 다음 턴에도 남아 있습니다.
-한동안 호출이 없으면 샌드박스를 거둬 자원을 돌려받습니다. 지우는 대신 멈춰 둘 수도 있습니다. 메모리와 디스크 상태를 스냅샷으로 저장했다가 다음 호출 때 되살리는 것입니다. 예를 들어 E2B 문서는 멈춘 샌드박스가 파일 시스템과 메모리를 함께 보관하고, 되살리는 데 약 1초가 걸린다고 적습니다.
+샌드박스를 언제 만들고 언제 치울지도 정해야 합니다. 흔한 설계 하나는 대화마다 샌드박스를 하나씩 두는 것입니다. 대화에서 코드 실행 도구가 처음 불릴 때 샌드박스를 만들고, 이후 턴에서는 같은 샌드박스를 다시 씁니다. 다만 샌드박스를 재사용한다고 파이썬 변수가 자동으로 남는 것은 아닙니다. 이 예시는 같은 Python 프로세스, 즉 같은 인터프리터 실행 문맥을 턴 사이에 계속 쓰는 경우입니다. 매 턴 새 Python 프로세스를 시작하면 같은 VM이나 컨테이너 안이어도 변수는 사라집니다. 파일은 샌드박스 파일 시스템에 남을 수 있지만, 변수는 프로세스 메모리에 있습니다.
+한동안 호출이 없으면 샌드박스를 거둬 자원을 돌려받습니다. 지우는 대신 멈춰 둘 수도 있습니다. 파일 시스템과 실행 중인 프로세스의 메모리를 스냅샷으로 저장했다가 다음 호출 때 되살리면, 같은 인터프리터의 변수도 이어집니다. 파일 시스템만 복원하거나 새 Python 프로세스를 시작하면 변수는 복원되지 않습니다. 예를 들어 E2B 문서는 멈춘 샌드박스가 파일 시스템과 메모리를 함께 보관하고, 되살리는 데 약 1초가 걸린다고 적습니다.
동시에 띄울 수 있는 샌드박스 수에도 상한을 둡니다. 상한이 차면 새 요청은 자리가 날 때까지 기다립니다. 아래 모형은 상한 3개, 유휴 시간 30분으로 정한 예입니다. 이 숫자는 설명을 위한 값입니다.
# 턴 1: 샌드박스를 새로 만들고 표를 읽는다
df = pd.read_excel("/work/sales.xlsx")
-# 턴 2: 같은 샌드박스라 df가 그대로 있다
+# 턴 2: 같은 Python 프로세스라 df가 그대로 있다
pivot = df.pivot_table(index="month", values="amount")
# 30분 뒤: 멈추고 스냅샷 저장
-# 턴 3: 되살린 뒤 df, pivot을 이어서 쓴다
- 샌드박스는 만들고, 다시 쓰고, 멈추고, 되살리고, 치우는 수명을 가집니다. 상태를 남길수록 편하지만 자원을 오래 잡습니다.
+# 턴 3: 프로세스 메모리까지 복원한 뒤 df, pivot을 이어서 쓴다 +파일은 샌드박스의 파일 시스템에, 변수는 Python 프로세스 메모리에 있습니다. 변수까지 이어 쓰려면 같은 인터프리터를 재사용하거나 그 프로세스 메모리를 복원해야 합니다.