[ParidelPooya]

Twin PR: aws/aws-durable-execution-sdk-js#1217

Changes since review

These commits address the review from yaythomas:

1. e803fe3c fix(extras): end AgentCore calls before reserve. InvokeAgentRuntime (with the answer read) and StopRuntimeSession now run through call_before_deadline with the remaining Lambda time, as the MicroVM calls do. A call that has not ended 10 seconds before the invocation times out fails its attempt with a retryable TimeoutError. So a stalled stop no longer hides a recorded result.

2. a23f55b3 fix(worker): commit AgentCore job start atomically, simplified in 2fda8b46, and reworked in 7bae717f after the second review. The worker starts the job's thread before it answers. The thread waits on an event before it runs the handler, and the event is set after the HTTP 200 is written. So a handler that holds the GIL does not delay the answer. A failed Thread.start() forgets the callback ID and answers 500, and a later delivery of the same job can run it. Thread creation can fail under resource exhaustion in a valid deployment, so this is code, not a rule. The lock around the start from a23f55b3 is not restored. So a duplicate request that arrives while a start fails can still get 200. In that case the durable function fails at its heartbeat timeout.

3. d816c770 feat(extras): record AgentCore operation subtypes. AgentcoreOperationSubType has the same five values as the JS twin (Agentcore, AgentcoreSessionId, AgentcoreCallback, AgentcoreRequest, AgentcoreStop). The operation passes them through ChildConfig, StepConfig, and CallbackConfig. Custom subtypes arrived in core SDK 3.0.0. So the extras package now requires aws-durable-execution-sdk-python>=3.0.0,<4. It required >=2.0.0 before. The extras package has no release yet.

4. 3f5bb652 docs(extras): qualify AgentCore dedup per process. The docstrings and both READMEs now say this: dedup holds per worker process, delivery is at-least-once across process replacement, and handler side effects must be idempotent.

5. 7f456339 test(examples): add an AgentCore cloud scenario. The examples package gets the AgentCore Run Job example, its cloud-only test, and the agent agentcore-agent/app.py. The wiring follows the MicroVM examples, as described in "CI dependency" below.

6. 2fda8b46 also adds a "Rules for AgentCore jobs" section to the extras and compute-worker READMEs. The SDK does not guard developer configuration. So each rule names the setting that the developer owns. 7bae717f reworded rule 1: the first heartbeat period starts before the job is delivered, so heartbeat_timeout must cover the request step with its retries and a cold session start (1.4 to 3.1 seconds in the live test), and 30 seconds or more is a safe value. It also added rule 6: a function timeout of at least 11 seconds. The heartbeat_timeout docstring has the matching note.

7. 7bae717f runs the MicroVM preflight require_time_for_call before each AgentCore call. With less than 11 seconds left in the invocation, the attempt makes no API call and fails with a message that asks for a longer function timeout. The default retry strategy retries that error, as in MicroVM. The stop failure log names the missing permission only for an AccessDenied answer.

Public API added since review: AgentcoreOperationSubType in extras.

CI dependency

The cloud scenario runs only when CI provides an agent runtime. This PR does not change CI infrastructure or any CI workflow. So the test is skipped in CI until these exist:

1. An agent runtime in the CI test account whose entry point is packages/aws-durable-execution-sdk-python-examples/agentcore-agent/app.py, with the compute-worker package installed.
2. On the agent runtime's execution role: lambda:SendDurableExecutionCallbackSuccess, lambda:SendDurableExecutionCallbackFailure, and lambda:SendDurableExecutionCallbackHeartbeat on the example function.
3. On the examples' function role (LambdaExecutionRoleArn): bedrock-agentcore:InvokeAgentRuntime and bedrock-agentcore:StopRuntimeSession on the agent runtime ARN and on <runtime ARN>/runtime-endpoint/*.
4. In cloud-tests.yml: pass the runtime ARN to sam deploy as AgentRuntimeArn, and pass --include-agentcore to generate_function_name_map.py.

The wiring works like the MicroVM examples:

