Skip to main content

Deploy a Serverless Worker on Amazon Bedrock AgentCore Runtime

View Markdown

This page shows how to add a Python Serverless Worker 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 complete tutorial, see Build a durable agent on Amazon Bedrock AgentCore. That guide starts with the Python Strands AgentCore sample 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.

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 first.
  • Temporal CLI 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, with the AWS CLI configured for that account and permission to create AgentCore resources, CloudFormation stacks, and IAM roles. See IAM permissions for AgentCore Runtime.
  • Node.js 20 or later, the AgentCore CLI, and the AWS CDK installed. Bootstrap the CDK in the target account and Region.

1. Add and configure the Worker Runtime​

Add a Python entry point that creates a Temporal Worker for your Workflows and Activities. Configure the Worker with a Worker Deployment Version, then start it from an AgentCore Runtime handler. The handler keeps the Worker polling in the background after it acknowledges the AgentCore invocation.

agentcore/agentcore.json is the AgentCore CLI project configuration. 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:

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

The entrypoint field names the Python file that AgentCore starts. That file must implement the AgentCore Runtime HTTP protocol contract 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.

The following fragment from the Python Strands AgentCore sample configures that entry point, a public network, and the named endpoint that Temporal invokes:

{
  "name": "temporal_strands_worker",
  "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.

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. Set --target to the name of the deployment target in agentcore/aws-targets.json. For example, if the target is named default, run:

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:

agentcore status --runtime temporal_strands_worker --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.

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

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

3. Grant Temporal permission to invoke the Runtime​

Self-hosted Temporal Service

If you use a self-hosted Temporal Service, create the invocation role during the self-hosted setup. 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 attack.

Download the CloudFormation template, 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. Include the hyphen when checking the combined length. CloudFormation cannot create the role if the combined name exceeds this limit.

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:

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

Then retrieve the invocation role ARN:

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 whose compute configuration points to the named AgentCore Runtime endpoint.

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

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

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:

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.