Skip to content
PromptKit Logo PromptKit

01: First AgentCore Deployment

Deploy a single-agent prompt pack to AWS Bedrock AgentCore, verify it is healthy, and tear it down cleanly.

Time: ~25 minutes

What You’ll Build

Section titled “What You’ll Build”

A single AgentCore runtime running your compiled prompt pack in AWS. By the end, you will have deployed, inspected, and destroyed your first AgentCore resource.

Learning Objectives

Section titled “Learning Objectives”
  • Create an IAM role with the correct trust policy for AgentCore
  • Build the PromptKit runtime binary for AgentCore (Linux ARM64)
  • Configure the AgentCore deploy adapter in arena.yaml
  • Validate your configuration before deploying
  • Preview a deployment plan and understand the resource changes
  • Apply the plan to create AWS resources
  • Invoke the deployed agent via the HTTP bridge
  • Check deployment health with the status command
  • Destroy all resources cleanly

Prerequisites

Section titled “Prerequisites”

Before starting, make sure you have the following ready:

  1. AWS account with Bedrock AgentCore access enabled in your target region.
  2. AWS CLI configured with credentials that have permission to manage AgentCore resources.
  3. PromptKit CLI installed and on your PATH. Verify with:
    Terminal window
    promptarena --version
  4. AgentCore adapter checked out locally (needed to build the runtime binary).
  5. Compiled pack — a .pack.json file produced by packc compile. For this tutorial, any single-agent pack will work. If you do not have one, compile the quickstart example:
    Terminal window
    packc compile -o my-agent.pack.json

Step 1: Create the IAM Role

Section titled “Step 1: Create the IAM Role”

AgentCore runtimes need an IAM role to operate. The role’s trust policy must allow the bedrock-agentcore.amazonaws.com service to assume it.

Create the role (replace YOUR_ACCOUNT_ID and YOUR_REGION with your values):

Terminal window
aws iam create-role \
  --role-name AgentCoreRuntime \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "AssumeRolePolicy",
        "Effect": "Allow",
        "Principal": {"Service": "bedrock-agentcore.amazonaws.com"},
        "Action": "sts:AssumeRole",
        "Condition": {
          "StringEquals": {"aws:SourceAccount": "YOUR_ACCOUNT_ID"},
          "ArnLike": {"aws:SourceArn": "arn:aws:bedrock-agentcore:YOUR_REGION:YOUR_ACCOUNT_ID:*"}
        }
      }
    ]
  }'

Attach the permissions the runtime needs:

Terminal window
# Bedrock model invocation
aws iam attach-role-policy \
  --role-name AgentCoreRuntime \
  --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess


# ECR image pull (required to start the container)
aws iam attach-role-policy \
  --role-name AgentCoreRuntime \
  --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly


# CloudWatch Logs (required for online eval configs and observability)
aws iam attach-role-policy \
  --role-name AgentCoreRuntime \
  --policy-arn arn:aws:iam::aws:policy/CloudWatchLogsReadOnlyAccess

If your pack uses Cedar policies (tool blocklist), the gateway role also needs permission to read the policy engine. Add an inline policy:

Terminal window
aws iam put-role-policy \
  --role-name AgentCoreRuntime \
  --policy-name AgentCorePolicyEngineAccess \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "PolicyEngineAccess",
        "Effect": "Allow",
        "Action": [
          "bedrock-agentcore:GetPolicyEngine",
          "bedrock-agentcore:ListPolicies"
        ],
        "Resource": "*"
      }
    ]
  }'

Note the role ARN for the next step:

Terminal window
aws iam get-role --role-name AgentCoreRuntime --query "Role.Arn" --output text
# e.g. arn:aws:iam::518192007936:role/AgentCoreRuntime

Step 2: Build the Runtime Binary

Section titled “Step 2: Build the Runtime Binary”

The PromptKit runtime binary runs inside AgentCore, serving your agent via HTTP (port 8080) and A2A (port 9000). It must be cross-compiled for Linux ARM64 (AgentCore’s architecture).

From the adapter repository:

Terminal window
cd promptarena-deploy-agentcore
make build-runtime-arm64

This produces a promptkit-runtime binary in the current directory. Note the path for the next step.

Step 3: Create the Deploy Configuration

Section titled “Step 3: Create the Deploy Configuration”