• The catalog flag usesAgentcore gives the function and its log group the condition HasAgentRuntime. The condition holds only when the template parameter AgentRuntimeArn is set. Its default is empty.
• The function receives the ARN as AGENT_RUNTIME_ARN.
• generate_function_name_map.py leaves the example out unless --include-agentcore is passed. The conftest skips a test whose example is missing from the map.

So a deploy without the parameter leaves the example out of the stack, and the test is skipped.

Issue #, if available

None.

What

This PR adds a first version of a compute operation for Amazon Bedrock AgentCore Runtime. It has two parts.

1. The extras package gets aws_durable_execution_sdk_python_extras.compute.agentcore. Its operation agentcore(context, name, *, job_input, config) runs one job in a new AgentCore Runtime session and returns the job's result.
2. The compute-worker package gets aws_durable_execution_sdk_python_compute_worker.agentcore. Its entry start_agentcore_worker(handler=..., logger=None) serves the AgentCore Runtime HTTP contract in the agent's container.

Both modules are experimental, like microvm.

Why

AgentCore Runtime runs agent code in an isolated session that the developer deploys outside the durable function. A durable function can send that code a job and wait on a durable callback for the result. The function invocation then ends during the wait, so Lambda bills no compute while the agent works. Today a developer must write that flow and the worker side by hand.

Design

Problem: a durable function cannot run a job on AgentCore Runtime and wait for its result without hand-written code on both sides.

Cause: the SDK has a compute operation only for Lambda MicroVMs.

Options considered:

1. A new compute type under compute/agentcore that follows the microvm flow. Chosen. AgentCore Runtime has the same shape as a MicroVM: the compute is defined outside the function, one request delivers the job, and the agent reports through the durable callback APIs. So the operation reuses the callback flow, the job document, the error base class ComputeError, and the worker's callback reporter and heartbeats.
2. A generic HTTP-callback operation that POSTs a job document to any endpoint. Rejected. AgentCore needs a signed InvokeAgentRuntime call, a session ID, and a StopRuntimeSession call at the end. A generic operation would need hooks for each of these. That is more configuration than one compute type.
3. No SDK support, with a documented pattern instead. Rejected. Each developer would rewrite the session step, the stop on failure, and the worker's deduplication. The deduplication is required for correctness (see Behavior).

One job per session in this iteration: a session that runs several jobs (agentcoreSession) needs a rule for waits between jobs. An idle session ends at the agent runtime's idleRuntimeSessionTimeout and loses its memory and files. That behavior needs a live probe first. So this PR builds only the one-job operation.

This PR removes no code.

Change

Extras (compute/agentcore/):

• config.py: AgentcoreConfig with agent_runtime_arn, timeout, qualifier, heartbeat_timeout, retry_strategy, client.
• operation.py: agentcore(), and AgentcoreNotAcceptedError for an answer other than {"accepted": true}.
• errors.py: AgentcoreError(ComputeError), AgentcoreDeliveryError, AgentcoreJobFailedError, AgentcoreTimeoutError. Each class is registered with the SDK error registry, like the MicroVM errors.
• job.py: the job document {version, region, callbackId, heartbeatTimeoutSeconds?, input}. It is the MicroVM job request without microvmId.
• retry.py: default_agentcore_retry_strategy.

Worker (agentcore/worker.py): start_agentcore_worker, AgentcoreWorker, AgentcoreJobContext, AgentcoreJobHandler. It imports the callback reporter, heartbeats, logger, job parser, and the request reader _Exchange from the microvm subpackage. No module moves in this PR.

Other files: README sections in both packages, boto3-stubs[bedrock-agentcore] in the root types and dev-extras environments, and a comment on the boto3 bound of the extras package.

