Skip to main content

Deploy a Serverless Worker on Amazon Bedrock AgentCore Runtime

View Markdown

This guide walks through deploying a Python Serverless Worker 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. 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.

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 or later, configured for your Namespace.
  • An AWS account in an AgentCore-supported Region.
  • The AWS CLI installed and configured with credentials for that account.
  • Node.js 20 or later and the AgentCore CLI installed with npm install -g @aws/agentcore.
  • The AWS CDK installed and bootstrapped in the target account and Region.
  • Python 3.10 or later and uv installed.
  • Permission to create AgentCore resources, CloudFormation stacks, and IAM roles. See IAM permissions for AgentCore Runtime.

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:

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:

FilePurpose
agentcore_worker.pyDefines the AgentCore Runtime handler and starts the Temporal Worker.
workflows.pyDefines the sample Workflow.
activities.pyDefines the sample Activity.
agentcore/agentcore.jsonConfigures the Runtime, endpoint, environment, and lifecycle.
agentcore/aws-targets.jsonSelects 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, 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:

[
  {
    "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:

{
  "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. 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.

The sample uses a CodeZip build and a public network:

{
  "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.

3. Deploy the Runtime and endpoint​

From the sample directory, run:

./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:

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.
  • The Runtime endpoint ARN for the named temporal endpoint, which you give Temporal in Step 5.

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 attack.

The sample includes a CloudFormation template and a script that deploys it. Pass the Runtime ARN with a trailing wildcard so the policy covers the Runtime and its endpoints:

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

Wait for the CloudFormation stack to finish:

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

Then retrieve the invocation role ARN:

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

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.
  • IAM role ARN: the invocation role ARN from Step 4.
  • External ID: the External ID from Step 4.

Save the Worker Deployment. When you create a version through the UI, the version is automatically current. Continue to Step 7.

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:

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:

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:

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.