feat(extras): run a job in AgentCore Runtime

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

@@ -2,7 +2,7 @@
 
 > This package is experimental. Its API can change in any release.
 
-The compute worker runs jobs from durable functions on compute that is defined outside the durable function. Each compute type has its own subpackage. Today the package has one subpackage: `aws_durable_execution_sdk_python_compute_worker.microvm`, the worker for AWS Lambda MicroVMs. The rest of this README describes the MicroVM worker.
+The compute worker runs jobs from durable functions on compute that is defined outside the durable function. Each compute type has its own subpackage: `aws_durable_execution_sdk_python_compute_worker.microvm`, the worker for AWS Lambda MicroVMs, and `aws_durable_execution_sdk_python_compute_worker.agentcore`, the worker for Amazon Bedrock AgentCore Runtime. The rest of this README describes the MicroVM worker, except the section [Run a job in AgentCore Runtime](#run-a-job-in-agentcore-runtime).
 
 Run jobs from a durable function inside an AWS Lambda MicroVM, and report each job's result to the durable function.
 
@@ -161,6 +161,59 @@ With `auto_suspend_on_idle`, the role also needs `lambda:SuspendMicrovm` on the
 
 The worker needs boto3 1.43.35 or later.
 
+## Run a job in AgentCore Runtime
+
+> The `agentcore` subpackage is experimental. Its API can change in any release.
+
+`start_agentcore_worker` serves the [AgentCore Runtime HTTP contract](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-http-protocol-contract.html) in the agent's container. It needs no dependency beyond this package.
+
+```python
+from aws_durable_execution_sdk_python_compute_worker.agentcore import (
+    AgentcoreJobContext,
+    start_agentcore_worker,
+)
+
+
+def review(job_input: dict, context: AgentcoreJobContext) -> dict:
+    context.logger.info("reviewing", extra={"pr": job_input["pr"]})
+    return {"approved": True, "comments": []}
+
+
+if __name__ == "__main__":
+    start_agentcore_worker(handler=review).wait()
+```
+
+The durable function sends the job with the `agentcore` operation of the [extras](https://github.com/aws/aws-durable-execution-sdk-python/tree/main/packages/aws-durable-execution-sdk-python-extras#run-a-job-in-agentcore-runtime) package:
+
+```python
+review = agentcore(context, "review", job_input={"pr": 7}, config=AGENT)
+```
+
+The worker listens on port 8080, because AgentCore Runtime sends its requests to that port. The host depends on where the worker runs:
+
+- Inside AgentCore Runtime, the `AGENTCORE_RUNTIME_URL` environment variable is set. The worker then listens on `0.0.0.0`, as the AgentCore contract requires. The runtime publishes no port, and AgentCore authorizes each `InvokeAgentRuntime` caller before it forwards the request.
+- Anywhere else, such as a laptop, the worker listens on `127.0.0.1`. The worker has no authentication, so it must not be reachable from the network.
+- A `host` argument overrides both.
+
+- `POST /invocations` reads the job document, starts the job's thread, and answers `{"accepted": true}` at once. The thread runs the handler only after the answer is written. A callback ID that the worker already accepted gets the same answer, and the job does not run again. A document that does not match the contract gets HTTP 400.
+- `GET /ping` answers `{"status": "HealthyBusy"}` while a job runs, and `{"status": "Healthy"}` otherwise. `time_of_last_update` holds the Unix time, in seconds, of the worker's start or of the last change of the status. It does not change between pings with the same status.
+- The job thread sends heartbeats when the job sets a heartbeat timeout, and then the success or failure callback.
+
+The worker remembers the callback IDs of accepted jobs only in its process memory. So it runs a job once per process. An answer can be lost after the job finished, and the retry can arrive after the idle timeout replaced the session's process. The new process then runs the same job again. So delivery is at-least-once across process replacement. Make the handler's side effects safe to repeat.
+
+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.
+
+### Rules for AgentCore jobs
+
+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.
+2. `timeout` must fit the agent runtime's configured `maxLifetime`.
+3. A job can run more than once when AgentCore replaces the worker process. Make handler side effects safe to repeat.
+4. Your logger must not throw.
+5. The runtime's idle timeout applies only while no job is running. One `agentcore()` call runs one job, so it does not lose state between jobs.
+6. Give the durable function a timeout of at least 11 seconds. Each AgentCore call needs the 10-second invocation reserve and 1 second for the call.
+
+The agent runtime's execution role needs `lambda:SendDurableExecutionCallbackSuccess`, `lambda:SendDurableExecutionCallbackFailure`, and `lambda:SendDurableExecutionCallbackHeartbeat` on the durable function's ARN. The function's execution role needs `bedrock-agentcore:InvokeAgentRuntime` and `bedrock-agentcore:StopRuntimeSession` on the agent runtime ARN and on `<runtime ARN>/runtime-endpoint/*`.
+
 ## Reference
 
 - [docs/worker.md](https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-compute-worker/docs/worker.md): the request flow, the lifecycle hooks, idle suspend outcomes, the job documents, reporting, heartbeats, logging fields, and best practices.

packages/aws-durable-execution-sdk-python-compute-worker/src/aws_durable_execution_sdk_python_compute_worker/agentcore/__init__.py

@@ -0,0 +1,39 @@
+# SPDX-FileCopyrightText: 2026-present Amazon.com, Inc. or its affiliates.
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Runs jobs from AWS Lambda durable functions inside an Amazon Bedrock
+AgentCore Runtime session.
+
+This module is experimental. Its API can change in any release.
+
+The exports match ``@aws/durable-execution-sdk-js-compute-worker/agentcore``.
+"""
+
+from aws_durable_execution_sdk_python_compute_worker.agentcore.worker import (
+    AGENTCORE_HOST,
+    AGENTCORE_PORT,
+    INVOCATIONS_PATH,
+    LOCAL_HOST,
+    PING_PATH,
+    RUNTIME_URL_ENV,
+    AgentcoreJobContext,
+    AgentcoreJobHandler,
+    AgentcoreWorker,
+    default_host,
+    start_agentcore_worker,
+)
+
+
+__all__ = [
+    "AGENTCORE_HOST",
+    "AGENTCORE_PORT",
+    "INVOCATIONS_PATH",
+    "LOCAL_HOST",
+    "PING_PATH",
+    "RUNTIME_URL_ENV",
+    "AgentcoreJobContext",
+    "AgentcoreJobHandler",
+    "AgentcoreWorker",
+    "default_host",
+    "start_agentcore_worker",
+]