Public API members added: 10 in extras (agentcore, AgentcoreConfig, the 4 error classes, AgentcoreNotAcceptedError, default_agentcore_retry_strategy, and re-exports of ComputeError and MAX_JOB_INPUT_BYTES) and 11 in the worker (start_agentcore_worker, AgentcoreWorker, AgentcoreJobContext, AgentcoreJobHandler, default_host, AGENTCORE_HOST, LOCAL_HOST, RUNTIME_URL_ENV, AGENTCORE_PORT, INVOCATIONS_PATH, PING_PATH). Source lines added: about 1,500, half of them docstrings.

Behavior

Flow, in one child context named name:

1. <name>.session generates the runtime session ID, a UUID of 36 characters. InvokeAgentRuntime requires at least 33. The step checkpoints the ID. So every retry and replay uses the same session.
2. <name>.callback creates the durable callback with timeout and heartbeat_timeout.
3. <name>.request calls InvokeAgentRuntime with agentRuntimeArn, runtimeSessionId, the optional qualifier, contentType: application/json, and the job document as payload. The step reads at most 64 KiB of the response stream and closes it. An answer other than {"accepted": true} fails the step without a retry, and the operation raises AgentcoreDeliveryError.
4. The child context waits on the callback.
5. <name>.stop calls StopRuntimeSession with the same ARN, session ID, and qualifier.

Stop on failure: the stop step runs after success, job failure, timeout, and a failed delivery. A failed stop is logged as an error and does not hide the job's result or error. ResourceNotFoundException from stop counts as stopped. An ExecutionError and a retryable InvocationError of the wait pass through without a stop, as in microvm.

Dedup rule: InvokeAgentRuntime has no idempotency token. So a retried request step can deliver the same job twice to the same session. The worker remembers every callback ID that it accepted (running, and the last 1,000 finished), in process memory only. It answers a repeated ID with {"accepted": true} and does not run the job again. A retry can arrive after the idle timeout replaced the session's process. The new process then runs the job again. So delivery is at-least-once across process replacement, and handler side effects must be idempotent.

Invocation reserve: each InvokeAgentRuntime and StopRuntimeSession call must end 10 seconds before the Lambda invocation times out. A call that has not ended by then fails its step attempt with a retryable TimeoutError.

Subtypes: the child context and the four inner operations record the five AgentcoreOperationSubType values.

Worker:

• POST /invocations parses the job document and checks version. A document that does not match gets HTTP 400. The worker starts a new job's thread, and then answers {"accepted": true}. The thread runs the handler only after the answer is written. A thread that cannot start gets HTTP 500, and the callback ID is forgotten.
• GET /ping answers {"status": "HealthyBusy"} while a job runs or reports, and {"status": "Healthy"} otherwise. The answer always carries time_of_last_update: the Unix time in seconds of the worker's start or of the last change between the two statuses. It does not change between pings with the same status. The AgentCore docs call the field optional. The issue docs: /ping response requires undocumented time_of_last_update field — without it AgentCore silently reaps microVMs even when status is HealthyBusy bedrock-agentcore-sdk-python#471 reports that a HealthyBusy session without it can end at the idle timeout.
• The worker listens on port 8080 by default. The default host depends on the environment:
  1. The AgentCore Runtime HTTP contract requires 0.0.0.0 inside the runtime. The runtime publishes no port, and AgentCore authorizes each InvokeAgentRuntime caller with IAM before it forwards the request.
  2. The worker has no authentication. So outside AgentCore, a bind on all interfaces would let any machine on the network send it a job.
  3. The live test found AGENTCORE_RUNTIME_URL set in a runtime with direct code deployment, and no /.dockerenv file or DOCKER_CONTAINER variable.
  4. So the worker listens on 0.0.0.0 when AGENTCORE_RUNTIME_URL is set, and on 127.0.0.1 otherwise. An explicit host argument overrides both.
• A job whose heartbeats cannot start fails its callback, as in the MicroVM worker. The job then does not wait for its heartbeat timeout.
• The server listens with a backlog of 511, as the MicroVM worker does. The default backlog of 5 reset concurrent connections in a review probe.

Permissions

