# Deploy a Serverless Worker on Amazon Bedrock AgentCore Runtime

> For the complete documentation index, see [llms.txt](https://docs.temporal.io/llms.txt).
> Any documentation page is available as raw Markdown by appending `.md` to its URL.

> Deploy a Python Serverless Worker to AgentCore Runtime and configure Temporal Cloud to invoke its endpoint.

> **Pre-release**
> Amazon Bedrock AgentCore Runtime support is in Pre-release, and its APIs may change in backwards-incompatible ways.

This guide walks through deploying a Python [Serverless Worker](/serverless-workers) to Amazon Bedrock AgentCore
Runtime. Temporal invokes the Runtime endpoint when the Worker Controller Instance needs Worker capacity.

The guide uses the
[Python Strands AgentCore sample](https://github.com/temporalio/samples-python/tree/6fd0c9e879e85c4403bf8c1c591f7394fa60bed2/bedrock_agentcore/strands-agent).
The deployment procedure applies to other Python Workers that use the same AgentCore Runtime handler. For the Worker
implementation and lifecycle, see
[Serverless Workers on Amazon Bedrock AgentCore Runtime - Python SDK](/develop/python/workers/serverless-workers/agentcore).

## 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, configured for your Namespace.
- An AWS account in an [AgentCore-supported Region](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html).
- The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) installed and configured
  with credentials for that account.
- Node.js 20 or later and the [AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-get-started-cli.html)
  installed with `npm install -g @aws/agentcore`.
- The [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting-started.html) installed and bootstrapped in the target
  account and Region.
- Python 3.10 or later and [`uv`](https://docs.astral.sh/uv/) installed.
- 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).

The sample agent calls an Amazon Bedrock model and uses AgentCore Code Interpreter. To run the sample without changing
it, make sure both services are available to your AWS account in the target Region.

## 1. Prepare the Worker 

Clone the sample repository and check out the AgentCore sample branch:

```bash
git clone https://github.com/temporalio/samples-python.git
cd samples-python
git checkout schoeff/strands-agent
cd bedrock_agentcore/strands-agent
```

The sample contains these deployment files:

| File | Purpose |
| --- | --- |
| [`agentcore_worker.py`](https://github.com/temporalio/samples-python/blob/6fd0c9e879e85c4403bf8c1c591f7394fa60bed2/bedrock_agentcore/strands-agent/agentcore_worker.py) | Defines the AgentCore Runtime handler and starts the Temporal Worker. |
| [`workflows.py`](https://github.com/temporalio/samples-python/blob/6fd0c9e879e85c4403bf8c1c591f7394fa60bed2/bedrock_agentcore/strands-agent/workflows.py) | Defines the sample Workflow. |
| [`activities.py`](https://github.com/temporalio/samples-python/blob/6fd0c9e879e85c4403bf8c1c591f7394fa60bed2/bedrock_agentcore/strands-agent/activities.py) | Defines the sample Activity. |
| [`agentcore/agentcore.json`](https://github.com/temporalio/samples-python/blob/6fd0c9e879e85c4403bf8c1c591f7394fa60bed2/bedrock_agentcore/strands-agent/agentcore/agentcore.json) | Configures the Runtime, endpoint, environment, and lifecycle. |
| [`agentcore/aws-targets.json`](https://github.com/temporalio/samples-python/blob/6fd0c9e879e85c4403bf8c1c591f7394fa60bed2/bedrock_agentcore/strands-agent/agentcore/aws-targets.json) | Selects the AWS account and Region. |

The Runtime handler registers `StrandsAgentWorkflow` and `execute_code` on the Worker. To deploy your own application,
replace those registrations with your Workflow and Activity Definitions. Keep the AgentCore handler, Worker Versioning
configuration, and shutdown policy. Every Workflow must declare a
[versioning behavior](/worker-versioning/#versioning-behaviors), or the Worker must set a default behavior.

## 2. Configure the AgentCore project 

The AgentCore CLI reads the project from `agentcore/agentcore.json` and deploys it to a target in
`agentcore/aws-targets.json`.

### Select the AWS account and Region 

Replace the account and Region in `agentcore/aws-targets.json`:

```json
[
  {
    "name": "default",
    "account": "<AWS_ACCOUNT_ID>",
    "region": "<AWS_REGION>"
  }
]
```

The Region must support AgentCore Runtime and any AWS services that the Worker's Activities call.

### Configure the Runtime 

In `agentcore/agentcore.json`, set the Temporal connection, Task Queue, Worker Deployment name, and Build ID under
`envVars`:

```json
{
  "name": "TEMPORAL_ADDRESS",
  "value": "<NAMESPACE>.<ACCOUNT>.tmprl.cloud:7233"
},
{
  "name": "TEMPORAL_NAMESPACE",
  "value": "<NAMESPACE>.<ACCOUNT>"
},
{
  "name": "TEMPORAL_API_KEY",
  "value": "<TEMPORAL_API_KEY>"
},
{
  "name": "TEMPORAL_TASK_QUEUE",
  "value": "agentcore-strands-task-queue"
},
{
  "name": "TEMPORAL_DEPLOYMENT_NAME",
  "value": "agentcore-strands-agent-python"
},
{
  "name": "TEMPORAL_BUILD_ID",
  "value": "1.0.0"
}
```

The deployment name and Build ID must match the values you use when you create the Worker Deployment Version in
[Step 5](#create-worker-deployment-version). The Task Queue must match the Task Queue used to start the Workflow.
For the sample, also set `AWS_REGION` to the Region in `aws-targets.json` so its Bedrock model and Code Interpreter
calls stay in that Region.

The sample stores the Temporal Cloud API key in `envVars` to keep the example short. Do not commit a populated API key.
For a production deployment, store the key in AWS Secrets Manager, grant the Runtime execution role permission to read
it, and load it in the Runtime handler. The AgentCore CLI creates the Runtime execution role during deployment. This
role is separate from the invocation role that Temporal assumes in [Step 4](#configure-iam).

The sample uses a CodeZip build and a public network:

```json
{
  "build": "CodeZip",
  "entrypoint": "agentcore_worker.py",
  "codeLocation": ".",
  "runtimeVersion": "PYTHON_3_12",
  "networkMode": "PUBLIC",
  "protocol": "HTTP",
  "authorizerType": "AWS_IAM"
}
```

`CodeZip` lets the AgentCore CLI package the Python code without Docker. `PUBLIC` gives the Worker outbound network
access to Temporal Cloud. The `AWS_IAM` authorizer lets Temporal invoke the endpoint by assuming an IAM role in your
AWS account.

Keep the named `temporal` endpoint in the sample configuration. Temporal invokes this endpoint rather than AgentCore's
`DEFAULT` endpoint. For the endpoint and Runtime version relationship, see
[Worker Versioning on AgentCore Runtime](/serverless-workers/agentcore/#worker-versioning).

## 3. Deploy the Runtime and endpoint 

From the sample directory, run:

```bash
./bin/create-runtime.sh
```

The script creates the AgentCore CDK scaffold on its first run. It then validates the project, packages the Worker and
its dependencies, and runs `agentcore deploy`. AgentCore creates the Runtime execution role, Runtime version, named
endpoint, and CloudWatch log group.

Check the deployed resources:

```bash
agentcore status --runtime temporal_strands_worker --json
agentcore status --type runtime-endpoint --json
```

Record both of these values from the output:

- The **Runtime ARN**, which you use to scope the invocation role in [Step 4](#configure-iam).
- The **Runtime endpoint ARN** for the named `temporal` endpoint, which you give Temporal in
  [Step 5](#create-worker-deployment-version).

## 4. Grant Temporal permission to invoke the Runtime 

Temporal Cloud assumes an IAM role in your AWS account to get the named endpoint and invoke the Runtime. The role is
not the Runtime execution role and does not run your Worker code.

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.

The sample includes a
[CloudFormation template](https://github.com/temporalio/samples-python/blob/6fd0c9e879e85c4403bf8c1c591f7394fa60bed2/bedrock_agentcore/strands-agent/iam-role-for-temporal-agentcore-invoke.yaml)
and a script that deploys it. Pass the Runtime ARN with a trailing wildcard so the policy covers the Runtime and its
endpoints:

```bash
AWS_REGION=<AWS_REGION> ./bin/mk-invoke-role.sh \
  temporal-agentcore-invoke \
  <EXTERNAL_ID> \
  '<AGENT_RUNTIME_ARN>*'
```

Wait for the CloudFormation stack to finish:

```bash
aws cloudformation wait stack-create-complete \
  --stack-name temporal-agentcore-invoke \
  --region <AWS_REGION>
```

Then retrieve the invocation role ARN:

```bash
aws cloudformation describe-stacks \
  --stack-name temporal-agentcore-invoke \
  --query 'Stacks[0].Outputs[?OutputKey==`RoleARN`].OutputValue' \
  --output text \
  --region <AWS_REGION>
```

The role grants `bedrock-agentcore:InvokeAgentRuntime` and `bedrock-agentcore:GetAgentRuntimeEndpoint` on the configured
Runtime resources. Record the role ARN for the next step.

## 5. Create the 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 the Runtime
environment variables from [Step 2](#configure-runtime).

**Temporal Cloud UI**

In the Temporal Cloud UI, open your Namespace and select **Workers** > **Create Worker Deployment**. Provide these
values:

- **Name**: `agentcore-strands-agent-python`.
- **Build ID**: `1.0.0`.
- **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-deployment).

**Temporal CLI**

First, create the Worker Deployment if it does not already exist:

```bash
temporal worker deployment create \
  --namespace <TEMPORAL_NAMESPACE> \
  --name agentcore-strands-agent-python
```

Then create the version with the AgentCore compute configuration:

```bash
temporal worker deployment create-version \
  --namespace <TEMPORAL_NAMESPACE> \
  --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>
```

| Flag | Description |
| --- | --- |
| `--deployment-name` | Worker Deployment name. Must match `TEMPORAL_DEPLOYMENT_NAME` in the Runtime environment. |
| `--build-id` | Worker Deployment Version Build ID. Must match `TEMPORAL_BUILD_ID` in the Runtime environment. |
| `--aws-agentcore-endpoint-arn` | ARN of the named AgentCore Runtime endpoint that Temporal invokes. |
| `--aws-agentcore-assume-role-arn` | IAM role Temporal assumes to invoke the endpoint. This is the CloudFormation stack output from Step 4, not the Runtime execution role. |
| `--aws-agentcore-assume-role-external-id` | External ID configured in the invocation role trust policy. |

To check whether Temporal can reach the endpoint, open the Worker Deployment Version in the Temporal Cloud UI and
select **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 

If you used the Temporal CLI, set the version as current:

```bash
temporal worker deployment set-current-version \
  --namespace <TEMPORAL_NAMESPACE> \
  --deployment-name agentcore-strands-agent-python \
  --build-id 1.0.0
```

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 the deployment 

Install the sample dependencies and export the same Temporal connection values that you configured for the Runtime:

```bash
uv sync
export TEMPORAL_ADDRESS=<NAMESPACE>.<ACCOUNT>.tmprl.cloud:7233
export TEMPORAL_NAMESPACE=<NAMESPACE>.<ACCOUNT>
export TEMPORAL_API_KEY=<TEMPORAL_API_KEY>
```

Start the sample Workflow from your local machine:

```bash
uv run python starter.py "Calculate the first 10 Fibonacci numbers."
```

The starter sends the Workflow to `agentcore-strands-task-queue`. When no Worker is polling, Temporal invokes
the AgentCore Runtime endpoint. The Runtime starts the Worker, and the Worker processes the Workflow and its Activities.

You can confirm the deployment in these places:

- **Temporal Cloud UI**: Open the Workflow Execution and confirm that its Event History progresses.
- **AgentCore logs**: Run `agentcore logs --runtime temporal_strands_worker` to see the Worker start and process Tasks.
- **Temporal CLI**: Run `temporal workflow show --workflow-id agentcore-strands-workflow-id-1` to inspect the Event
  History.

For the sample Workflow and agent implementation, see
[`workflows.py`](https://github.com/temporalio/samples-python/blob/6fd0c9e879e85c4403bf8c1c591f7394fa60bed2/bedrock_agentcore/strands-agent/workflows.py).