Skip to content

Commit 74a497d

Browse files
committed
docs(worker): document AgentCore sessions
Add a section to the compute-worker README. Jobs of one AgentCore session run in one worker process, so files on disk and values in memory carry over between jobs. The runtime idle timeout ends the session, and a later job then starts with fresh state. Closes #950
1 parent 84759fa commit 74a497d

1 file changed

Lines changed: 13 additions & 0 deletions

File tree

  • packages/aws-durable-execution-sdk-python-compute-worker

‎packages/aws-durable-execution-sdk-python-compute-worker/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -203,6 +203,19 @@ The worker remembers the callback IDs of accepted jobs only in its process memor
203203

204204
While a job runs, the worker answers `/ping` with `HealthyBusy`, so the agent runtime's idle timeout (`idleRuntimeSessionTimeout`) does not end the job. After the idle timeout, a session with no running job ends. A later request with the same session ID then gets a new microVM without an error, and the memory and files of the old one are lost. The `agentcore` operation sends one job per session, so this loss cannot affect a job.
205205

206+
### Several jobs in one session
207+
208+
A durable function can send several jobs to one AgentCore session. The worker runs every job of the session in the same process. So the jobs share state:
209+
210+
- Files that a job writes to disk stay there for the next job.
211+
- Values that a handler keeps in module-level variables stay in memory for the next job.
212+
213+
The worker clears no state between jobs. A handler that needs a clean start must clean up itself.
214+
215+
The state lasts until the agent runtime's idle timeout (`idleRuntimeSessionTimeout`) ends the session. The idle timeout counts only time with no running job. So a wait between two jobs that is longer than the idle timeout ends the session. The next job then gets a new microVM and a new process, and the files and memory of the old session are lost. The job still runs, without an error. So set the idle timeout longer than any wait between the jobs of one session.
216+
217+
The [extras README](https://github.com/aws/aws-durable-execution-sdk-python/tree/main/packages/aws-durable-execution-sdk-python-extras#run-a-job-in-agentcore-runtime) describes how a durable function sends jobs to AgentCore.
218+
206219
### Rules for AgentCore jobs
207220

208221
1. Set `heartbeat_timeout`. It ends the job when the worker crashes or stops reporting. The first heartbeat period starts when the callback is created, before the job is delivered. So it must cover the request step with its retries and a cold session start, which took 1.4 to 3.1 seconds in a live test. 30 seconds or more is a safe value.

0 commit comments

Comments
 (0)