Open your config.arena.yaml file and add a deploy section under spec:. If you do not have an arena config yet, create one:

# config.arena.yaml
apiVersion: promptkit.altairalabs.ai/v1alpha1
kind: Arena
metadata:
  name: my-agent
spec:
  prompt_configs:
    - id: main
      file: prompts/main.yaml


  deploy:
    provider: agentcore
    agentcore:
      region: us-west-2
      runtime_role_arn: arn:aws:iam::123456789012:role/AgentCoreRuntime
      runtime_binary_path: /path/to/promptkit-runtime
      model: claude-3-5-haiku-20241022

Replace the values:

  • region — the AWS region where AgentCore is available (e.g., us-west-2, us-east-1).
  • runtime_role_arn — the full ARN of the IAM role created in Step 1.
  • runtime_binary_path — the path to the cross-compiled runtime binary from Step 2.
  • model — the Bedrock model ID to use (e.g., claude-3-5-haiku-20241022).

The adapter supports additional options (memory, observability, tags) covered in the Configuration Reference.

Step 4: Validate the Configuration

Section titled “Step 4: Validate the Configuration”

Before deploying, confirm that the configuration is syntactically correct and the field values pass validation:

Terminal window
promptarena deploy validate

Expected output on success:

Validating agentcore configuration...
  region:          us-west-2         OK
  runtime_role_arn: arn:aws:iam::123456789012:role/AgentCoreRuntime  OK


Configuration is valid.

If validation fails, the adapter returns specific error messages. For example:

Configuration is invalid:
  - region "us-west2" does not match expected format (e.g. us-west-2)

Fix any reported issues before continuing.

Step 5: Preview the Deployment Plan

Section titled “Step 5: Preview the Deployment Plan”

Run the plan command to see what resources the adapter will create — without making any changes to AWS:

Terminal window
promptarena deploy plan

For a single-agent pack named my-agent, you will see output like this:

Planning agentcore deployment...


  agent_runtime  my-agent  CREATE  Create AgentCore runtime for my-agent


Plan: 1 to create, 0 to update, 0 to delete

The plan tells you:

  • Resource type: agent_runtime — a Bedrock AgentCore runtime container.
  • Name: derived from your pack ID.
  • Action: CREATE because no prior deployment state exists.

If your pack includes tools, validators, or memory configuration, additional resources will appear:

  memory          my-agent_memory       CREATE  Create memory store (session) for my-agent
  cedar_policy    main                  CREATE  Create Cedar policy for prompt main
  agent_runtime   my-agent              CREATE  Create AgentCore runtime for my-agent


Plan: 3 to create, 0 to update, 0 to delete

Review the plan and proceed when it looks correct.

Step 6: Deploy

Section titled “Step 6: Deploy”

Apply the plan to create the resources in AWS:

Terminal window
promptarena deploy

The adapter streams progress as each resource is created:

Deploying to agentcore...


  [  0%] Creating agent_runtime: my-agent
  [ 45%] Creating agent_runtime: my-agent (polling for READY status)
  [ 50%] Created agent_runtime: my-agent
         ARN: arn:aws:bedrock:us-west-2:123456789012:agent-runtime/abcd1234


Deploy complete. 1 resource created.

The runtime creation includes a polling phase — the adapter waits until the runtime transitions from CREATING to READY before reporting success. This typically takes 30-90 seconds.

Step 7: Invoke the Agent

Section titled “Step 7: Invoke the Agent”

Once deployed, you can invoke your agent via the InvokeAgentRuntime API. The runtime ARN is in the deploy state output.

Using the AWS CLI:

Terminal window
aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent-xxxx" \
  --runtime-session-id "test-session-1" \
  --payload '{"prompt": "Explain machine learning in one sentence."}' \
  --content-type "application/json" \
  --accept "application/json" \
  /dev/stdout

The HTTP bridge on port 8080 accepts the payload and returns:

{"response": "Machine learning is...", "status": "success"}

The payload supports both prompt and input field names for compatibility with the AWS ecosystem convention.

Step 8: Verify Deployment Health

Section titled “Step 8: Verify Deployment Health”

Confirm that the deployed resources are healthy:

Terminal window
promptarena deploy status

Expected output:

AgentCore deployment status: deployed


  agent_runtime  my-agent  healthy


