Skip to main content

Deploy a Serverless Worker on Amazon Bedrock AgentCore Runtime

View Markdown

This page covers only deploying an existing Python Serverless Worker 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. 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, or a self-hosted Temporal Service v1.32.0 or later.
  • For self-hosted deployments, complete the 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 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​

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:

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

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.

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.