diff --git a/bin/sync-ai-cookbook.js b/bin/sync-ai-cookbook.js
index 31eb55257a..7b169e3c1b 100644
--- a/bin/sync-ai-cookbook.js
+++ b/bin/sync-ai-cookbook.js
@@ -24,6 +24,9 @@ const SLUG_ALIASES = new Map([
// Add more aliases as recipes are renamed: ['old-slug', 'new-slug']
]);
+// Map old documentation paths used by cookbook recipes to their current routes.
+const DOCS_PATH_ALIASES = new Map([['/evaluate/cloud/limits', '/cloud/limits']]);
+
function runGit(args, options = {}) {
const result = spawnSync('git', args, {
stdio: ['ignore', 'inherit', 'inherit'],
@@ -297,7 +300,8 @@ function normalizeDocsHref(href) {
if (!match) {
return null;
}
- const pathname = match[1] ?? '/';
+ const originalPathname = match[1] ?? '/';
+ const pathname = DOCS_PATH_ALIASES.get(originalPathname) ?? originalPathname;
const search = match[2] ?? '';
const hash = match[3] ?? '';
return `${pathname}${search}${hash}`;
diff --git a/docs/develop/python/workers/serverless-workers/agentcore.mdx b/docs/develop/python/workers/serverless-workers/agentcore.mdx
new file mode 100644
index 0000000000..368256c0f6
--- /dev/null
+++ b/docs/develop/python/workers/serverless-workers/agentcore.mdx
@@ -0,0 +1,280 @@
+---
+id: agentcore
+title: Serverless Workers on Amazon Bedrock AgentCore Runtime - Python SDK
+sidebar_label: Amazon Bedrock AgentCore
+description: Run a Temporal Worker on Amazon Bedrock AgentCore Runtime using the Python SDK.
+slug: /develop/python/workers/serverless-workers/agentcore
+toc_max_heading_level: 4
+tags:
+ - Workers
+ - Python SDK
+ - Serverless
+ - Amazon Bedrock AgentCore
+---
+
+import { ReleaseNoteHeader } from '@site/src/components'
+
+
+ Amazon Bedrock AgentCore Runtime support is in Pre-release, and its APIs may change in backwards-incompatible ways.
+
+
+On Amazon Bedrock AgentCore Runtime, you run a standard long-lived Python Worker inside an AgentCore Runtime handler.
+Temporal starts the handler when the Worker Controller Instance needs capacity. The handler starts a Worker that polls
+the Task Queue, then stops it when your idle policy decides to release capacity.
+
+The Worker uses the normal Python SDK. The handler uses the `bedrock-agentcore` package to receive AgentCore Runtime
+invocations.
+
+For the provider behavior, including autoscaling, Worker Versioning, and the Runtime session lifecycle, see
+[Serverless Workers on Amazon Bedrock AgentCore Runtime](/serverless-workers/agentcore).
+For the infrastructure procedure, see
+[Deploy a Serverless Worker on Amazon Bedrock AgentCore Runtime](/production-deployment/worker-deployments/serverless-workers/agentcore).
+
+## Install the AgentCore Runtime SDK {/* #install-agentcore-runtime-sdk */}
+
+Install the AgentCore Runtime SDK alongside the Temporal Python SDK:
+
+```bash
+pip install bedrock-agentcore
+```
+
+## Create a versioned Worker {/* #versioned-worker */}
+
+Serverless Workers require [Worker Versioning](/worker-versioning). Create the Worker as you would any long-lived
+Python Worker, then set `deployment_config` to declare its Worker Deployment Version and enable versioning:
+
+```python
+worker = Worker(
+ # ...
+ deployment_config=WorkerDeploymentConfig(
+ version=WorkerDeploymentVersion(
+ deployment_name=DEPLOYMENT_NAME,
+ build_id=BUILD_ID,
+ ),
+ use_worker_versioning=True,
+ default_versioning_behavior=VersioningBehavior.PINNED,
+ ),
+)
+```
+
+`TEMPORAL_DEPLOYMENT_NAME` and `TEMPORAL_BUILD_ID` must match the Worker Deployment Version that you create with
+`temporal worker deployment create-version`. Configure that Worker Deployment Version with the AgentCore Runtime
+endpoint that Temporal invokes. For the endpoint configuration, see
+[Worker Versioning](/serverless-workers/agentcore#worker-versioning).
+
+Every Workflow needs a [versioning behavior](/worker-versioning#versioning-behaviors), either `PINNED` or
+`AUTO_UPGRADE`. Setting `default_versioning_behavior` as shown applies `PINNED` behavior to every Workflow on the
+Worker. To set the behavior per Workflow instead, pass `versioning_behavior` to the `@workflow.defn` decorator.
+
+## Start the Worker from the Runtime handler {/* #runtime-handler */}
+
+AgentCore Runtime invokes an HTTP handler. Use `BedrockAgentCoreApp` to provide that handler. Register the Worker as an
+asynchronous AgentCore task, then return an acknowledgment while the Worker continues polling in the background. The
+sample stores the background task in `_worker` and uses it to prevent another invocation from starting a duplicate
+Worker in the same Runtime session:
+
+
+[bedrock_agentcore/strands_agent/agentcore_worker.py](https://github.com/temporalio/samples-python/blob/main/bedrock_agentcore/strands_agent/agentcore_worker.py)
+```py
+async def run_worker() -> None:
+ """Poll until idle, then drain."""
+ api_key = os.environ.get("TEMPORAL_API_KEY") or None
+ client = await Client.connect(
+ os.environ.get("TEMPORAL_ADDRESS", "localhost:7233"),
+ namespace=os.environ.get("TEMPORAL_NAMESPACE", "default"),
+ api_key=api_key,
+ tls=bool(api_key),
+ plugins=[StrandsPlugin()],
+ )
+
+ tracker = ActivityTracker()
+ log.info("polling %s as %s/%s", TASK_QUEUE, DEPLOYMENT_NAME, BUILD_ID)
+ # execute_code is a sync Activity, so it needs an executor to block on.
+ with ThreadPoolExecutor(max_workers=4) as activity_executor:
+ worker = Worker(
+ client,
+ task_queue=TASK_QUEUE,
+ workflows=[workflows.StrandsAgentWorkflow],
+ activities=[execute_code],
+ activity_executor=activity_executor,
+ interceptors=[tracker],
+ deployment_config=WorkerDeploymentConfig(
+ version=WorkerDeploymentVersion(
+ deployment_name=DEPLOYMENT_NAME, build_id=BUILD_ID
+ ),
+ use_worker_versioning=True,
+ default_versioning_behavior=VersioningBehavior.PINNED,
+ ),
+ graceful_shutdown_timeout=DRAIN,
+ )
+ async with worker:
+ await tracker.wait_until_idle(DEBOUNCE)
+ log.info("worker idle for %ss; drained", DEBOUNCE)
+
+
+async def _run_until_idle(task_id: int) -> None:
+ """Own the Worker's whole life, and always release the async task."""
+ try:
+ await run_worker()
+ except Exception:
+ # Nothing awaits this task, so an error would otherwise be swallowed.
+ log.exception("worker failed in async task")
+ finally:
+ # Without this the session stays HealthyBusy until MaxLifetime.
+ app.complete_async_task(task_id)
+
+
+@app.entrypoint
+async def invoke(payload: dict) -> dict:
+ """Start the Worker and acknowledge. The payload is unused."""
+ # Prevent duplicate workers since we exit early
+ global _worker
+ if _worker is not None and not _worker.done():
+ log.info("worker already polling %s", TASK_QUEUE)
+ return {"message": "worker already polling", "task_queue": TASK_QUEUE}
+
+ task_id = app.add_async_task("temporal-worker")
+ _worker = asyncio.create_task(_run_until_idle(task_id))
+
+ return {"message": "worker starting", "task_queue": TASK_QUEUE}
+
+
+```
+
+
+The payload does not represent a Workflow input. The Worker Controller Instance invokes the endpoint to add Worker
+capacity. Applications start Workflows through the Temporal Client, as usual. `add_async_task` causes AgentCore to
+report the Runtime as busy while the Worker polls. `complete_async_task` releases that status after the Worker drains
+or fails.
+
+## Configure the Temporal connection {/* #configure-connection */}
+
+The `temporalio.envconfig` package loads [Temporal Client](/develop/python/client/temporal-client) configuration from
+environment variables and an optional TOML configuration file. Set the Temporal address, Namespace, Task Queue, and
+Worker Deployment Version values as Runtime environment variables. Store a Temporal Cloud API key or TLS material in a
+secret store rather than in the Runtime definition.
+
+For the supported connection variables, config-file format, and profiles, see
+[Environment configuration](/develop/environment-configuration).
+
+## Stop and drain the Worker {/* #stop-and-drain-the-worker */}
+
+AgentCore cannot tell when a Worker that is still polling has no Temporal work. The Runtime remains busy while the
+asynchronous task is registered, so it can remain active until its eight-hour maximum lifetime. To release capacity
+sooner, have the handler detect when the Worker has no useful work and complete the asynchronous task.
+
+When the condition remains true for an idle period, leave the `async with worker` block. The Worker stops polling for
+new Tasks and gives in-flight Activities time to complete before the Runtime handler returns.
+
+The following example from the
+[AgentCore sample Worker](https://github.com/temporalio/samples-python/blob/9d5c46bed0f0f6f8a726fa91f371c4c83f232ba2/bedrock_agentcore/strands_agent/agentcore_worker.py)
+defines an `ActivityTracker`. It uses an [Activity inbound Interceptor](/develop/python/workers/interceptors) to count
+running Activities.
+
+
+[bedrock_agentcore/strands_agent/agentcore_worker.py](https://github.com/temporalio/samples-python/blob/main/bedrock_agentcore/strands_agent/agentcore_worker.py)
+```py
+# How long the Worker keeps polling after it goes idle.
+DEBOUNCE = float(os.environ.get("AGENTCORE_DEBOUNCE_SECONDS", "60"))
+# How long the drain waits for in-flight Activities (a model or tool call).
+DRAIN = timedelta(seconds=120)
+
+
+class ActivityTracker(Interceptor):
+ """Tracks in-flight activities and blocks until AGENTCORE_DEBOUNCE_SECONDS elapses with no events."""
+
+ def __init__(self) -> None:
+ self.inflight = 0
+ self.changed = asyncio.Event()
+
+ def intercept_activity(
+ self, next: ActivityInboundInterceptor
+ ) -> ActivityInboundInterceptor:
+ return _TrackedActivity(next, self)
+
+ async def wait_until_idle(self, debounce: float) -> None:
+ """Return once no Activity has run for ``debounce`` seconds."""
+ while True:
+ self.changed.clear()
+ try:
+ # Wake the moment an Activity starts or finishes; a timeout
+ # instead means nothing has happened for the whole window.
+ await asyncio.wait_for(self.changed.wait(), timeout=debounce)
+ except asyncio.TimeoutError:
+ if self.inflight == 0:
+ return
+
+
+class _TrackedActivity(ActivityInboundInterceptor):
+ def __init__(
+ self, next: ActivityInboundInterceptor, tracker: ActivityTracker
+ ) -> None:
+ super().__init__(next)
+ self._tracker = tracker
+
+ async def execute_activity(self, input: ExecuteActivityInput):
+ self._tracker.inflight += 1
+ self._tracker.changed.set()
+ log.info("activity in flight: %d", self._tracker.inflight)
+ try:
+ return await self.next.execute_activity(input)
+ finally:
+ self._tracker.inflight -= 1
+ self._tracker.changed.set()
+
+
+```
+
+
+Register the tracker as a Worker Interceptor and wait for it inside the Worker context:
+
+```python
+tracker = ActivityTracker()
+worker = Worker(
+ client,
+ # ...
+ interceptors=[tracker],
+ graceful_shutdown_timeout=DRAIN,
+)
+
+async with worker:
+ await tracker.wait_until_idle(DEBOUNCE)
+```
+
+`ActivityTracker` retires the Worker only after 60 seconds without an Activity starting or completing and with no
+Activity running. A long-running Activity keeps the count above zero, so the idle policy does not interrupt it. The
+two-minute `graceful_shutdown_timeout` is a safety limit for any Activity still in flight when shutdown starts.
+
+Memory pressure can be another retirement condition. For example, the Runtime handler can monitor process memory and
+initiate the same graceful shutdown when usage crosses a threshold. Memory usage is not an idle signal. It tells you
+when to recycle a Worker, not whether it has work to do. Test any memory-based policy against the Runtime's memory
+limit and your Activity retry behavior.
+
+`AGENTCORE_DEBOUNCE_SECONDS` controls the idle period. `graceful_shutdown_timeout` controls how long the Worker waits
+for in-flight Activities after it stops polling. Choose both values for your workload, and account for AgentCore's
+maximum Runtime lifetime. For the AgentCore lifecycle settings, see
+[Lifecycle](/serverless-workers/agentcore#lifecycle).
+
+## Keep Activities safe across Worker termination {/* #activity-recovery */}
+
+AgentCore can end the compute that runs a Worker. An Activity running at that time can be interrupted and retried.
+Use [Activity Heartbeats](/develop/python/activities/timeouts#activity-heartbeats) so a retry resumes from its last
+recorded progress instead of starting over:
+
+```python
+from temporalio import activity
+
+
+@activity.defn
+async def my_activity(items: list[str]) -> str:
+ for i, item in enumerate(items):
+ activity.heartbeat(i)
+ # ... process item
+ return "done"
+```
+
+## Add observability {/* #add-observability */}
+
+An AgentCore Runtime Worker emits the same traces and metrics as a Worker on other compute. For metrics export and
+OpenTelemetry tracing interceptors, see [Observability - Python SDK](/develop/python/platform/observability) and the
+[SDK metrics reference](/references/sdk-metrics).
diff --git a/docs/develop/python/workers/serverless-workers/index.mdx b/docs/develop/python/workers/serverless-workers/index.mdx
index 3241c39562..c0d1d55f52 100644
--- a/docs/develop/python/workers/serverless-workers/index.mdx
+++ b/docs/develop/python/workers/serverless-workers/index.mdx
@@ -14,10 +14,10 @@ tags:
import { ReleaseNoteHeader } from '@site/src/components';
- AWS Lambda support is in Public Preview. GCP Cloud Run support is in Pre-release, and its APIs may change in
- backwards-incompatible ways. To request Cloud Run access, create a [support ticket](/evaluate/cloud/support#support-ticket) or
- contact your account team, and [sign up for updates](https://temporal.io/pages/serverless-workers-updates) to hear
- when Cloud Run reaches Public Preview.
+ AWS Lambda support is in Public Preview. Amazon Bedrock AgentCore Runtime and GCP Cloud Run support are in
+ Pre-release, and their APIs may change in backwards-incompatible ways. To request Cloud Run access, create a
+ [support ticket](/cloud/support#support-ticket) or contact your account team, and
+ [sign up for updates](https://temporal.io/pages/serverless-workers-updates) to hear when Cloud Run reaches Public Preview.
Serverless Workers run on ephemeral, on-demand compute rather than long-lived processes.
@@ -29,4 +29,5 @@ For the end-to-end deployment guide, see [Deploy a Serverless Worker](/productio
## Supported providers
- [**AWS Lambda**](/develop/python/workers/serverless-workers/aws-lambda) - Use the `lambda_worker` contrib package to run a Worker as a Lambda function. Covers setup, configuration, Lambda-tuned defaults, and observability.
+- [**Amazon Bedrock AgentCore Runtime**](/develop/python/workers/serverless-workers/agentcore) - Run a standard Worker from an AgentCore Runtime handler. Covers the handler, Worker Versioning, connection configuration, and Worker shutdown.
- [**GCP Cloud Run**](/develop/python/workers/serverless-workers/cloud-run) - Run a standard Worker on a Cloud Run worker pool. Covers the versioned Worker setup, connection configuration, and handling scale-in.
diff --git a/docs/encyclopedia/workers/serverless-workers/aws-lambda.mdx b/docs/encyclopedia/workers/serverless-workers/aws-lambda.mdx
index 4547762d57..fca5bec7c3 100644
--- a/docs/encyclopedia/workers/serverless-workers/aws-lambda.mdx
+++ b/docs/encyclopedia/workers/serverless-workers/aws-lambda.mdx
@@ -24,26 +24,38 @@ For a step-by-step deployment guide, see [Deploy a Serverless Worker on AWS Lamb
## Autoscaling {/* #autoscaling */}
-The Lambda autoscaling algorithm is event-driven and reactive.
+The autoscaling algorithm in this section applies to Serverless Workers on AWS Lambda and Amazon Bedrock AgentCore
+Runtime. The compute providers have different Worker lifecycles after a scale-out action. For AgentCore Runtime
+lifecycle details, see [Serverless Workers on Amazon Bedrock AgentCore Runtime](/serverless-workers/agentcore#lifecycle).
+
+The autoscaling algorithm is event-driven and reactive.
Sync match failure is the primary control signal, and backlog aids sizing.
-When the [WCI](/serverless-workers#worker-controller-instance) needs more capacity, it calls the Lambda `InvokeFunction` API to start new Workers.
-Each call is a discrete action ("invoke N more functions"), not a target state.
-Temporal calls that API from outside your network, so no inbound connection to the function is needed.
-The WCI does not manage a fleet of instances.
+When the [WCI](/serverless-workers#worker-controller-instance) needs more capacity, it invokes the compute provider to
+start new Workers: the Lambda `InvokeFunction` API for Lambda or an AgentCore Runtime endpoint for AgentCore Runtime.
+Each call is a discrete action ("start N more Workers"), not a target state. Temporal calls the provider API from
+outside your network, so no inbound connection to the Worker is needed. The WCI does not manage a fleet of instances.
### Scale-out {/* #scale-out */}
-On sync match failure, the WCI invokes new Lambda functions.
-Because Lambda cold start is sub-second to low single-digit seconds, reactive-only control does not create meaningful backlog overshoot.
-The WCI can scale from zero with low latency.
+On sync match failure, the WCI starts new Workers through the compute provider API.
+
+For Lambda, cold start is sub-second to low single-digit seconds, so reactive-only control does not create meaningful
+backlog overshoot. The WCI can scale from zero with low latency.
+
+For AgentCore Runtime startup and session behavior, see
+[Lifecycle](/serverless-workers/agentcore#lifecycle).
### Scale-in {/* #scale-in */}
-Scale-in is automatic.
-Each Lambda invocation runs until the Worker has finished processing available Tasks or approaches the 15-minute execution time limit, then shuts down.
-There is no drain logic or stabilization window.
-The WCI does not need to actively remove capacity.
+The WCI does not maintain a target number of Workers or actively remove capacity. The provider and Worker lifecycle
+determine when a Worker stops.
+
+On Lambda, each invocation runs until the Worker has finished processing available Tasks or approaches the 15-minute
+execution time limit, then shuts down. There is no drain logic or stabilization window.
+
+On AgentCore Runtime, Worker shutdown and AgentCore session lifecycle settings determine when a Worker stops. See
+[Lifecycle](/serverless-workers/agentcore#lifecycle).
### Instance model {/* #instance-model */}
diff --git a/docs/encyclopedia/workers/serverless-workers/index.mdx b/docs/encyclopedia/workers/serverless-workers/index.mdx
index d3c6d7d0be..657fb5f378 100644
--- a/docs/encyclopedia/workers/serverless-workers/index.mdx
+++ b/docs/encyclopedia/workers/serverless-workers/index.mdx
@@ -14,10 +14,10 @@ tags:
import { CaptionedImage, ReleaseNoteHeader } from '@site/src/components';
- AWS Lambda support is in Public Preview. GCP Cloud Run support is in Pre-release, and its APIs may change in
- backwards-incompatible ways. To request Cloud Run access, create a [support ticket](/evaluate/cloud/support#support-ticket) or
- contact your account team, and [sign up for updates](https://temporal.io/pages/serverless-workers-updates) to hear
- when Cloud Run reaches Public Preview.
+ AWS Lambda support is in Public Preview. Amazon Bedrock AgentCore Runtime and GCP Cloud Run support are in
+ Pre-release, and their APIs may change in backwards-incompatible ways. To request Cloud Run access, create a
+ [support ticket](/cloud/support#support-ticket) or contact your account team, and
+ [sign up for updates](https://temporal.io/pages/serverless-workers-updates) to hear when Cloud Run reaches Public Preview.
This page covers the following:
@@ -39,8 +39,9 @@ in response to work on a Task Queue.
A Serverless Worker uses the same Temporal SDKs as a traditional long-lived Worker, and registers Workflows and
Activities the same way. What differs is that Temporal manages the Worker's lifecycle rather than you running a Worker
-process. How that lifecycle works depends on the compute provider: AWS Lambda runs short-lived invocations, while GCP
-Cloud Run runs a pool of long-lived instances. See [Worker lifecycle](#worker-lifecycle).
+process. How that lifecycle works depends on the compute provider: AWS Lambda runs short-lived invocations, Amazon
+Bedrock AgentCore Runtime runs sessions with idle and maximum-lifetime limits, and GCP Cloud Run runs a pool of
+long-lived instances. See [Worker lifecycle](#worker-lifecycle).
Serverless Workers require [Worker Versioning](/worker-versioning). Each Serverless Worker must be associated with a
[Worker Deployment Version](/worker-versioning#deployment-versions) that has a compute provider configured.
@@ -69,12 +70,13 @@ Temporal impersonates to scale it.
Compute providers are only needed for Serverless Workers. Traditional long-lived Workers do not require a compute
provider because the Worker process lifecycle is not managed by the Temporal server.
-Temporal supports two compute providers:
+Temporal supports three compute providers:
-| Provider | Description |
-| ------------- | ----------------------------------------------------------------------------- |
-| AWS Lambda | Temporal assumes an IAM role in your AWS account to invoke a Lambda function. |
-| GCP Cloud Run | Temporal scales a Cloud Run [Worker Pool](https://cloud.google.com/run/docs/resource-model#worker-pools) through the Cloud Run admin API. A Worker Pool is its own Cloud Run resource type, distinct from a Service or a Job. |
+| Provider | Description |
+| ------------------------------ | ----------- |
+| AWS Lambda | Temporal assumes an IAM role in your AWS account to invoke a Lambda function. |
+| Amazon Bedrock AgentCore Runtime | Temporal assumes an IAM role in your AWS account to invoke an AgentCore Runtime endpoint. |
+| GCP Cloud Run | Temporal scales a Cloud Run [Worker Pool](https://cloud.google.com/run/docs/resource-model#worker-pools) through the Cloud Run admin API. A Worker Pool is its own Cloud Run resource type, distinct from a Service or a Job. |
## How Serverless invocation works {/* #how-invocation-works */}
@@ -167,6 +169,7 @@ short-lived invocations on AWS Lambda, or long-lived pool instances on GCP Cloud
Refer to the lifecycle section for your compute provider:
- [AWS Lambda lifecycle](/serverless-workers/aws-lambda#lifecycle)
+- [Amazon Bedrock AgentCore Runtime lifecycle](/serverless-workers/agentcore#lifecycle)
- [GCP Cloud Run lifecycle](/serverless-workers/cloud-run#lifecycle)
## Failure handling {/* #failure-handling */}
@@ -207,9 +210,9 @@ With single-slot configuration, each Activity gets a dedicated execution environ
| Constraint | Detail |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Activity duration | Depends on the compute provider. On AWS Lambda, an Activity must finish within the invocation limit (15 minutes maximum), minus the shutdown deadline buffer. On GCP Cloud Run, instances are long-lived, so no per-invocation limit applies. See [Worker lifecycle](#worker-lifecycle). |
+| Activity duration | Depends on the compute provider. On AWS Lambda, an Activity must finish within the invocation limit (15 minutes maximum), minus the shutdown deadline buffer. On Amazon Bedrock AgentCore Runtime, a microVM session has a maximum lifetime of 8 hours. On GCP Cloud Run, instances are long-lived, so no per-invocation limit applies. See [Worker lifecycle](#worker-lifecycle). |
| Workflow duration | No limit. Workflows of any duration work. A Workflow runs across as many Workers as needed. |
-| Worker code | Same Temporal SDK Worker code, using the serverless Worker package for your SDK. |
+| Worker code | Depends on the compute provider. AWS Lambda uses a serverless Worker package for your SDK. Amazon Bedrock AgentCore Runtime and GCP Cloud Run run standard long-lived Temporal Workers inside provider-specific runtime infrastructure. |
| Versioning | [Worker Versioning](/worker-versioning) is required. Each Workflow must have an `AutoUpgrade` or `Pinned` behavior, set per-Workflow or as a Worker-level default. See [Worker Versioning](/worker-versioning) for rollout strategies such as ramping, and [Worker Versioning with Serverless Workers](#worker-versioning-with-serverless-workers) for how Worker Deployment Versions map to compute provider primitives. |
| High Availability | On failover of a Namespace with [Multi-region or Multi-cloud Replication](/cloud/high-availability), the WCI keeps invoking Workers in the original region unless you manually repoint the compute provider. Compute provider configuration, such as a Lambda ARN or a Cloud Run Worker Pool, is scoped to a single region. See [Serverless Workers and High Availability](/cloud/high-availability#serverless-workers). |
@@ -221,4 +224,5 @@ How Worker Deployment Versions map to compute provider primitives differs by pro
Refer to the versioning section for your compute provider:
- [AWS Lambda versioning](/serverless-workers/aws-lambda#worker-versioning)
+- [Amazon Bedrock AgentCore Runtime versioning](/serverless-workers/agentcore#worker-versioning)
- [GCP Cloud Run versioning](/serverless-workers/cloud-run#worker-versioning)
diff --git a/docs/encyclopedia/workers/serverless-workers/serverless-workers-agentcore.mdx b/docs/encyclopedia/workers/serverless-workers/serverless-workers-agentcore.mdx
new file mode 100644
index 0000000000..05aee3c5cc
--- /dev/null
+++ b/docs/encyclopedia/workers/serverless-workers/serverless-workers-agentcore.mdx
@@ -0,0 +1,159 @@
+---
+id: serverless-workers-agentcore
+title: Serverless Workers on Amazon Bedrock AgentCore Runtime
+sidebar_label: Amazon Bedrock AgentCore
+description:
+ How Serverless Workers run on Amazon Bedrock AgentCore Runtime, including Worker Versioning and Runtime session
+ lifecycle.
+slug: /serverless-workers/agentcore
+toc_max_heading_level: 4
+tags:
+ - Workers
+ - Concepts
+ - Serverless
+ - Amazon Bedrock AgentCore
+---
+
+import { ReleaseNoteHeader } from '@site/src/components';
+
+
+ Amazon Bedrock AgentCore Runtime support is in Pre-release, and its APIs may change in backwards-incompatible ways.
+
+
+This page covers how Serverless Workers run on Amazon Bedrock AgentCore Runtime, including Worker Versioning and the
+Runtime session lifecycle.
+
+For a complete tutorial that explains the agent architecture and walks through deployment, see
+[Build a durable agent on Amazon Bedrock AgentCore](/guides/durable-agent-on-agentcore). If your Worker and AgentCore
+project are already in place, see
+[Deploy a Serverless Worker on Amazon Bedrock AgentCore Runtime](/production-deployment/worker-deployments/serverless-workers/agentcore).
+
+On AgentCore Runtime, a Serverless Worker is a standard long-running Temporal Worker that runs inside an AgentCore
+Runtime session. When the [Worker Controller Instance (WCI)](/serverless-workers#worker-controller-instance) needs
+capacity, it invokes an AgentCore Runtime endpoint. The Runtime starts a Worker, which connects to the Temporal Service
+and polls its Task Queue.
+
+## How Temporal and AgentCore work together {/* #how-temporal-and-agentcore-work-together */}
+
+Temporal is the durable execution layer for the agent. A Workflow records the agent's progress, coordinates model and
+tool calls, waits for input, and applies retries and timeouts. Model calls and tool calls run as Activities.
+
+AgentCore supplies the compute that hosts Temporal Workers and optional services that those Activities can use.
+Configuring AgentCore Runtime as a Serverless Workers compute provider does not automatically configure the other
+AgentCore services.
+
+| Concern | Where it belongs | How to use it |
+| --- | --- | --- |
+| **Agent execution and progress** | Temporal Workflow | Keep the agent loop, completed steps, approvals, and long-running waits in the Workflow so execution can continue on another Worker. |
+| **Model and tool operations** | Temporal Activities | Give each external operation its own timeout, Retry Policy, and recorded result. The Temporal Strands integration runs model and tool calls as Activities. |
+| **Worker compute** | AgentCore Runtime | Host a Temporal Worker in each Runtime session. Treat the Worker and its process-local state as replaceable. |
+| **Credentials** | [AgentCore Identity](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html) | Resolve credentials when an Activity accesses AWS or third-party services. Do not store credentials in Workflow state. |
+| **Tool access and authorization** | [AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-core-concepts.html) and [Policy](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-create-policies.html) | Call governed tools from Activities. Gateway connects the agent to tools, and Policy controls which tool calls are allowed. |
+| **Knowledge across conversations** | [AgentCore Memory](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html) | Read or write reusable knowledge through Activities. Memory does not replace Workflow state or Event History. |
+| **Runtime and agent telemetry** | [AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html) | Use AgentCore telemetry for Runtime, model, and tool behavior. Use Temporal Event History to inspect durable execution progress. |
+| **Caches and temporary files** | AgentCore Runtime session | Reuse them while the Runtime compute remains available, but do not require them to continue the Workflow. |
+
+For an implementation of this architecture using Strands and AgentCore Code Interpreter, see
+[Build a durable agent on Amazon Bedrock AgentCore](/guides/durable-agent-on-agentcore).
+
+## Choose AgentCore Runtime or AWS Lambda {/* #choose-agentcore-or-lambda */}
+
+AgentCore Runtime and AWS Lambda use the same event-driven autoscaling algorithm and run replaceable Workers. With
+either provider, a Workflow can continue for days, months, or longer across multiple Worker processes. Durable Timers,
+human approval waits, and waits for external events do not require compute to remain running. Keep durable progress in
+the Workflow and treat Worker-local state as replaceable.
+
+| Consideration | AgentCore Runtime | AWS Lambda |
+| --- | --- | --- |
+| **Primary use** | Agent and tool workloads that use the [AgentCore platform](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html). | General-purpose, event-driven Worker workloads on AWS. |
+| **Worker process** | A standard long-running Worker runs as background work in a Runtime session. The Runtime handler defines its idle and drain behavior, subject to AgentCore lifecycle limits. | A Lambda Worker integration starts the Worker, monitors the invocation deadline, and shuts it down before the function ends. |
+| **Compute lifetime** | A Runtime session using the serverless microVM compute type can run for up to 8 hours. | One function invocation can run for up to [15 minutes](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html). A later invocation can continue processing Tasks for the same Workflow. |
+| **Process-local reuse** | The Worker can reuse initialization work, in-memory caches, and temporary files while its Runtime compute remains available. A later Task can run on another Worker, so do not depend on this state. | Each invocation is independent. Do not expect process-local state to be available to a later invocation. |
+| **Agent services** | AgentCore provides services for identity, tool access, policy, memory, and observability. | Lambda can call AWS services under its execution role, but it does not provide the AgentCore agent platform. |
+
+Both compute providers can serve long-running Workflows because Temporal maintains Workflow state and execution
+progress independently of any Worker process. Their differences affect which provider is a better fit for individual
+Activity attempts, Worker lifecycle, process-local reuse, and AgentCore services:
+
+| Choose AgentCore Runtime if | Choose AWS Lambda if |
+| --- | --- |
+| Your application uses AgentCore services for identity, tool access, policy, memory, or observability. | Your Worker needs general-purpose AWS compute but does not use the AgentCore platform. |
+| An Activity attempt might need longer than Lambda's 15-minute invocation limit. An AgentCore Runtime session can provide up to 8 hours for uninterrupted work. | Individual Activity attempts finish within the Lambda invocation window or can resume or retry without significant cost. The 15-minute limit does not limit the overall Workflow duration. |
+| Reusing initialization work, in-memory caches, or temporary files reduces startup work or latency. | The Worker does not need process-local reuse. |
+
+## Autoscaling {/* #autoscaling */}
+
+AgentCore Runtime uses the same event-driven autoscaling model as AWS Lambda. The WCI invokes individual Runtime
+sessions when it needs more capacity. It does not manage a target-sized pool of Runtime sessions. For the shared
+autoscaling behavior, see [Autoscaling for Serverless Workers on AWS Lambda](/serverless-workers/aws-lambda#autoscaling).
+
+## Worker Versioning {/* #worker-versioning */}
+
+Serverless Workers require [Worker Versioning](/worker-versioning). Associate each Worker Deployment Version with a
+named AgentCore Runtime endpoint that points to one AgentCore Runtime version.
+
+AgentCore creates an immutable Runtime version when you create or update a Runtime. A named endpoint has a stable ARN
+and points to a chosen Runtime version. Configure the endpoint ARN as the compute provider for the corresponding Worker
+Deployment Version:
+
+```bash
+temporal worker deployment create-version \
+ --deployment-name my-worker \
+ --build-id v1 \
+ --aws-agentcore-endpoint-arn \
+ --aws-agentcore-assume-role-arn \
+ --aws-agentcore-assume-role-external-id
+```
+
+Use one named endpoint for each Worker Deployment Version. For example, point an endpoint named `temporal-v1` at
+AgentCore Runtime version `1` and use its ARN for Temporal Worker Deployment Version `my-worker/v1`.
+
+When you deploy new Worker code, AgentCore creates a new Runtime version. Create another endpoint that points to that
+new Runtime version and configure it on a new Worker Deployment Version. Keep the older endpoint while Pinned
+Workflows can still need the older Worker code.
+
+:::caution
+
+Do not configure a live Worker Deployment Version with AgentCore's `DEFAULT` endpoint. That endpoint moves to the
+latest Runtime version whenever you update the Runtime. Updating code behind a Worker Deployment Version can cause
+non-determinism errors for in-flight Workflows, including Pinned Workflows.
+
+:::
+
+For details about AgentCore Runtime versions and endpoints, see [AgentCore Runtime versioning and
+endpoints](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agent-runtime-versioning.html).
+
+## Lifecycle {/* #lifecycle */}
+
+An AgentCore Runtime session is the compute that runs a Worker, not a durable place to store Workflow state. AgentCore
+can resume a session on new compute after the previous compute ends, and a later Task can run on another Worker. Keep
+state that a Workflow needs in the Workflow or another durable store.
+
+Unlike an AWS Lambda Worker, an AgentCore Worker does not have a fixed Lambda invocation deadline. Your Runtime handler
+starts the Worker as background work. The Worker polls until it drains or AgentCore ends its compute.
+
+Two sets of controls determine when that Worker stops:
+
+- **Worker idle and graceful-shutdown policy**: Your Worker implementation decides when it has been idle, stops
+ polling, and waits for in-flight Activities to complete.
+- **AgentCore lifecycle settings**: AgentCore can end the session or its compute before the Worker policy does.
+
+The AgentCore lifecycle settings are:
+
+- **Idle Runtime session timeout**: Ends a Runtime session after it has not received an AgentCore Runtime invocation for
+ the configured duration. The default is 15 minutes. This is not a Temporal Worker idle timer: polling the Temporal
+ Service does not reset it.
+- **Maximum lifetime**: Ends the compute running a Runtime session after the configured duration. The default and
+ maximum is 8 hours. AgentCore can resume the session on new compute after that.
+
+AgentCore's session idle timeout does not replace a Worker idle policy. It resets with AgentCore Runtime invocations
+and does not measure Task Queue activity. To control how long an unused Worker polls, implement a separate shutdown
+policy: when its idle condition is met, stop polling and drain in-flight Activities before the Runtime handler returns.
+Choose the idle period and drain timeout for your workload, and account for the AgentCore maximum lifetime.
+
+Configure Activity timeouts and, for long-running Activities,
+[Activity Heartbeats](/encyclopedia/detecting-activity-failures#activity-heartbeat) so a retry can recover if AgentCore
+ends the compute before an Activity completes.
+
+For the lifecycle setting ranges and defaults, see [Configure Amazon Bedrock AgentCore lifecycle
+settings](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-lifecycle-settings.html).
diff --git a/docs/evaluate/features/serverless-workers/index.mdx b/docs/evaluate/features/serverless-workers/index.mdx
index 79380ef7c6..fa7597c48f 100644
--- a/docs/evaluate/features/serverless-workers/index.mdx
+++ b/docs/evaluate/features/serverless-workers/index.mdx
@@ -13,21 +13,21 @@ tags:
import { ReleaseNoteHeader } from '@site/src/components';
- AWS Lambda support is in Public Preview. GCP Cloud Run support is in Pre-release, and its APIs may change in
- backwards-incompatible ways. To request Cloud Run access, create a [support ticket](/evaluate/cloud/support#support-ticket) or
- contact your account team, and [sign up for updates](https://temporal.io/pages/serverless-workers-updates) to hear
- when Cloud Run reaches Public Preview.
+ AWS Lambda support is in Public Preview. Amazon Bedrock AgentCore Runtime and GCP Cloud Run support are in
+ Pre-release, and their APIs may change in backwards-incompatible ways. To request access, create a
+ [support ticket](/cloud/support#support-ticket) or contact your account team. You can also
+ [sign up for updates](https://temporal.io/pages/serverless-workers-updates).
-Serverless Workers let you run Temporal Workers on serverless compute platforms like AWS Lambda and GCP Cloud Run. There
-are no servers to provision, no clusters to scale, and no idle compute to pay for. Temporal starts Workers when Tasks
-arrive and stops them when the work drains.
+Serverless Workers let you run Temporal Workers on AWS Lambda, Amazon Bedrock AgentCore Runtime, and GCP Cloud Run.
+There are no servers to provision, no Worker fleet to scale, and no idle Worker fleet to maintain. Temporal starts
+Worker capacity when Tasks arrive and scales it down when the work drains.
Serverless Workers use the same Temporal SDKs as traditional long-lived Workers. You register Workflows and Activities
the same way. The difference is in the lifecycle: Temporal manages it instead of you running a Worker process. How that
lifecycle works depends on the provider. On AWS Lambda, Temporal invokes a function per unit of work, and the Worker
-exits when the invocation ends. On GCP Cloud Run, Temporal resizes a pool of long-lived instances, scaling it to zero
-when there is no work.
+exits when the invocation ends. On AgentCore Runtime, Temporal invokes Runtime sessions that host standard long-running
+Workers. On GCP Cloud Run, Temporal resizes a pool of long-lived instances, scaling it to zero when there is no work.
For a deeper look at how Serverless invocation works under the hood, see [Serverless Workers](/serverless-workers) in
the encyclopedia.
@@ -49,7 +49,7 @@ dedicated compute.
Long-lived Workers require you to provision infrastructure, configure scaling policies, manage deployments, and monitor
host-level health. Serverless Workers reduce this burden by offloading invocation and scaling to Temporal and the
-compute provider. You still deploy the function and configure the compute provider, but there is no always-on
+compute provider. You still deploy the Worker package and configure the compute provider, but there is no always-on
infrastructure to manage and no autoscaling policies to tune.
Worker management is one of the most common sources of support questions for Temporal users. Serverless Workers offer a
@@ -61,9 +61,9 @@ of managing infrastructure.
Running a long-lived Worker requires choosing a hosting strategy, configuring compute resources, and setting up
deployment pipelines before you can execute your first Workflow in production.
-With Serverless Workers, deploying a Worker is as simple as deploying a function. Package your Worker code, deploy it to
-your serverless provider, and configure the connection to Temporal. There is no need to set up Kubernetes, manage
-container orchestration, or design a scaling strategy.
+With Serverless Workers, you package your Worker code, deploy it to your serverless provider, and configure the
+connection to Temporal. There is no need to set up Kubernetes, manage container orchestration, or design a scaling
+strategy.
### Scale automatically
@@ -89,8 +89,8 @@ Serverless Workers are a good fit when:
always-on compute.
- **You want a simpler getting-started path.** Deploying a function is simpler than setting up a container orchestration
platform. Serverless Workers reduce the steps between writing Worker code and running your first Workflow.
-- **Your organization has standardized on serverless.** Teams that already run services on Lambda, Cloud Run, or similar
- platforms can run Temporal Workers using the same deployment patterns and tooling.
+- **Your organization has standardized on serverless.** Teams that already run services on Lambda, AgentCore Runtime,
+ Cloud Run, or similar platforms can run Temporal Workers using the same deployment patterns and tooling.
- **You serve multiple tenants with infrequent workloads.** Platforms that run Workflows on behalf of many users or
customers can avoid running dedicated Workers per tenant.
@@ -98,28 +98,34 @@ Serverless Workers may not be ideal when:
- **Activities are long-running and cannot be interrupted.** Some serverless platforms enforce execution time limits.
For example, AWS Lambda has a 15-minute execution limit. Activities that run longer than the provider's timeout and
- cannot be broken into smaller steps need a different hosting strategy or a provider with longer limits (such as Cloud
- Run). Long-running Workflows are not affected because Workflows can span multiple invocations.
+ cannot be broken into smaller steps need a different hosting strategy or a provider with a longer compute lifetime.
+ AgentCore Runtime sessions can provide up to 8 hours of uninterrupted compute. Long-running Workflows are not
+ affected because Temporal maintains their state and execution progress across Worker processes.
- **Workloads require sustained high throughput.** For consistently high-volume Task Queues, long-lived Workers on
dedicated compute may be more cost-effective and performant.
- **You need a persistent connection to Temporal.** Some features require the Worker to hold a connection open. On AWS
- Lambda each invocation connects fresh, so those features do not apply. Cloud Run instances are long-lived and hold a
- connection for as long as the instance runs.
+ Lambda each invocation connects fresh, so those features do not apply. AgentCore Runtime Workers and Cloud Run
+ instances hold a connection for the lifetime of their compute.
## How Serverless Workers compare to long-lived Workers
| | Long-lived Worker | Serverless Worker |
| -------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| **Lifecycle** | Long-lived process that runs continuously. | Temporal starts and stops it: per invocation on AWS Lambda, by pool size on GCP Cloud Run. |
+| **Lifecycle** | Long-lived process that runs continuously. | Temporal starts and stops it according to the compute provider's lifecycle. |
| **Scaling** | You manage scaling (Kubernetes HPA, instance count, etc.). | Temporal adds capacity as needed, within the compute provider's limits. |
-| **Connection** | Persistent connection to Temporal. | Fresh connection per invocation on AWS Lambda. Held for the instance's lifetime on GCP Cloud Run. |
+| **Connection** | Persistent connection to Temporal. | Fresh per Lambda invocation. Held for the compute lifetime on AgentCore Runtime and Cloud Run. |
## Supported providers
-| Provider | Compute |
-| ------------- | --------------------------------------------------------------------------- |
-| AWS Lambda | A function Temporal invokes per unit of work. |
-| GCP Cloud Run | A Worker Pool of long-lived instances whose size Temporal scales. |
+All three providers can serve long-running Workflows because Workflow lifetime is independent of Worker lifetime. The
+provider's compute limit applies to an individual Worker invocation or compute instance, not to the total Workflow
+duration.
+
+| Provider | Worker lifecycle | Consider this provider when |
+| --- | --- | --- |
+| [AWS Lambda](/serverless-workers/aws-lambda) | Temporal invokes a function per unit of work. Each invocation can run for up to 15 minutes. | You want general-purpose, event-driven AWS compute, and individual Activity attempts fit within the Lambda invocation window. |
+| [Amazon Bedrock AgentCore Runtime](/serverless-workers/agentcore) | Temporal invokes Runtime sessions that host standard long-running Workers. Each session can provide up to 8 hours of uninterrupted compute. | You are building agents on AWS, want to use AgentCore services, need longer Activity attempts, or benefit from process-local reuse while the Runtime compute remains available. |
+| [GCP Cloud Run](/serverless-workers/cloud-run) | Temporal adjusts the size of a Worker Pool of long-lived instances. | You want a managed pool of container-based Workers on Google Cloud. |
## Next steps
@@ -131,12 +137,12 @@ Serverless Workers may not be ideal when:
For the Worker code itself, pick your SDK and provider:
-| SDK | AWS Lambda | GCP Cloud Run |
-| --- | --- | --- |
-| Go | [Lambda Workers in Go](/develop/go/workers/serverless-workers/aws-lambda) | [Cloud Run Workers in Go](/develop/go/workers/serverless-workers/cloud-run) |
-| Python | [Lambda Workers in Python](/develop/python/workers/serverless-workers/aws-lambda) | [Cloud Run Workers in Python](/develop/python/workers/serverless-workers/cloud-run) |
-| TypeScript | [Lambda Workers in TypeScript](/develop/typescript/workers/serverless-workers/aws-lambda) | [Cloud Run Workers in TypeScript](/develop/typescript/workers/serverless-workers/cloud-run) |
-| Java | [Lambda Workers in Java](/develop/java/workers/serverless-workers/aws-lambda) | [Cloud Run Workers in Java](/develop/java/workers/serverless-workers/cloud-run) |
-| .NET | [Lambda Workers in .NET](/develop/dotnet/workers/serverless-workers/aws-lambda) | [Cloud Run Workers in .NET](/develop/dotnet/workers/serverless-workers/cloud-run) |
-| Ruby | | [Cloud Run Workers in Ruby](/develop/ruby/workers/serverless-workers/cloud-run) |
-| Rust | | [Cloud Run Workers in Rust](/develop/rust/workers/serverless-workers/cloud-run) |
+| SDK | AWS Lambda | Amazon Bedrock AgentCore Runtime | GCP Cloud Run |
+| --- | --- | --- | --- |
+| Go | [Lambda Workers in Go](/develop/go/workers/serverless-workers/aws-lambda) | | [Cloud Run Workers in Go](/develop/go/workers/serverless-workers/cloud-run) |
+| Python | [Lambda Workers in Python](/develop/python/workers/serverless-workers/aws-lambda) | [AgentCore Runtime Workers in Python](/develop/python/workers/serverless-workers/agentcore) | [Cloud Run Workers in Python](/develop/python/workers/serverless-workers/cloud-run) |
+| TypeScript | [Lambda Workers in TypeScript](/develop/typescript/workers/serverless-workers/aws-lambda) | | [Cloud Run Workers in TypeScript](/develop/typescript/workers/serverless-workers/cloud-run) |
+| Java | [Lambda Workers in Java](/develop/java/workers/serverless-workers/aws-lambda) | | [Cloud Run Workers in Java](/develop/java/workers/serverless-workers/cloud-run) |
+| .NET | [Lambda Workers in .NET](/develop/dotnet/workers/serverless-workers/aws-lambda) | | [Cloud Run Workers in .NET](/develop/dotnet/workers/serverless-workers/cloud-run) |
+| Ruby | | | [Cloud Run Workers in Ruby](/develop/ruby/workers/serverless-workers/cloud-run) |
+| Rust | | | [Cloud Run Workers in Rust](/develop/rust/workers/serverless-workers/cloud-run) |
diff --git a/docs/guides/durable-agent-on-agentcore.mdx b/docs/guides/durable-agent-on-agentcore.mdx
new file mode 100644
index 0000000000..9a6e54619e
--- /dev/null
+++ b/docs/guides/durable-agent-on-agentcore.mdx
@@ -0,0 +1,387 @@
+---
+id: durable-agent-on-agentcore
+title: Build a durable agent on Amazon Bedrock AgentCore
+sidebar_label: Durable agent on AgentCore
+description: Run a Strands agent as a Temporal Workflow while AgentCore Runtime supplies serverless Worker compute and a code execution tool.
+toc_max_heading_level: 3
+author: n/a
+tags:
+ - Workflows
+ - Activities
+ - Workers
+ - Python SDK
+ - Strands Agents
+ - Serverless
+---
+
+import { CaptionedImage, ReleaseNoteHeader } from '@site/src/components';
+
+
+ Amazon Bedrock AgentCore Runtime support is in Pre-release, and its APIs may change in backwards-incompatible ways.
+
+
+This guide deploys a Strands agent as a Temporal Serverless Worker on Amazon Bedrock AgentCore Runtime. The agent uses
+Amazon Bedrock for model inference and AgentCore Code Interpreter to run Python.
+
+If you already have an AgentCore application and are only interested in deploying a Worker Runtime, see
+[Deploy a Serverless Worker on Amazon Bedrock AgentCore
+Runtime](/production-deployment/worker-deployments/serverless-workers/agentcore). This guide uses a complete agent
+sample to explain why the Workflow, Activities, Runtime, and Worker Deployment are structured this way.
+
+## What you will build
+
+You will build an agent that can respond to prompts by using Amazon Bedrock for model inference and AgentCore Code
+Interpreter to run Python when needed. The sample accepts one prompt and runs one Workflow Execution. The Workflow asks
+the model to answer the prompt. The model can call Code Interpreter through a Temporal Activity before returning its
+answer.
+
+Your Temporal Client starts the Workflow. When the Task Queue needs a Worker, Temporal starts an
+AgentCore Runtime session. The Worker processes the Workflow and Activity Tasks, then drains after 60 seconds without
+an Activity starting or finishing.
+
+The sample handles one turn so the tutorial can focus on deployment. Both the model request and Code Interpreter call
+run as Temporal Activities. If the Worker stops before an Activity completes, Temporal can retry the Activity on
+another Worker according to its Retry Policy.
+
+## Architecture
+
+Temporal Cloud owns the agent's execution state and capacity control. The application starts or signals the Workflow.
+The Workflow records agent decisions and schedules model and tool work as Temporal Tasks. When the Task Queue needs
+capacity, the [Worker Controller Instance (WCI)](/serverless-workers#worker-controller-instance) starts AgentCore
+Runtime sessions.
+
+Each Runtime session hosts a Temporal Worker that polls the versioned Task Queue. Workers can call AgentCore services,
+but the sessions and their process-local state remain replaceable. The sample in this guide uses AgentCore Code
+Interpreter. It does not use every AgentCore service shown in the reference architecture.
+
+
+
+Place state according to how long it must remain available:
+
+| State | Location | Reason |
+|---|---|---|
+| Agent progress and bounded working context | Temporal Workflow | Temporal reconstructs Workflow state from Event History when another Worker continues the execution. |
+| Model calls and tool operations | Temporal Activities | Each operation gets its own timeout, Retry Policy, and recorded result. |
+| Large conversations, uploads, and generated artifacts | External durable storage, with references in the Workflow | Large or unbounded data should not cause Event History to grow without limit. |
+| Process-local caches and temporary files | AgentCore Runtime session | Runtime sessions are replaceable, so the agent must tolerate losing this state. |
+
+This division is what lets the Workflow outlive any one Runtime session. A Worker can stop after the current work is
+complete, and a later Worker can reconstruct the Workflow before continuing it.
+
+To extend the sample to multiple turns, use one Workflow ID per conversation and send later prompts to that Workflow
+through Updates. Any compatible Runtime session can process the next turn.
+
+## Prerequisites
+
+- A Temporal Cloud account with an AWS-hosted Namespace and access to the AgentCore Serverless Workers Pre-release.
+- A Temporal Cloud API key that can connect to the Namespace.
+- [Temporal CLI v1.8.3](https://github.com/temporalio/cli/releases/tag/v1.8.3) or later.
+- Python 3.10 or later and [`uv`](https://docs.astral.sh/uv/).
+- Node.js 20 or later and the
+ [AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-get-started-cli.html).
+- The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) configured for your AWS
+ account.
+- The [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting-started.html) installed and bootstrapped in an
+ [AgentCore-supported Region](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html).
+- AWS permissions to deploy AgentCore resources, CloudFormation stacks, and IAM roles. See
+ [IAM permissions for AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html).
+- Access to the Amazon Bedrock model that Strands selects in the target Region.
+
+## 1. Get the sample
+
+Clone the [Python samples repository](https://github.com/temporalio/samples-python/tree/main/bedrock_agentcore/strands_agent),
+then install the sample's Python dependencies:
+
+```bash
+git clone --depth 1 https://github.com/temporalio/samples-python.git
+cd samples-python/bedrock_agentcore/strands_agent
+uv sync
+```
+
+The cloned directory contains the Workflow, Activity, Runtime handler, AgentCore configuration, deployment scripts,
+and IAM template used throughout this guide.
+
+The sample uses AgentCore's CodeZip build instead of a container image. AgentCore packages the Python project and runs
+it on its managed Python runtime, so this path does not require a Dockerfile. The checked-in files define the
+application and Runtime settings. The deployment script generates the AgentCore CDK project when you first run it.
+
+## 2. Examine the agent Workflow
+
+The sample creates a
+[`TemporalAgent`](https://github.com/temporalio/sdk-python/blob/main/temporalio/contrib/strands/_temporal_agent.py) with a
+system prompt and the `execute_code` tool:
+
+
+[bedrock_agentcore/strands_agent/workflows.py](https://github.com/temporalio/samples-python/blob/main/bedrock_agentcore/strands_agent/workflows.py)
+```py
+@workflow.defn
+class StrandsAgentWorkflow:
+ def __init__(self) -> None:
+ # Configure with the plugin's default BedrockModel(), custom system
+ # prompt and code interpreter tool.
+ self.agent = TemporalAgent(
+ start_to_close_timeout=timedelta(seconds=60),
+ system_prompt=SYSTEM_PROMPT,
+ tools=[
+ activity_as_tool(
+ execute_code,
+ start_to_close_timeout=timedelta(minutes=2),
+ )
+ ],
+ )
+
+ @workflow.run
+ async def run(self, prompt: str) -> str:
+ # invoke_async, not agent(prompt) -- the sync form spawns a worker thread the
+ # Workflow sandbox blocks.
+ result = await self.agent.invoke_async(prompt)
+ return str(result)
+
+
+```
+
+
+`TemporalAgent` adapts the Strands agent loop to run in Workflow code. The Temporal Strands plugin schedules each model
+call as an Activity. `activity_as_tool` makes `execute_code` another Activity when the model selects that tool.
+
+The Workflow owns the sequence of model and tool decisions because that sequence must resume correctly after a
+failure. The model calls themselves do not run as ordinary Workflow code. They run as Activities because they perform
+network I/O, can fail independently, and are not deterministic.
+
+The `execute_code` Activity creates a Code Interpreter session using the Workflow ID as its session name:
+
+
+[bedrock_agentcore/strands_agent/activities.py](https://github.com/temporalio/samples-python/blob/main/bedrock_agentcore/strands_agent/activities.py)
+```py
+# Use AgentCore Code Interpreter to provide a code sandbox and execute LLM generated solution
+@activity.defn
+def execute_code(
+ code: str, language: LanguageType = LanguageType.PYTHON
+) -> dict[str, Any]:
+ """Run code in this Sessions's sandbox (workflow ID) and return the Code Interpreter result."""
+ interpreter = AgentCoreCodeInterpreter(
+ region=os.environ.get("AWS_REGION", "us-west-2"),
+ session_name=activity.info().workflow_id,
+ )
+ return interpreter.execute_code(
+ ExecuteCodeAction(type="executeCode", code=code, language=language)
+ )
+
+
+```
+
+
+Using the Workflow ID gives each Workflow Execution its own Code Interpreter sandbox.
+
+## 3. Configure and deploy the Runtime
+
+Open `agentcore/aws-targets.json`. Replace the account number and Region with the AWS account and Region where you
+will deploy the Runtime:
+
+```json
+[
+ {
+ "name": "default",
+ "description": "AWS account and Region for the Runtime",
+ "account": "",
+ "region": ""
+ }
+]
+```
+
+Open `agentcore/agentcore.json` and replace the placeholder values for `TEMPORAL_ADDRESS`, `TEMPORAL_NAMESPACE`, and
+`TEMPORAL_API_KEY`. Set `AWS_REGION` to the same Region used in `aws-targets.json`. Keep these sample values unchanged:
+
+| Setting | Value |
+|---|---|
+| `TEMPORAL_TASK_QUEUE` | `agentcore-strands-task-queue` |
+| `TEMPORAL_DEPLOYMENT_NAME` | `agentcore-strands-agent-python` |
+| `TEMPORAL_BUILD_ID` | `1.0.0` |
+| Runtime endpoint name | `temporal` |
+
+These values connect two separately configured systems. The Runtime uses the Task Queue, deployment name, and Build ID
+when its Worker registers with Temporal. The Worker Deployment Version created in Step 5 uses the same deployment name
+and Build ID and points Temporal back to this Runtime endpoint. If the values differ, Temporal can start compute that
+does not register as the version waiting for work.
+
+Putting the API key in `agentcore.json` keeps the tutorial short. Do not commit the populated file. For a production
+deployment, store the key in AWS Secrets Manager and load it when the Runtime starts.
+
+Set the Region for the AWS CLI commands in this guide:
+
+```bash
+export AWS_REGION=""
+```
+
+Deploy the Runtime and its named endpoint:
+
+```bash
+./bin/create-runtime.sh
+```
+
+The script creates the AgentCore CDK project on its first run, validates the configuration, packages the sample, and
+deploys it. The sample uses public network mode so the Worker can make an outbound connection to Temporal Cloud. The
+named endpoint is for capacity requests from Temporal, not prompts from the application.
+
+Retrieve the Runtime and endpoint ARNs:
+
+```bash
+export AGENT_RUNTIME_ARN="$(
+ aws bedrock-agentcore-control list-agent-runtimes \
+ --region "$AWS_REGION" \
+ --query "agentRuntimes[?agentRuntimeName=='TemporalStrandsAgent_temporal_strands_worker'].agentRuntimeArn | [0]" \
+ --output text
+)"
+export AGENT_RUNTIME_ID="${AGENT_RUNTIME_ARN##*/}"
+export RUNTIME_ENDPOINT_ARN="$(
+ aws bedrock-agentcore-control list-agent-runtime-endpoints \
+ --agent-runtime-id "$AGENT_RUNTIME_ID" \
+ --region "$AWS_REGION" \
+ --query "runtimeEndpoints[?name=='temporal'].agentRuntimeEndpointArn | [0]" \
+ --output text
+)"
+echo "$AGENT_RUNTIME_ARN"
+echo "$RUNTIME_ENDPOINT_ARN"
+```
+
+Both commands must print an ARN before you continue.
+
+:::important Runtime ARN and endpoint ARN are different
+
+`AGENT_RUNTIME_ARN` ends with `/runtime/`. It identifies the Runtime resource. The IAM role in Step 4 uses
+this ARN with a trailing wildcard to allow access to the Runtime and its endpoints.
+
+`RUNTIME_ENDPOINT_ARN` adds `/runtime-endpoint/temporal` to the Runtime ARN. It identifies the named endpoint that
+routes invocations to its configured Runtime version. The Worker Deployment Version in Step 5 uses this ARN to tell
+Temporal what to invoke.
+
+Do not use `AGENT_RUNTIME_ARN` as the `--aws-agentcore-endpoint-arn` value.
+
+:::
+
+## 4. Grant Temporal access to the Runtime
+
+Set the External ID, then use the sample's CloudFormation script to create the IAM role that Temporal Cloud assumes:
+
+```bash
+export EXTERNAL_ID="temporal-agentcore-tutorial"
+export INVOCATION_STACK="ac-strands-invoke"
+
+./bin/mk-invoke-role.sh \
+ "$INVOCATION_STACK" \
+ "$EXTERNAL_ID" \
+ "${AGENT_RUNTIME_ARN}*"
+```
+
+The fixed External ID makes the tutorial commands repeatable. Use a unique External ID for a production deployment.
+
+:::caution
+
+The sample names the IAM role `Temporal-Cloud-Serverless-Worker-`. An [IAM role name can contain at most 64
+characters](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-iam-role.html). Keep
+`INVOCATION_STACK` to 31 characters or fewer. The `ac-strands-invoke` value above is within the limit.
+
+:::
+
+Wait for the stack and retrieve the role ARN:
+
+```bash
+aws cloudformation wait stack-create-complete \
+ --stack-name "$INVOCATION_STACK" \
+ --region "$AWS_REGION"
+
+export INVOCATION_ROLE_ARN="$(
+ aws cloudformation describe-stacks \
+ --stack-name "$INVOCATION_STACK" \
+ --query 'Stacks[0].Outputs[?OutputKey==`RoleARN`].OutputValue' \
+ --output text \
+ --region "$AWS_REGION"
+)"
+echo "$INVOCATION_ROLE_ARN"
+```
+
+This invocation role lets Temporal get the named endpoint and invoke the Runtime. It is separate from the Runtime
+execution role that AgentCore created to run the Worker and access Code Interpreter.
+
+Keeping the roles separate gives each side only the permissions it needs. Temporal assumes the invocation role to
+start capacity. AgentCore assumes the execution role inside that capacity when the Worker calls Bedrock and Code
+Interpreter. The trailing wildcard on the Runtime ARN allows the invocation role to cover the named endpoint as well
+as the Runtime.
+
+## 5. Create the Serverless Worker deployment
+
+The values in `agentcore.json` configure the Worker inside AgentCore Runtime. They do not configure the Temporal CLI or
+the sample client process. Before continuing, export `TEMPORAL_ADDRESS`, `TEMPORAL_NAMESPACE`, `TEMPORAL_API_KEY`, and
+`AWS_REGION` for those processes. From the `samples-python/bedrock_agentcore/strands_agent` directory, run this command
+to read and export the values from `agentcore/agentcore.json`:
+
+```bash
+eval "$(python3 -c 'import json, shlex; env = {item["name"]: item["value"] for item in json.load(open("agentcore/agentcore.json"))["runtimes"][0]["envVars"]}; print("\n".join(f"export {name}={shlex.quote(env[name])}" for name in ("TEMPORAL_ADDRESS", "TEMPORAL_NAMESPACE", "TEMPORAL_API_KEY", "AWS_REGION")))')"
+```
+
+Create a Worker Deployment and a version that points to the AgentCore endpoint:
+
+```bash
+temporal worker deployment create \
+ --name agentcore-strands-agent-python
+
+temporal worker deployment create-version \
+ --deployment-name agentcore-strands-agent-python \
+ --build-id 1.0.0 \
+ --aws-agentcore-endpoint-arn "$RUNTIME_ENDPOINT_ARN" \
+ --aws-agentcore-assume-role-arn "$INVOCATION_ROLE_ARN" \
+ --aws-agentcore-assume-role-external-id "$EXTERNAL_ID"
+
+temporal worker deployment set-current-version \
+ --deployment-name agentcore-strands-agent-python \
+ --build-id 1.0.0 \
+ --yes
+```
+
+Creating the version causes Temporal to invoke the Runtime and wait for the Worker to register. The deployment name
+and Build ID match the values in `agentcore.json`. Setting the version as current lets it receive new Tasks on the
+`agentcore-strands-task-queue` Task Queue.
+
+The Worker Deployment Version binds one version of the Worker code to one compute configuration. The sample registers
+Workflows with `PINNED` behavior, so a Workflow continues on its assigned version instead of moving to a newer version
+while it is running. Marking `1.0.0` as current sends new Workflow Executions to that version.
+
+## 6. Run the agent
+
+Run the sample client with its default prompt:
+
+```bash
+uv run python starter.py
+```
+
+Or provide a prompt:
+
+```bash
+uv run python starter.py \
+ "Calculate the first 10 Fibonacci numbers and verify the result with Python."
+```
+
+`starter.py` starts `StrandsAgentWorkflow` and waits for its result. Temporal starts AgentCore Worker capacity, the
+Workflow calls the model and Code Interpreter Activities, and the client prints the answer. The Workflow then
+completes. After 60 seconds without an Activity starting or finishing, the Worker drains.
+
+Inspect the completed Workflow Execution:
+
+```bash
+temporal workflow show \
+ --workflow-id agentcore-strands-workflow-id-1
+```
+
+The Event History contains the model and `execute_code` Activities. Search the previous hour of AgentCore Runtime logs:
+
+```bash
+agentcore logs --runtime temporal_strands_worker --since 1h
+```
+
+The Workflow history and AgentCore logs show the two sides of the integration. Event History records what the agent
+did. The AgentCore logs show which replaceable Worker process performed the work and when that Worker drained.
diff --git a/docs/production-deployment/worker-deployments/index.mdx b/docs/production-deployment/worker-deployments/index.mdx
index 4a4ecb9a1f..f70742770f 100644
--- a/docs/production-deployment/worker-deployments/index.mdx
+++ b/docs/production-deployment/worker-deployments/index.mdx
@@ -30,7 +30,7 @@ You can optionally use the Temporal [Worker Controller](/production-deployment/w
This section also covers specific Worker Deployment examples:
- [**Serverless Workers**](/production-deployment/worker-deployments/serverless-workers)
- Deploy Serverless Workers on serverless compute like AWS Lambda.
+ Deploy Serverless Workers on AWS Lambda, GCP Cloud Run, or Amazon Bedrock AgentCore Runtime.
Temporal invokes your Worker when Tasks arrive, with no long-lived processes to manage.
- [**Deploy Workers to Amazon EKS**](/production-deployment/worker-deployments/deploy-workers-to-aws-eks)
diff --git a/docs/production-deployment/worker-deployments/serverless-workers/agentcore-self-hosted-setup.mdx b/docs/production-deployment/worker-deployments/serverless-workers/agentcore-self-hosted-setup.mdx
new file mode 100644
index 0000000000..9a04f5712a
--- /dev/null
+++ b/docs/production-deployment/worker-deployments/serverless-workers/agentcore-self-hosted-setup.mdx
@@ -0,0 +1,245 @@
+---
+id: agentcore-self-hosted-setup
+title: Self-hosted setup for Serverless Workers on Amazon Bedrock AgentCore Runtime
+sidebar_label: Self-hosted setup
+description: Configure AWS access and a self-hosted Temporal Service to run Serverless Workers on Amazon Bedrock AgentCore Runtime.
+slug: /production-deployment/worker-deployments/serverless-workers/agentcore/self-hosted-setup
+toc_max_heading_level: 4
+tags:
+ - Workers
+ - Deploy
+ - Serverless
+ - Self-hosting
+ - Amazon Bedrock AgentCore
+---
+
+import { ReleaseNoteHeader } from '@site/src/components';
+
+
+ Amazon Bedrock AgentCore Runtime support is in Pre-release, and its APIs may change in backwards-incompatible ways.
+
+
+Serverless Workers on AgentCore Runtime require Temporal Service v1.32.0 or later.
+
+This page covers the prerequisites for running [Serverless Workers](/serverless-workers) on a self-hosted Temporal
+Service with AgentCore Runtime:
+
+1. Ensure that AgentCore Runtime and the Temporal Service can reach each other.
+2. Enable the Worker Controller Instance (WCI) and AgentCore compute provider through dynamic configuration.
+3. Provide the Temporal Service with AWS credentials.
+4. Create an IAM role that grants Temporal permission to get and invoke AgentCore Runtime endpoints.
+
+Once setup is complete, follow the
+[AgentCore Runtime deployment guide](/production-deployment/worker-deployments/serverless-workers/agentcore) to deploy
+your Worker.
+
+## Configure network access {/* #configure-network-access */}
+
+The [Temporal Service frontend](/temporal-service/temporal-server#frontend-service) must be reachable from the
+AgentCore Runtime. If the Temporal Service has a public endpoint, configure the Runtime to use a public network. If the
+Temporal Service is available only through a private network, configure the Runtime for
+[VPC access](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-vpc.html) and connect that VPC to
+the network that hosts the Temporal Service.
+
+The Temporal Service must also reach the AgentCore control-plane and data-plane APIs. If the Service runs in an AWS VPC
+without internet access, configure
+[AgentCore interface VPC endpoints](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/vpc-interface-endpoints.html)
+for both APIs.
+
+## Enable the Worker Controller Instance {/* #enable-worker-controller */}
+
+[WCI](/serverless-workers#how-invocation-works) is the server component that monitors Task Queues and invokes compute
+providers. It is disabled by default and must be enabled through
+[dynamic configuration](/references/dynamic-configuration).
+
+Add the following keys to your dynamic config file:
+
+```yaml
+workercontroller.enabled:
+ - value: true
+
+workercontroller.compute_providers.enabled:
+ - value:
+ - aws-agentcore
+
+workercontroller.scaling_algorithms.enabled:
+ - value:
+ - no-sync
+```
+
+`workercontroller.compute_providers.enabled` is an allowlist that defaults to no providers. The `aws-agentcore` value
+enables the AgentCore compute provider. AgentCore uses the `no-sync` event-driven scaling algorithm, which invokes a
+Runtime session when the Task Queue needs more Worker capacity.
+
+If either allowlist already contains values for other compute providers or scaling algorithms, keep those values and
+add `aws-agentcore` or `no-sync` to the existing list.
+
+To enable WCI for specific Namespaces instead of globally, add a `constraints` section with the Namespace name under
+`workercontroller.enabled`. For example, to enable WCI only for `your-namespace`:
+
+```yaml
+workercontroller.enabled:
+ - value: true
+ constraints:
+ namespace: 'your-namespace'
+```
+
+The Temporal Service watches the dynamic config file for changes and applies updates without a restart.
+
+By default, the AWS compute providers require an invocation role and External ID in each Worker Deployment Version.
+Keep the default value of `workercontroller.compute_providers.aws.require_role_and_external_id` enabled and create the
+role in the following sections.
+
+## Configure AWS credentials {/* #configure-aws-credentials */}
+
+The Temporal Service needs AWS credentials to assume the AgentCore invocation role. How you provide credentials depends
+on where the Temporal Service runs.
+
+**On AWS infrastructure such as EC2, ECS, or EKS:** The server uses the attached instance role, task role, or pod role
+automatically. The attached role must have `sts:AssumeRole` permission for the invocation role created in the next
+step.
+
+**Outside AWS:** Use [IAM Roles Anywhere](https://aws.amazon.com/iam/roles-anywhere/), or configure static AWS
+credentials in the server environment. Static credentials are not recommended:
+
+```text
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_REGION=
+```
+
+These credentials must belong to an IAM user or role that has `sts:AssumeRole` permission for the AgentCore invocation
+role.
+
+## Create the AgentCore invocation role {/* #create-invocation-role */}
+
+Temporal gets and invokes AgentCore Runtime endpoints by assuming an IAM role in your AWS account. The role trust policy
+must allow the AWS identity used by the Temporal Service to assume it.
+
+[Download the CloudFormation template](/files/temporal-self-hosted-serverless-worker-agentcore-role.yaml), then deploy
+it. Pass each Runtime ARN with a trailing wildcard so the policy covers the Runtime and its endpoints:
+
+:::caution
+
+An [IAM role name can contain at most 64
+characters](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-iam-role.html). If you
+set `RoleName`, keep the complete name within this limit.
+
+:::
+
+```bash
+aws cloudformation create-stack \
+ --stack-name temporal-agentcore-worker \
+ --template-body file://temporal-self-hosted-serverless-worker-agentcore-role.yaml \
+ --parameters \
+ ParameterKey=TemporalIamRoleArn,ParameterValue= \
+ ParameterKey=AssumeRoleExternalId,ParameterValue= \
+ ParameterKey=AgentRuntimeARNs,ParameterValue='*' \
+ --capabilities CAPABILITY_NAMED_IAM \
+ --region
+```
+
+| Parameter | Description |
+| --- | --- |
+| `TemporalIamRoleArn` | ARN of the IAM role or user that the Temporal Service runs as. Run `aws sts get-caller-identity` in the server environment to identify it. |
+| `AssumeRoleExternalId` | Unique string that prevents [confused deputy](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) attacks. Use the same value when creating the Worker Deployment Version. |
+| `AgentRuntimeARNs` | Comma-separated Runtime ARNs that Temporal can access. Append a wildcard to each Runtime ARN to include its endpoints. |
+| `RoleName` | Name of the IAM role to create. Defaults to `Temporal-AgentCore-Worker`. Use a different name when deploying more than one copy of the stack. |
+
+
+CloudFormation template
+
+```yaml
+AWSTemplateFormatVersion: '2010-09-09'
+Description:
+ Creates an IAM role that a self-hosted Temporal Service can assume to invoke Amazon Bedrock AgentCore runtimes.
+
+Parameters:
+ TemporalIamRoleArn:
+ Type: String
+ Description: The ARN of the IAM role or user that the Temporal Service runs as.
+
+ AssumeRoleExternalId:
+ Type: String
+ Description: A unique identifier to prevent confused deputy attacks.
+ AllowedPattern: '[a-zA-Z0-9_+=,.@-]*'
+ MinLength: 5
+ MaxLength: 45
+
+ AgentRuntimeARNs:
+ Type: CommaDelimitedList
+ Description: >-
+ Comma-separated list of AgentCore Runtime ARNs that Temporal may access. Append a wildcard to each Runtime ARN
+ to include its endpoints.
+
+ RoleName:
+ Type: String
+ Default: 'Temporal-AgentCore-Worker'
+
+Resources:
+ TemporalAgentCoreWorker:
+ Type: AWS::IAM::Role
+ Properties:
+ RoleName: !Ref RoleName
+ AssumeRolePolicyDocument:
+ Version: '2012-10-17'
+ Statement:
+ - Effect: Allow
+ Principal:
+ AWS: [!Ref TemporalIamRoleArn]
+ Action: sts:AssumeRole
+ Condition:
+ StringEquals:
+ 'sts:ExternalId': [!Ref AssumeRoleExternalId]
+ Description: The role the Temporal Service uses to invoke AgentCore runtimes for Serverless Workers
+ MaxSessionDuration: 3600
+
+ TemporalAgentCoreInvokePermissions:
+ Type: AWS::IAM::Policy
+ Properties:
+ PolicyName: 'Temporal-AgentCore-Invoke-Permissions'
+ PolicyDocument:
+ Version: '2012-10-17'
+ Statement:
+ - Effect: Allow
+ Action:
+ - bedrock-agentcore:InvokeAgentRuntime
+ - bedrock-agentcore:GetAgentRuntimeEndpoint
+ Resource: !Ref AgentRuntimeARNs
+ Roles:
+ - !Ref TemporalAgentCoreWorker
+
+Outputs:
+ RoleARN:
+ Description: The ARN of the IAM role created for the Temporal Service
+ Value: !GetAtt TemporalAgentCoreWorker.Arn
+
+ AgentRuntimeARNs:
+ Description: The AgentCore Runtime ARNs that Temporal may access
+ Value: !Join [', ', !Ref AgentRuntimeARNs]
+```
+
+
+
+Wait for the stack to finish, then retrieve the invocation role ARN:
+
+```bash
+aws cloudformation wait stack-create-complete \
+ --stack-name temporal-agentcore-worker \
+ --region
+
+aws cloudformation describe-stacks \
+ --stack-name temporal-agentcore-worker \
+ --query 'Stacks[0].Outputs[?OutputKey==`RoleARN`].OutputValue' \
+ --output text \
+ --region
+```
+
+Use this role ARN and the External ID when creating the Worker Deployment Version.
+
+## Next steps {/* #next-steps */}
+
+Follow the [AgentCore Runtime deployment
+guide](/production-deployment/worker-deployments/serverless-workers/agentcore). Configure the Runtime Worker with your
+self-hosted Temporal Service address and authentication settings. Skip the Temporal Cloud IAM step and use the
+invocation role and External ID from this page when you create the Worker Deployment Version with the Temporal CLI.
diff --git a/docs/production-deployment/worker-deployments/serverless-workers/agentcore.mdx b/docs/production-deployment/worker-deployments/serverless-workers/agentcore.mdx
new file mode 100644
index 0000000000..c67affd568
--- /dev/null
+++ b/docs/production-deployment/worker-deployments/serverless-workers/agentcore.mdx
@@ -0,0 +1,427 @@
+---
+id: agentcore
+title: Deploy a Serverless Worker on Amazon Bedrock AgentCore Runtime
+sidebar_label: Amazon Bedrock AgentCore
+description: Add a Python Worker to an existing AgentCore application and configure Temporal to start capacity when Task Queue demand increases.
+slug: /production-deployment/worker-deployments/serverless-workers/agentcore
+toc_max_heading_level: 4
+tags:
+ - Workers
+ - Deploy
+ - Serverless
+ - Amazon Bedrock AgentCore
+---
+
+import { ReleaseNoteHeader } from '@site/src/components';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+ Amazon Bedrock AgentCore Runtime support is in Pre-release, and its APIs may change in backwards-incompatible ways.
+
+
+This page shows how to add a Python [Serverless Worker](/serverless-workers) to an existing Amazon Bedrock AgentCore
+application, deploy it to AgentCore Runtime, and connect it to a Worker Deployment Version. It assumes that your
+Workflow and Activity code and AgentCore project are already in place.
+
+For a tutorial that walks you through setting up an AgentCore project from scratch, see [Build a durable agent on
+Amazon Bedrock AgentCore](/guides/durable-agent-on-agentcore). That guide starts with the [Python Strands AgentCore
+sample](https://github.com/temporalio/samples-python/tree/main/bedrock_agentcore/strands_agent) and explains
+the agent architecture, Workflow and Activity boundaries, AgentCore project configuration, and deployment from start to
+finish. Use this page when you only need the Worker deployment procedure.
+
+For details about the Worker implementation and lifecycle, see [Serverless Workers on Amazon Bedrock AgentCore Runtime -
+Python SDK](/develop/python/workers/serverless-workers/agentcore).
+
+## Prerequisites {/* #prerequisites */}
+
+- A Temporal Cloud account with an AWS-hosted Namespace and access to the AgentCore Serverless Workers Pre-release. For
+ a self-hosted Temporal Service v1.32.0 or later, complete the
+ [self-hosted setup](/production-deployment/worker-deployments/serverless-workers/agentcore/self-hosted-setup) first.
+- [Temporal CLI v1.8.3](https://github.com/temporalio/cli/releases/tag/v1.8.3) or later, configured for your Namespace.
+- An existing AgentCore project with `agentcore/agentcore.json`, `agentcore/aws-targets.json`, and a generated AgentCore
+ CDK project.
+- An AWS account in an [AgentCore-supported Region](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html),
+ with the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) configured for that
+ account and permission to create AgentCore resources, CloudFormation stacks, and IAM roles. See
+ [IAM permissions for AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html).
+- Node.js 20 or later, the [AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-get-started-cli.html),
+ and the [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting-started.html) installed. Bootstrap the CDK in the
+ target account and Region.
+
+## 1. Configure the Worker Runtime {/* #configure-worker-runtime */}
+
+`agentcore/agentcore.json` is the [AgentCore CLI project
+configuration](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-get-started-cli.html). Its
+`runtimes` array defines the AgentCore Runtime resources that the CLI deploys.
+
+The `entrypoint` field names the Python file that AgentCore starts. That file must implement the [AgentCore Runtime HTTP
+protocol contract](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-http-protocol-contract.html) by
+serving the Runtime's `/invocations` and `/ping` endpoints. For a Serverless Worker, `/invocations` starts the Temporal
+Worker and acknowledges the request. For an implementation example, see the [Python Runtime entry
+point](/develop/python/workers/serverless-workers/agentcore#runtime-handler).
+
+The following fragment from the Python Strands AgentCore sample configures that entry point, a public network, and the
+named endpoint that Temporal invokes:
+
+```json
+{
+ "name": "temporal_strands_worker",
+ "build": "CodeZip",
+ "entrypoint": "agentcore_worker.py",
+ "codeLocation": ".",
+ "runtimeVersion": "PYTHON_3_12",
+ "networkMode": "PUBLIC",
+ "protocol": "HTTP",
+ "authorizerType": "AWS_IAM",
+ "endpoints": {
+ "temporal": {
+ "version": 1,
+ "description": "Invoked by Temporal Cloud Serverless Workers"
+ }
+ }
+}
+```
+
+In this initial configuration, `version: 1` selects the first AgentCore Runtime version.
+
+Within the same Runtime object, add the Temporal connection, Task Queue, Worker Deployment name, and Build ID to the
+`envVars` array:
+
+```json
+{
+ "envVars": [
+ {
+ "name": "TEMPORAL_ADDRESS",
+ "value": "..tmprl.cloud:7233"
+ },
+ {
+ "name": "TEMPORAL_NAMESPACE",
+ "value": "."
+ },
+ {
+ "name": "TEMPORAL_API_KEY",
+ "value": ""
+ },
+ {
+ "name": "TEMPORAL_TASK_QUEUE",
+ "value": ""
+ },
+ {
+ "name": "TEMPORAL_DEPLOYMENT_NAME",
+ "value": ""
+ },
+ {
+ "name": "TEMPORAL_BUILD_ID",
+ "value": ""
+ }
+ ]
+}
+```
+
+Replace `.` with your Temporal Cloud Namespace ID, `` with its API key, and
+`` with the Task Queue used by your application. Choose `` and `` for this Worker
+version.
+
+Do not commit a populated Temporal Cloud API key. For a production deployment, store it in AWS Secrets Manager, grant
+the Runtime execution role permission to read it, and load it in the Runtime entry point. The Runtime execution role is
+separate from the invocation role that Temporal assumes.
+
+## 2. Add the Worker code {/* #add-worker-code */}
+
+For a `CodeZip` Runtime, AgentCore packages the directory identified by `codeLocation`. The `entrypoint` path is
+relative to that directory. The directory must contain the entry point, every local module that it imports, and a
+`pyproject.toml` file that declares the Runtime dependencies.
+
+The sample sets `codeLocation` to `.` and uses the following layout:
+
+```text
+project-root/
+├── agentcore/
+│ ├── agentcore.json
+│ ├── aws-targets.json
+│ └── cdk/
+├── agentcore_worker.py
+├── workflows.py
+├── activities.py
+└── pyproject.toml
+```
+
+With this layout, set `entrypoint` to `agentcore_worker.py`. If your AgentCore application keeps code in a directory
+such as `app/MyAgent`, set `codeLocation` to that directory and put the entry point, imported modules, and
+`pyproject.toml` there.
+
+Declare `temporalio`, `bedrock-agentcore`, and your application dependencies in `pyproject.toml`. The entry point must:
+
+- Connect a Temporal Client and create a standard long-running Worker with your Workflows and Activities.
+- Configure the Worker with the deployment name and Build ID from the Runtime environment.
+- Use `BedrockAgentCoreApp` to implement the AgentCore Runtime HTTP endpoints.
+- Start the Worker as an AgentCore asynchronous task and acknowledge the invocation without waiting for the Worker to
+ stop.
+- Stop polling and drain the Worker when its idle policy decides to release the Runtime.
+
+The following excerpt from the Python sample implements this structure. It uses the `ActivityTracker`, `DEBOUNCE`, and
+`DRAIN` values defined in the same source file to retire the Worker after an idle period. The complete linked source
+file also contains the imports, creates the `BedrockAgentCoreApp`, retains the background task in `_worker`, and calls
+`app.run()` when the entry point starts. For the idle-policy code and an explanation of each part, see
+[Start the Worker from the Runtime handler](/develop/python/workers/serverless-workers/agentcore#runtime-handler).
+
+
+[bedrock_agentcore/strands_agent/agentcore_worker.py](https://github.com/temporalio/samples-python/blob/main/bedrock_agentcore/strands_agent/agentcore_worker.py)
+```py
+async def run_worker() -> None:
+ """Poll until idle, then drain."""
+ api_key = os.environ.get("TEMPORAL_API_KEY") or None
+ client = await Client.connect(
+ os.environ.get("TEMPORAL_ADDRESS", "localhost:7233"),
+ namespace=os.environ.get("TEMPORAL_NAMESPACE", "default"),
+ api_key=api_key,
+ tls=bool(api_key),
+ plugins=[StrandsPlugin()],
+ )
+
+ tracker = ActivityTracker()
+ log.info("polling %s as %s/%s", TASK_QUEUE, DEPLOYMENT_NAME, BUILD_ID)
+ # execute_code is a sync Activity, so it needs an executor to block on.
+ with ThreadPoolExecutor(max_workers=4) as activity_executor:
+ worker = Worker(
+ client,
+ task_queue=TASK_QUEUE,
+ workflows=[workflows.StrandsAgentWorkflow],
+ activities=[execute_code],
+ activity_executor=activity_executor,
+ interceptors=[tracker],
+ deployment_config=WorkerDeploymentConfig(
+ version=WorkerDeploymentVersion(
+ deployment_name=DEPLOYMENT_NAME, build_id=BUILD_ID
+ ),
+ use_worker_versioning=True,
+ default_versioning_behavior=VersioningBehavior.PINNED,
+ ),
+ graceful_shutdown_timeout=DRAIN,
+ )
+ async with worker:
+ await tracker.wait_until_idle(DEBOUNCE)
+ log.info("worker idle for %ss; drained", DEBOUNCE)
+
+
+async def _run_until_idle(task_id: int) -> None:
+ """Own the Worker's whole life, and always release the async task."""
+ try:
+ await run_worker()
+ except Exception:
+ # Nothing awaits this task, so an error would otherwise be swallowed.
+ log.exception("worker failed in async task")
+ finally:
+ # Without this the session stays HealthyBusy until MaxLifetime.
+ app.complete_async_task(task_id)
+
+
+@app.entrypoint
+async def invoke(payload: dict) -> dict:
+ """Start the Worker and acknowledge. The payload is unused."""
+ # Prevent duplicate workers since we exit early
+ global _worker
+ if _worker is not None and not _worker.done():
+ log.info("worker already polling %s", TASK_QUEUE)
+ return {"message": "worker already polling", "task_queue": TASK_QUEUE}
+
+ task_id = app.add_async_task("temporal-worker")
+ _worker = asyncio.create_task(_run_until_idle(task_id))
+
+ return {"message": "worker starting", "task_queue": TASK_QUEUE}
+
+
+```
+
+
+Replace `StrandsPlugin`, `StrandsAgentWorkflow`, and `execute_code` with the plugins, Workflows, and Activities used by
+your application.
+
+## 3. Deploy the Worker Runtime {/* #deploy-runtime */}
+
+From the AgentCore project directory, validate and deploy the project. Set `--target` to the `name` of the deployment
+target in `agentcore/aws-targets.json`. For example, if the target is named `default`, run:
+
+```bash
+agentcore validate
+agentcore deploy --target default -y
+```
+
+AgentCore packages the Worker and its dependencies, deploys the Runtime, and creates the named endpoint.
+
+Check the deployed resources. The `--runtime` value is the Runtime object's `name` in `agentcore/agentcore.json`. The
+sample Runtime is named `temporal_strands_worker`. If your Runtime has a different name, replace this value:
+
+```bash
+agentcore status --runtime temporal_strands_worker --json
+agentcore status --type runtime-endpoint --json
+```
+
+Record the Runtime ARN and the ARN of the named endpoint.
+
+:::important Runtime ARN and endpoint ARN are different
+
+The Runtime ARN ends with `/runtime/`. It identifies the Runtime resource. Use it with a trailing wildcard
+to scope the IAM role that Temporal assumes:
+
+```text
+arn:aws:bedrock-agentcore:::runtime/
+```
+
+The endpoint ARN adds `/runtime-endpoint/` to the Runtime ARN. It identifies the named endpoint that
+routes invocations to its configured Runtime version. Give this ARN to Temporal when you create the Worker Deployment
+Version:
+
+```text
+arn:aws:bedrock-agentcore:::runtime//runtime-endpoint/
+```
+
+Do not pass the Runtime ARN as the `--aws-agentcore-endpoint-arn` value.
+
+:::
+
+If you use a VPC instead of a public network, configure outbound access from the VPC to the Temporal Service. Temporal
+invokes the named endpoint by assuming the IAM role that you create in [Step 4](#configure-iam).
+
+## 4. Grant Temporal permission to invoke the Runtime {/* #configure-iam */}
+
+:::info Self-hosted Temporal Service
+
+If you use a self-hosted Temporal Service, create the invocation role during the
+[self-hosted setup](/production-deployment/worker-deployments/serverless-workers/agentcore/self-hosted-setup#create-invocation-role).
+Use that role when you create the Worker Deployment Version and skip the rest of this step.
+
+:::
+
+Temporal Cloud assumes an IAM role in your AWS account to get the named endpoint and invoke the Runtime. Choose an
+External ID of at least five characters. Use the same value in the role trust policy and the Worker Deployment Version.
+The External ID prevents a [confused deputy](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)
+attack.
+
+[Download the CloudFormation template](/files/temporal-cloud-serverless-worker-agentcore-role.yaml), then deploy it.
+Pass the Runtime ARN with a trailing wildcard so the policy covers the Runtime and its endpoints.
+
+:::caution
+
+The template names the IAM role `-`. An [IAM role name can contain at most 64
+characters](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-iam-role.html). Include
+the hyphen when checking the combined length. CloudFormation cannot create the role if the combined name exceeds this
+limit.
+
+:::
+
+```bash
+aws cloudformation create-stack \
+ --stack-name \
+ --template-body file://temporal-cloud-serverless-worker-agentcore-role.yaml \
+ --parameters \
+ ParameterKey=AssumeRoleExternalId,ParameterValue= \
+ ParameterKey=AgentRuntimeARNs,ParameterValue='*' \
+ ParameterKey=RoleName,ParameterValue= \
+ --capabilities CAPABILITY_NAMED_IAM \
+ --region
+```
+
+Wait for the CloudFormation stack to finish:
+
+```bash
+aws cloudformation wait stack-create-complete \
+ --stack-name \
+ --region
+```
+
+Then retrieve the invocation role ARN:
+
+```bash
+aws cloudformation describe-stacks \
+ --stack-name \
+ --query 'Stacks[0].Outputs[?OutputKey==`RoleARN`].OutputValue' \
+ --output text \
+ --region
+```
+
+The role grants `bedrock-agentcore:InvokeAgentRuntime` and `bedrock-agentcore:GetAgentRuntimeEndpoint` on the configured
+Runtime resources. This role does not run the Worker code.
+
+## 5. Create the Worker Deployment Version {/* #create-worker-deployment-version */}
+
+Create a [Worker Deployment Version](/production-deployment/worker-deployments/worker-versioning) whose compute
+configuration points to the named AgentCore Runtime endpoint. The deployment name and Build ID must match
+`TEMPORAL_DEPLOYMENT_NAME` and `TEMPORAL_BUILD_ID` in the Runtime environment from
+[Step 1](#configure-worker-runtime).
+
+
+
+
+In the Temporal Cloud UI, open your Namespace and select **Workers** > **Create Worker Deployment**. Provide these
+values:
+
+- **Name**: the value of `TEMPORAL_DEPLOYMENT_NAME` in the Runtime environment.
+- **Build ID**: the value of `TEMPORAL_BUILD_ID` in the Runtime environment.
+- **Compute Provider**: select **Amazon Bedrock AgentCore Runtime**.
+- **Runtime endpoint ARN**: the named endpoint ARN from [Step 3](#deploy-runtime).
+- **IAM role ARN**: the invocation role ARN from [Step 4](#configure-iam).
+- **External ID**: the External ID from [Step 4](#configure-iam).
+
+Save the Worker Deployment. When you create a version through the UI, the version is automatically current. Continue
+to [Step 7](#verify-worker-startup).
+
+
+
+
+Use the Temporal CLI for a self-hosted Temporal Service.
+
+First, create the Worker Deployment if it does not already exist:
+
+```bash
+temporal worker deployment create \
+ --namespace \
+ --name
+```
+
+Then create the version with the AgentCore compute configuration:
+
+```bash
+temporal worker deployment create-version \
+ --namespace \
+ --deployment-name \
+ --build-id \
+ --aws-agentcore-endpoint-arn \
+ --aws-agentcore-assume-role-arn \
+ --aws-agentcore-assume-role-external-id
+```
+
+
+
+
+For Temporal Cloud, check whether Temporal can reach the endpoint by opening the Worker Deployment Version in the
+Temporal Cloud UI and selecting **Actions** > **Validate Connection**. This checks that Temporal can assume the
+invocation role, get the named endpoint, and invoke the Runtime.
+
+## 6. Set the version as current {/* #set-current-version */}
+
+If you used the Temporal CLI, set the version as current:
+
+```bash
+temporal worker deployment set-current-version \
+ --namespace \
+ --deployment-name \
+ --build-id
+```
+
+This command asks you to confirm because it changes which version receives new Tasks. Pass `--yes` to skip the prompt.
+If you created the version in the Temporal Cloud UI, it is already current.
+
+## 7. Verify Worker startup {/* #verify-worker-startup */}
+
+Submit work to the configured Task Queue using your application. When no Worker is polling, Temporal invokes the named
+AgentCore Runtime endpoint. The Runtime starts the Worker, and the Worker polls and processes Tasks.
+
+You can confirm the deployment in these places:
+
+- **Temporal UI**: Open the Worker Deployment Version and confirm that a Worker has polled the Task Queue. In Temporal
+ Cloud, also confirm that the connection is valid.
+- **AgentCore logs**: Run `agentcore logs --runtime ` to see the Worker start and process Tasks.
+- **Temporal CLI**: Run `temporal worker deployment describe --name ` to inspect the deployment and
+ current version.
diff --git a/docs/production-deployment/worker-deployments/serverless-workers/index.mdx b/docs/production-deployment/worker-deployments/serverless-workers/index.mdx
index 58718e33ff..8e15a56982 100644
--- a/docs/production-deployment/worker-deployments/serverless-workers/index.mdx
+++ b/docs/production-deployment/worker-deployments/serverless-workers/index.mdx
@@ -15,10 +15,9 @@ tags:
import { ReleaseNoteHeader } from '@site/src/components';
- AWS Lambda support is in Public Preview. GCP Cloud Run support is in Pre-release, and its APIs may change in
- backwards-incompatible ways. To request Cloud Run access, create a [support ticket](/evaluate/cloud/support#support-ticket) or
- contact your account team, and [sign up for updates](https://temporal.io/pages/serverless-workers-updates) to hear
- when Cloud Run reaches Public Preview.
+ AWS Lambda support is in Public Preview. Support for GCP Cloud Run and Amazon Bedrock AgentCore Runtime is in
+ Pre-release, and their APIs may change in backwards-incompatible ways. To request access, create a
+ [support ticket](/cloud/support#support-ticket) or contact your account team.
Serverless Workers let you run Temporal Workers on serverless compute. Deploy your Worker code to a serverless provider,
@@ -27,9 +26,8 @@ work on the Task Queue. There is no always-on Worker fleet to provision or scale
Temporal monitors Task Queues that have a compute provider configured. When a Task arrives and no Worker is free to take
it, the [Worker Controller Instance (WCI)](/serverless-workers#how-invocation-works) starts compute. How it starts
-compute is where the providers differ. On AWS Lambda the WCI invokes a function per unit of work, and the Worker exits
-when the invocation window ends. On GCP Cloud Run it resizes a Worker Pool of long-lived instances that poll
-continuously.
+compute is where the providers differ. On AWS Lambda and AgentCore Runtime, the WCI invokes compute in response to
+unmet Task Queue demand. On GCP Cloud Run, it resizes a Worker Pool of long-lived instances that poll continuously.
## Supported providers
@@ -38,3 +36,6 @@ continuously.
- [**GCP Cloud Run**](/production-deployment/worker-deployments/serverless-workers/cloud-run) - Deploy a Serverless
Worker to a Cloud Run Worker Pool. Temporal impersonates a service account in your GCP project to scale the pool as
Tasks arrive and drain.
+- [**Amazon Bedrock AgentCore Runtime**](/production-deployment/worker-deployments/serverless-workers/agentcore) -
+ Deploy a Serverless Worker to AgentCore Runtime. Temporal assumes an IAM role in your AWS account to invoke the
+ Runtime endpoint as Tasks arrive.
diff --git a/sidebars.js b/sidebars.js
index 95c9896ed6..e4dbf10779 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -640,6 +640,7 @@ const developPythonCategory = {
},
items: [
'develop/python/workers/serverless-workers/aws-lambda',
+ 'develop/python/workers/serverless-workers/agentcore',
'develop/python/workers/serverless-workers/cloud-run',
],
},
@@ -1604,6 +1605,18 @@ module.exports = {
'production-deployment/worker-deployments/serverless-workers/aws-lambda/self-hosted-setup',
],
},
+ {
+ type: 'category',
+ label: 'Amazon Bedrock AgentCore',
+ collapsed: true,
+ link: {
+ type: 'doc',
+ id: 'production-deployment/worker-deployments/serverless-workers/agentcore',
+ },
+ items: [
+ 'production-deployment/worker-deployments/serverless-workers/agentcore-self-hosted-setup',
+ ],
+ },
{
type: 'category',
label: 'GCP Cloud Run',
@@ -2042,6 +2055,7 @@ module.exports = {
link: { type: 'doc', id: 'encyclopedia/workers/serverless-workers/serverless-workers' },
items: [
'encyclopedia/workers/serverless-workers/serverless-workers-aws-lambda',
+ 'encyclopedia/workers/serverless-workers/serverless-workers-agentcore',
'encyclopedia/workers/serverless-workers/serverless-workers-cloud-run',
],
},
@@ -2204,6 +2218,7 @@ module.exports = {
id: 'guides/index',
},
items: [
+ 'guides/durable-agent-on-agentcore',
'guides/entity-pattern-loyalty-points',
'guides/recover-without-restart',
'guides/route-specialized-workloads',
diff --git a/snipsync.config.yaml b/snipsync.config.yaml
index a1b6ba5c4f..d18878e6c9 100644
--- a/snipsync.config.yaml
+++ b/snipsync.config.yaml
@@ -39,7 +39,6 @@ origins:
ref: 'main'
- owner: temporalio
repo: sdk-go
-
targets:
- docs
diff --git a/src/components/GuidesGrid/guides-data.json b/src/components/GuidesGrid/guides-data.json
index 9f05d5194e..8e6641a888 100644
--- a/src/components/GuidesGrid/guides-data.json
+++ b/src/components/GuidesGrid/guides-data.json
@@ -1,4 +1,13 @@
[
+ {
+ "name": "Durable agent on AgentCore",
+ "description":
+ "Run a long-lived Strands agent with Temporal and serverless Worker compute on Amazon Bedrock AgentCore.",
+ "tags": ["AI agents"],
+ "sdk": "Python",
+ "href": "/guides/durable-agent-on-agentcore"
+ },
+
{
"name": "Customer loyalty program",
"description":
diff --git a/static/diagrams/temporal-agentcore-reference-architecture.png b/static/diagrams/temporal-agentcore-reference-architecture.png
new file mode 100644
index 0000000000..b429235b03
Binary files /dev/null and b/static/diagrams/temporal-agentcore-reference-architecture.png differ
diff --git a/static/files/temporal-cloud-serverless-worker-agentcore-role.yaml b/static/files/temporal-cloud-serverless-worker-agentcore-role.yaml
new file mode 100644
index 0000000000..a4d5b16504
--- /dev/null
+++ b/static/files/temporal-cloud-serverless-worker-agentcore-role.yaml
@@ -0,0 +1,69 @@
+# CloudFormation template for creating an IAM role that Temporal Cloud can assume to invoke AgentCore runtimes.
+AWSTemplateFormatVersion: '2010-09-09'
+Description:
+ Creates an IAM role that Temporal Cloud can assume to invoke Amazon Bedrock AgentCore runtimes for Serverless Workers.
+
+Parameters:
+ AssumeRoleExternalId:
+ Type: String
+ Description: A string you choose. Use the same value when creating the Worker Deployment Version.
+ AllowedPattern: '[a-zA-Z0-9_+=,.@-]*'
+ MinLength: 5
+ MaxLength: 45
+
+ AgentRuntimeARNs:
+ Type: CommaDelimitedList
+ Description: >-
+ Comma-separated list of AgentCore Runtime ARNs that Temporal may invoke. Append a wildcard to each Runtime ARN
+ to include its endpoints.
+
+ RoleName:
+ Type: String
+ Default: 'Temporal-Cloud-Serverless-Worker'
+
+Resources:
+ TemporalCloudServerlessWorker:
+ Type: AWS::IAM::Role
+ Properties:
+ RoleName: !Sub '${RoleName}-${AWS::StackName}'
+ AssumeRolePolicyDocument:
+ Version: '2012-10-17'
+ Statement:
+ - Effect: Allow
+ Principal:
+ AWS:
+ - arn:aws:iam::902542641901:role/wci-lambda-invoke
+ - arn:aws:iam::160190466495:role/wci-lambda-invoke
+ - arn:aws:iam::819232936619:role/wci-lambda-invoke
+ - arn:aws:iam::829909441867:role/wci-lambda-invoke
+ - arn:aws:iam::354116250941:role/wci-lambda-invoke
+ Action: sts:AssumeRole
+ Condition:
+ StringEquals:
+ 'sts:ExternalId': !Ref AssumeRoleExternalId
+ Description: The role Temporal Cloud uses to invoke AgentCore runtimes for Serverless Workers
+ MaxSessionDuration: 3600
+
+ TemporalCloudAgentCoreInvokePermissions:
+ Type: AWS::IAM::Policy
+ Properties:
+ PolicyName: 'Temporal-Cloud-AgentCore-Invoke-Permissions'
+ PolicyDocument:
+ Version: '2012-10-17'
+ Statement:
+ - Effect: Allow
+ Action:
+ - bedrock-agentcore:InvokeAgentRuntime
+ - bedrock-agentcore:GetAgentRuntimeEndpoint
+ Resource: !Ref AgentRuntimeARNs
+ Roles:
+ - !Ref TemporalCloudServerlessWorker
+
+Outputs:
+ RoleARN:
+ Description: The ARN of the IAM role created for Temporal Cloud
+ Value: !GetAtt TemporalCloudServerlessWorker.Arn
+
+ AgentRuntimeARNs:
+ Description: The AgentCore Runtime ARNs that Temporal may invoke
+ Value: !Join [', ', !Ref AgentRuntimeARNs]
diff --git a/static/files/temporal-self-hosted-serverless-worker-agentcore-role.yaml b/static/files/temporal-self-hosted-serverless-worker-agentcore-role.yaml
new file mode 100644
index 0000000000..7e98aca04c
--- /dev/null
+++ b/static/files/temporal-self-hosted-serverless-worker-agentcore-role.yaml
@@ -0,0 +1,68 @@
+# CloudFormation template for creating an IAM role that a self-hosted Temporal Service can assume to invoke AgentCore runtimes.
+AWSTemplateFormatVersion: '2010-09-09'
+Description:
+ Creates an IAM role that a self-hosted Temporal Service can assume to invoke Amazon Bedrock AgentCore runtimes.
+
+Parameters:
+ TemporalIamRoleArn:
+ Type: String
+ Description: The ARN of the IAM role or user that the Temporal Service runs as.
+
+ AssumeRoleExternalId:
+ Type: String
+ Description: A unique identifier to prevent confused deputy attacks.
+ AllowedPattern: '[a-zA-Z0-9_+=,.@-]*'
+ MinLength: 5
+ MaxLength: 45
+
+ AgentRuntimeARNs:
+ Type: CommaDelimitedList
+ Description: >-
+ Comma-separated list of AgentCore Runtime ARNs that Temporal may access. Append a wildcard to each Runtime ARN
+ to include its endpoints.
+
+ RoleName:
+ Type: String
+ Default: 'Temporal-AgentCore-Worker'
+
+Resources:
+ TemporalAgentCoreWorker:
+ Type: AWS::IAM::Role
+ Properties:
+ RoleName: !Ref RoleName
+ AssumeRolePolicyDocument:
+ Version: '2012-10-17'
+ Statement:
+ - Effect: Allow
+ Principal:
+ AWS: [!Ref TemporalIamRoleArn]
+ Action: sts:AssumeRole
+ Condition:
+ StringEquals:
+ 'sts:ExternalId': [!Ref AssumeRoleExternalId]
+ Description: The role the Temporal Service uses to invoke AgentCore runtimes for Serverless Workers
+ MaxSessionDuration: 3600
+
+ TemporalAgentCoreInvokePermissions:
+ Type: AWS::IAM::Policy
+ Properties:
+ PolicyName: 'Temporal-AgentCore-Invoke-Permissions'
+ PolicyDocument:
+ Version: '2012-10-17'
+ Statement:
+ - Effect: Allow
+ Action:
+ - bedrock-agentcore:InvokeAgentRuntime
+ - bedrock-agentcore:GetAgentRuntimeEndpoint
+ Resource: !Ref AgentRuntimeARNs
+ Roles:
+ - !Ref TemporalAgentCoreWorker
+
+Outputs:
+ RoleARN:
+ Description: The ARN of the IAM role created for the Temporal Service
+ Value: !GetAtt TemporalAgentCoreWorker.Arn
+
+ AgentRuntimeARNs:
+ Description: The AgentCore Runtime ARNs that Temporal may access
+ Value: !Join [', ', !Ref AgentRuntimeARNs]