From 29df604fd62cb6615fd146a7e484520167a65280 Mon Sep 17 00:00:00 2001 From: Aaqibhafeez Khan Date: Wed, 18 Nov 2026 07:35:43 +0530 Subject: [PATCH] docs(plz-3d-explain): clarify Python state persistence --- .../assets/example-agent-sandbox.en.html | 20 +++++++++---------- .../assets/example-agent-sandbox.html | 20 +++++++++---------- 2 files changed, 20 insertions(+), 20 deletions(-) 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 @@

For example

9A day in the life of a sandbox

-

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.

For example

# 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.

@@ -1514,16 +1514,16 @@

Sources (checked 2026-10-28)

sheet.position.y = sheetY + 2; sheet.scale.setScalar(1); sheet.visible = true; await a.move(sheet, [sheet.position.x, sheetY, sheet.position.z], 600); await a.scaleTo(df, 1, 500); - say('Turn 1: it read the file into a table (df). All 3 slots are now full.'); + say('Turn 1: the same Python process read the file into a table (df). All 3 slots are now full.'); await a.wait(1100); say('Chat D also needs a sandbox, but the limit is reached, so it waits.'); await a.scaleTo(D, 1, 600); await a.wait(1100); - say('Turn 2: in chat A, it computes a pivot. The df from the previous turn is still there.'); + say('Turn 2: the same Python process is reused to compute a pivot. df remains in process memory; it would be gone if a new process had started.'); await a.flash(df, COLOR.actor, 600); await a.scaleTo(pivot, 1, 500); await a.wait(1100); - say('Chat A had no calls for 30 minutes. The sandbox was paused and its state saved as a snapshot.'); + say('Chat A had no calls for 30 minutes. The file system and the running Python process memory were saved in a snapshot.'); snap.visible = true; snap.scale.setScalar(0.001); await Promise.all([a.scaleTo(A, 0.001, 700), a.scaleTo(snap, 1, 700)]); A.visible = false; @@ -1536,11 +1536,11 @@

Sources (checked 2026-10-28)

await a.scaleTo(D, 0.001, 600); D.visible = false; await a.wait(600); - say('Turn 3: the user asks in chat A again. The saved snapshot is revived.'); + say('Turn 3: the user asks in chat A again. The snapshot, including process memory, is revived.'); await a.move(snap, [slot0.x, FLOOR + 0.07, slot0.z], 800, 1.2); await Promise.all([a.scaleTo(snap, 0.001, 600), a.scaleTo(A, 1, 700)]); snap.visible = false; - say('Turn 3: df and pivot came back as they were. It continued the computation instead of reading everything again.'); + say('Turn 3: df and pivot came back with process memory. The same interpreter continued the computation.'); }, }; }, diff --git a/skills/plz-3d-explain/assets/example-agent-sandbox.html b/skills/plz-3d-explain/assets/example-agent-sandbox.html index cdfe8ff..f68a59b 100644 --- a/skills/plz-3d-explain/assets/example-agent-sandbox.html +++ b/skills/plz-3d-explain/assets/example-agent-sandbox.html @@ -390,17 +390,17 @@

예를 들면

9샌드박스의 하루

-

샌드박스를 언제 만들고 언제 치울지도 정해야 합니다. 흔한 설계 하나는 대화마다 샌드박스를 하나씩 두는 것입니다. 대화에서 코드 실행 도구가 처음 불릴 때 샌드박스를 만들고, 이후 턴에서는 같은 샌드박스를 다시 씁니다. 그러면 앞 턴에서 만든 변수가 다음 턴에도 남아 있습니다.

-

한동안 호출이 없으면 샌드박스를 거둬 자원을 돌려받습니다. 지우는 대신 멈춰 둘 수도 있습니다. 메모리와 디스크 상태를 스냅샷으로 저장했다가 다음 호출 때 되살리는 것입니다. 예를 들어 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 프로세스 메모리에 있습니다. 변수까지 이어 쓰려면 같은 인터프리터를 재사용하거나 그 프로세스 메모리를 복원해야 합니다.

@@ -1514,16 +1514,16 @@

출처 (2026-10-28 확인)

sheet.position.y = sheetY + 2; sheet.scale.setScalar(1); sheet.visible = true; await a.move(sheet, [sheet.position.x, sheetY, sheet.position.z], 600); await a.scaleTo(df, 1, 500); - say('턴 1: 파일을 읽어 표(df)로 만들었습니다. 자리 3개가 모두 찼습니다.'); + say('턴 1: 같은 Python 프로세스에서 파일을 읽어 표(df)로 만들었습니다. 자리 3개가 모두 찼습니다.'); await a.wait(1100); say('대화 D도 샌드박스가 필요하지만, 상한이 차서 기다립니다.'); await a.scaleTo(D, 1, 600); await a.wait(1100); - say('턴 2: 대화 A에서 피벗을 계산합니다. 앞 턴의 df가 그대로 남아 있습니다.'); + say('턴 2: 같은 Python 프로세스를 재사용해 피벗을 계산합니다. df는 프로세스 메모리에 남아 있습니다. 새 프로세스를 시작했다면 df는 사라졌을 것입니다.'); await a.flash(df, COLOR.actor, 600); await a.scaleTo(pivot, 1, 500); await a.wait(1100); - say('대화 A에서 30분 동안 호출이 없었습니다. 샌드박스를 멈추고 상태를 스냅샷으로 저장했습니다.'); + say('대화 A에서 30분 동안 호출이 없었습니다. 파일 시스템과 실행 중인 Python 프로세스의 메모리를 스냅샷으로 저장했습니다.'); snap.visible = true; snap.scale.setScalar(0.001); await Promise.all([a.scaleTo(A, 0.001, 700), a.scaleTo(snap, 1, 700)]); A.visible = false; @@ -1536,11 +1536,11 @@

출처 (2026-10-28 확인)

await a.scaleTo(D, 0.001, 600); D.visible = false; await a.wait(600); - say('턴 3: 사용자가 대화 A에서 다시 묻습니다. 저장해 둔 스냅샷을 되살립니다.'); + say('턴 3: 사용자가 대화 A에서 다시 묻습니다. 프로세스 메모리까지 포함한 스냅샷을 되살립니다.'); await a.move(snap, [slot0.x, FLOOR + 0.07, slot0.z], 800, 1.2); await Promise.all([a.scaleTo(snap, 0.001, 600), a.scaleTo(A, 1, 700)]); snap.visible = false; - say('턴 3: df와 pivot이 그대로 돌아왔습니다. 처음부터 다시 읽지 않고 이어서 계산했습니다.'); + say('턴 3: df와 pivot이 프로세스 메모리와 함께 돌아왔습니다. 같은 인터프리터에서 계산을 이어 갔습니다.'); }, }; },