• Durable function's execution role: bedrock-agentcore:InvokeAgentRuntime and bedrock-agentcore:StopRuntimeSession on two resources: the agent runtime ARN, and <runtime ARN>/runtime-endpoint/*. The live test denied both calls on <runtime ARN>/runtime-endpoint/DEFAULT with a policy that named only the runtime ARN. To allow one endpoint only, name the endpoint of qualifier instead of *.
• Agent runtime's execution role: lambda:SendDurableExecutionCallbackSuccess, lambda:SendDurableExecutionCallbackFailure, and lambda:SendDurableExecutionCallbackHeartbeat on the function ARN.

Idle timeout: while a job runs, the worker answers /ping with HealthyBusy, so the agent runtime's 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. This operation sends one job per session, so the loss cannot affect a job.

Assumptions

• The request and response shapes of InvokeAgentRuntime and StopRuntimeSession come from the installed botocore 1.44.0 model. A test sends both calls through a real boto3 client with botocore.stub.Stubber, which validates the parameters against that model. The response response member is a streaming blob in the model.
• botocore 1.40.46 is the first release with StopRuntimeSession, checked by installing releases in a venv. The current bound boto3>=1.43.35 is newer. So the bound does not change.
• The host 0.0.0.0, port 8080, /invocations, and /ping come from the AgentCore Runtime HTTP protocol contract in the AWS docs.
• Verified live: AgentCore forwards the payload to /invocations unchanged, with the session ID header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id. The handler saw the session ID that <name>.session checkpointed.
• Verified live: HealthyBusy with time_of_last_update set only on a status change kept a session through a 180-second job with an idle timeout of 60 seconds.
• Verified live: StopRuntimeSession answers 404 ResourceNotFoundException for a stopped or never-started session, and 200 for a session that the idle timeout ended.
• Verified live: AGENTCORE_RUNTIME_URL is set in a runtime with direct code deployment. Unverified: that a container deployment sets it too. A container deployment without it binds 127.0.0.1 and must pass host=AGENTCORE_HOST.

Decisions not covered by the issue or the design note

• The job document carries region, as the MicroVM job request does. The agent runtime can run in another Region than the function, and the worker needs the function's Region for the callback calls.
• timeout must be at least 1 second and has no upper bound. A microVM session lives at most 8 hours, but AgentCore Instances sessions can live up to 14 days. So the docstring tells the developer to keep the timeout within the runtime's maxLifetime.
• The request sets accept: application/json.
• The default client has a 60-second read timeout instead of the MicroVM client's 30 seconds, because the first request of a session starts the session.
• default_agentcore_retry_strategy retries ThrottlingException, InternalServerException, RetryableConflictException, HTTP 429 and 5xx, and connection errors, with at most 5 attempts.
• A 400 from the worker for a bad document does not fail the callback. The live test showed that AgentCore returns it as RuntimeClientError (HTTP 424), which is not retried. So the function fails at once with AgentcoreDeliveryError.
• The default host comes from AGENTCORE_RUNTIME_URL, not from the Docker markers that the AgentCore SDK for Python uses, because the live runtime had no Docker markers.
• The new test files have an agentcore_ prefix, because mypy rejects two test modules with the same name, such as microvm/errors_test.py and agentcore/errors_test.py.
• Failed AgentCore calls do not get the request ID in the message. The MicroVM helper for that is typed to the MicroVM operations. Listed as a follow-up.

Out of scope / follow-ups

• agentcore_session: several jobs in one session.
• Streaming responses, OAuth/JWT inbound auth, custom headers.
• Move the shared worker modules (callback reporter, heartbeats, logger, job parser, request reader) from compute_worker/microvm to the top level of compute_worker.
• Request IDs of failed AgentCore calls in the error message, as for MicroVM calls.
• CI infrastructure for the AgentCore cloud scenario (see "CI dependency").
• Publishing changes.

Testing

Since review (Python 3.13, uv venv, the same packages plus the examples package):