1 resource, all healthy.

Each resource is checked against the AWS API. Possible statuses are:

  • healthy — the resource exists and is functioning normally.
  • unhealthy — the resource exists but is in a degraded state.
  • missing — the resource was expected but could not be found in AWS.

If any resource is unhealthy or missing, the aggregate status changes to degraded.

Step 9: Destroy the Deployment

Section titled “Step 9: Destroy the Deployment”

When you are done, tear down all resources:

Terminal window
promptarena deploy destroy

The adapter deletes resources in reverse dependency order:

Destroying agentcore deployment...


  Destroying 1 resources
  Step 1: deleting agent_runtime resources (1)
  Deleted agent_runtime "my-agent"


Destroy complete.

Run promptarena deploy status again to confirm nothing remains:

AgentCore deployment status: not_deployed

What You Learned

Section titled “What You Learned”
  • The deploy.agentcore section in arena.yaml requires region, runtime_role_arn, runtime_binary_path, and model for a basic deployment.
  • promptarena deploy validate catches configuration errors before you spend time on a real deployment.
  • promptarena deploy plan previews the exact resources that will be created, updated, or deleted.
  • promptarena deploy creates the resources and polls until they are ready.
  • promptarena deploy status checks the health of every deployed resource.
  • promptarena deploy destroy tears down resources in the correct dependency order.

Common Issues

Section titled “Common Issues”

Invalid Region Format

Section titled “Invalid Region Format”
region "uswest2" does not match expected format (e.g. us-west-2)

The region must be a valid AWS region identifier in the format xx-xxxx-N (e.g., us-west-2, eu-central-1). Check the AWS region list for regions that support Bedrock AgentCore.

Role Validation Failed

Section titled “Role Validation Failed”
ValidationException: Role validation failed for 'arn:aws:iam::...:role/AgentCoreRuntime'.
Please verify that the role exists and its trust policy allows assumption by this service

The runtime role’s trust policy must allow bedrock-agentcore.amazonaws.com to assume it (not bedrock.amazonaws.com). Verify the trust policy:

Terminal window
aws iam get-role --role-name AgentCoreRuntime --query "Role.AssumeRolePolicyDocument"

The Principal.Service must be bedrock-agentcore.amazonaws.com. See Step 1 for the correct trust policy.

Missing IAM Permissions

Section titled “Missing IAM Permissions”
agentcore: create agent_runtime "my-agent": AccessDeniedException:
  User is not authorized to perform bedrock:CreateAgentRuntime

The AWS credentials used by the CLI (not the runtime role) need permission to manage AgentCore resources. Ensure your IAM user or role has the bedrock:*AgentRuntime* permissions, or use the AWS-managed AmazonBedrockAgentCoreDeveloperAccess policy.

The runtime role (runtime_role_arn) is a separate concern — it is the role the runtime assumes when it runs. It needs bedrock:InvokeModel and related permissions.

Account Mismatch

Section titled “Account Mismatch”
AWS caller account 111111111111 does not match runtime_role_arn account 222222222222

The AWS credentials you are using belong to a different account than the one in your runtime_role_arn. Either update the role ARN to use your account ID, or switch to credentials for the correct account.

Runtime Stuck in CREATING

Section titled “Runtime Stuck in CREATING”
agentcore: create agent_runtime "my-agent": timed out waiting for READY status

The adapter polls for up to 5 minutes waiting for the runtime to become READY. If it times out:

  1. Check the AWS Console under Bedrock > AgentCore to see the runtime’s actual status.
  2. Look for error details in the runtime’s event log.
  3. Common causes: the runtime role ARN is invalid, the role lacks a trust policy for bedrock-agentcore.amazonaws.com, or the region does not have AgentCore capacity.
  4. After fixing the issue, run promptarena deploy again — the adapter will detect the existing resource and attempt an update rather than creating a duplicate.

Role ARN Validation Error

Section titled “Role ARN Validation Error”
runtime_role_arn "arn:aws:iam:123456789012:role/MyRole" is not a valid IAM role ARN

The ARN must follow the exact format arn:aws:iam::<12-digit-account-id>:role/<role-name>. Note the double colon (::) between iam and the account ID. A common mistake is using a single colon.

Next Steps

Section titled “Next Steps”