# 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 Cloud 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 guide deploys an existing Python [Serverless Worker](/serverless-workers) to Amazon Bedrock AgentCore Runtime and
configures Temporal Cloud to start Worker capacity. It assumes that you already have a Temporal Worker and an AgentCore
project. For the Worker implementation and lifecycle, see
[Serverless Workers on Amazon Bedrock AgentCore Runtime - Python SDK](/develop/python/workers/serverless-workers/agentcore).

If you are still deciding how to structure your agent, Workflow, and Activities, see the
[Python Strands AgentCore sample](https://github.com/temporalio/samples-python/tree/schoeff/strands-agent/bedrock_agentcore/strands-agent)
for a complete application.

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

In `agentcore/agentcore.json`, configure the Runtime with 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 Runtime definition must use your Worker handler as its entrypoint and provide a named endpoint for Temporal. The
following fragment uses a public network so the Worker can reach Temporal Cloud:

```json
{
  "entrypoint": "agentcore_worker.py",
  "networkMode": "PUBLIC",
  "protocol": "HTTP",
  "authorizerType": "AWS_IAM",
  "endpoints": {
    "temporal": {
      "version": 1,
      "description": "Invoked by Temporal Cloud Serverless Workers"
    }
  }
}
```

If you use a VPC instead, configure outbound access from the VPC to your Temporal Cloud Namespace. Temporal invokes the
named endpoint by assuming the IAM role that you create in [Step 3](#configure-iam).

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 handler. 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 Cloud.

## 3. 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. 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:

```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>*' \
  --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**

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.

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.

## 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 Cloud UI**: Open the Worker Deployment Version and confirm that the connection is valid and a Worker has
  polled the Task Queue.
- **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.