Skip to main content

Deploy a Serverless Worker on Amazon Bedrock AgentCore Runtime

View Markdown

This guide deploys an existing Python Serverless Worker 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.

If you are still deciding how to structure your agent, Workflow, and Activities, see the Python Strands AgentCore sample 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 or later, configured for your Namespace.
  • An existing Python Temporal Worker with an 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.
  • 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.
  • Permission to create AgentCore resources, CloudFormation stacks, and IAM roles. See IAM permissions for AgentCore Runtime.

1. Configure the Worker Runtime​

In agentcore/agentcore.json, configure the Runtime with 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 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:

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

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:

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:

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

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:

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.

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:

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.