• AgentCore tests at 7bae717f: 93 passed (was 84). The new ones cover a stalled request that ends before the reserve and is retried, a stalled request that fails the delivery with the reserve error, a stalled stop that does not hide the result, the call without a deadline outside Lambda, the subtype history assertion, the handler starting only after the answer is written, a thread start failure that answers 500 and lets a later delivery run, an invocation with 3 seconds left that makes no call and logs no permission hint, the permission hint for a denied stop, and the retry of the time preflight.
• Examples: 213 passed, 7 skipped (the cloud-only tests). The new AgentCore example parts and the generator tests pass. In cloud mode without the map entry, the AgentCore test is skipped.
• Mutations that now fail a test: no reserve in the shared helper, no reserve on the request call, no reserve on the stop call, no handler gate, a 200 instead of a 500 on a failed start, the callback ID kept after a failed start, no time preflight, the permission hint always or never added, the preflight error not retried, each of the five subtypes removed, and each generator branch removed (condition, environment variable, resource condition, parameter, map filter).
• Full extras, compute-worker, and examples suites at 7bae717f: 1,359 passed, 7 skipped, 1 failed. The failure is microvm/callback_reporter_test.py::test_create_raises_when_boto3_cannot_build_the_client, which fails the same way on the base commit in this environment.
• mypy: no issues in extras (48 files) and compute-worker (20 files). hatch fmt --check (hatch 1.16.5): clean in extras, compute-worker, and examples. lintcommit.py: pass for all 7 commits.

Before review:

Python 3.13, uv venv with the core, testing, extras, and compute-worker packages installed in editable mode.

• New tests: 84 passed (32 worker, 52 extras: operation, errors, and a composed test of the operation with the real worker in one process). Line and branch coverage of the new modules: 100% (489 statements, 74 branches).
• Mutations from the review now fail a test: no 64 KiB read limit, the dedup check outside the lock, a changed default host, a changed default port, and a backlog of 5.
• Full extras and compute-worker suites: 993 passed, 0 failed (pytest -n 4).
• mypy: no issues in extras (35 files) and compute-worker (20 files).
• hatch fmt --check with hatch 1.16.5: clean in every package.
• lintcommit.py: pass.

No existing test expectation changed. The extras conftest.py only gains a fake bedrock-agentcore client.

Live test

The operation and the worker of the first commit ran against live AgentCore Runtime agents in us-east-1, deployed with direct code deployment (PYTHON_3_13), idle timeout 60 seconds. The JS twin ran the same scenarios.

#	Scenario	Python	JS
1	Short job (5 s)	PASS: result returned, stop ran, session gone	PASS
2	Failing job	PASS: AgentcoreJobFailedError, stop ran	PASS
3	180-second job, idle timeout 60 s	PASS: succeeded after 187 s in the same process	PASS
4a	Worker crash, heartbeat timeout 30 s	PASS: AgentcoreTimeoutError 30 s after delivery, stop ran	PASS
4b	Handler with long synchronous work	n/a: each job runs in its own thread	FAIL, fixed in the JS twin: the accept answer came after the handler's synchronous part
5	Duplicate delivery	PASS: both answers {"accepted":true}, the handler ran once	PASS
6	Stop of an ended session	PASS: the service answers 404, the stop step succeeds and logs no error	PASS

Measurements:

• Cold start, the first invoke of a new session: 1.4 to 3.1 s. Warm invoke: 146 to 253 ms. Both runtimes together.
• StopRuntimeSession on an ended or never-started session answers 404 ResourceNotFoundException. The operation treats it as stopped.
• A worker 400 for a bad document surfaces as RuntimeClientError (HTTP 424). The default retry strategy does not retry it.
• After the idle timeout, the same session ID gets a new microVM without an error.
• A policy with only the runtime ARN was denied on the runtime endpoint resource. This PR now documents the endpoint resource.

The fix commit (bind default, heartbeat start failure, backlog, docs) and the commits since review have unit tests only. They have not run live.

Checklist

• Every new branch has a test that fails without it (rule 4)
• For a bug fix: the first commit adds a test that fails on the current code (rule 5). Not a bug fix.
• Every edited test expectation is listed in the description, with the reason (rule 5). None.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.