# 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 an existing Python Worker to AgentCore Runtime and configure Temporal to start capacity when Task Queue demand increases.

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

This page covers only deploying an existing Python [Serverless Worker](/serverless-workers) to Amazon Bedrock AgentCore
Runtime and connecting it to a Worker Deployment Version. It assumes that your Worker and AgentCore project are already
in place.

For a complete tutorial, 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/schoeff/strands-agent/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 

- A Temporal Cloud account with an AWS-hosted Namespace and access to the AgentCore Serverless Workers Pre-release, or
  a self-hosted Temporal Service v1.32.0 or later.
- For self-hosted deployments, complete the
  [self-hosted setup](/production-deployment/worker-deployments/serverless-workers/agentcore/self-hosted-setup) before
  following this guide.
- Credentials that let the Worker connect to the Temporal Service. The example configuration uses a Temporal Cloud API
  key.
- [Temporal CLI v1.8.3](https://github.com/temporalio/cli/releases/tag/v1.8.3) or later, configured for your Namespace.
- An existing Python Temporal Worker with an
  [AgentCore Runtime handler](/develop/python/workers/serverless-workers/agentcore#runtime-handler).
- An AgentCore project that packages the Worker and contains `agentcore/agentcore.json`, `agentcore/aws-targets.json`,
  and the generated AgentCore CDK project.
- 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.
- 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).

## 1. Configure the 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. In the existing Runtime object, configure
the Temporal connection, Task Queue, Worker Deployment name, and Build ID:

```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": "<TASK_QUEUE>"
},
{
  "name": "TEMPORAL_DEPLOYMENT_NAME",
  "value": "<DEPLOYMENT_NAME>"
},
{
  "name": "TEMPORAL_BUILD_ID",
  "value": "<BUILD_ID>"
}
```

The Task Queue must match the Task Queue used by your application. The deployment name and Build ID must match the
Worker Deployment Version that you create in [Step 4](#create-worker-deployment-version).

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
{
  "entrypoint": "agentcore_worker.py",
  "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. Verify the named endpoint's
version after deployment in [Step 2](#deploy-runtime).

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. Deploy the Worker Runtime 

From the AgentCore project directory, validate and deploy the project:

```bash
agentcore validate
agentcore deploy --target <TARGET> -y
```

AgentCore packages the Worker and its dependencies, deploys the Runtime, and creates the named endpoint.

Check the deployed resources:

```bash
agentcore status --runtime <RUNTIME_NAME> --json
agentcore status --type runtime-endpoint --json
```

Record the Runtime ARN and the ARN of the named endpoint. You use the Runtime ARN to scope the invocation role and give
the endpoint ARN to Temporal.

AgentCore creates an immutable Runtime version when you create or update a Runtime. A named endpoint remains pinned to
its configured version until you update it. For details, see [AgentCore Runtime versioning and
endpoints](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agent-runtime-versioning.html).

Confirm that the endpoint's live version matches the Runtime version containing the Worker code and environment
configuration that you intend to deploy:

```bash
aws bedrock-agentcore-control get-agent-runtime-endpoint \
  --agent-runtime-id <RUNTIME_ID> \
  --endpoint-name <ENDPOINT_NAME> \
  --query '{status:status,liveVersion:liveVersion}' \
  --region <AWS_REGION>
```

> **⚠️ Caution:**
> Verify the endpoint version after redeploying
>
> If you redeploy the Runtime without updating its named endpoint, Temporal continues to invoke the earlier Worker code.
> Creating the Worker Deployment Version can then time out if that code does not acknowledge the invocation promptly or
> does not register the expected deployment name and Build ID.
>
> For a later Worker version, create or update a named endpoint to use the new Runtime version. Use that endpoint ARN for
> the corresponding Worker Deployment Version. Keep endpoints used by existing Worker Deployment Versions pinned to
> their original Runtime versions.
>

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 3](#configure-iam).

## 3. Grant Temporal permission to invoke the Runtime 

> **ℹ️ 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 `<ROLE_NAME>-<STACK_NAME>`. 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 <STACK_NAME> \
  --template-body file://temporal-cloud-serverless-worker-agentcore-role.yaml \
  --parameters \
    ParameterKey=AssumeRoleExternalId,ParameterValue=<EXTERNAL_ID> \
    ParameterKey=AgentRuntimeARNs,ParameterValue='<AGENT_RUNTIME_ARN>*' \
    ParameterKey=RoleName,ParameterValue=<ROLE_NAME> \
  --capabilities CAPABILITY_NAMED_IAM \
  --region <AWS_REGION>
```

Wait for the CloudFormation stack to finish:

```bash
aws cloudformation wait stack-create-complete \
  --stack-name <STACK_NAME> \
  --region <AWS_REGION>
```

Then retrieve the invocation role ARN:

```bash
aws cloudformation describe-stacks \
  --stack-name <STACK_NAME> \
  --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. This role does not run the Worker code.

## 4. 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.

**Temporal Cloud UI**

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 2](#deploy-runtime).
- **IAM role ARN**: the invocation role ARN from [Step 3](#configure-iam).
- **External ID**: the External ID from [Step 3](#configure-iam).

Save the Worker Deployment. When you create a version through the UI, the version is automatically current. Continue
to [Step 6](#verify-worker-startup).

**Temporal CLI**

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 <TEMPORAL_NAMESPACE> \
  --name <DEPLOYMENT_NAME>
```

Then create the version with the AgentCore compute configuration:

```bash
temporal worker deployment create-version \
  --namespace <TEMPORAL_NAMESPACE> \
  --deployment-name <DEPLOYMENT_NAME> \
  --build-id <BUILD_ID> \
  --aws-agentcore-endpoint-arn <RUNTIME_ENDPOINT_ARN> \
  --aws-agentcore-assume-role-arn <INVOCATION_ROLE_ARN> \
  --aws-agentcore-assume-role-external-id <EXTERNAL_ID>
```

The deployment name and Build ID must match the values in the Runtime environment.

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.

## 5. 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 <DEPLOYMENT_NAME> \
  --build-id <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.

## 6. 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 <RUNTIME_NAME>` to see the Worker start and process Tasks.
- **Temporal CLI**: Run `temporal worker deployment describe --name <DEPLOYMENT_NAME>` to inspect the deployment and
  current version.