Pega Blueprint AI Agent — Setup Guide

This guide covers the full setup for deploying the Pega Blueprint AI Agent (subscribed from AWS Marketplace) on Amazon Bedrock AgentCore Runtime and connecting it to the AWS Transform (ATX) console.

1. Requirements

• A valid Pega GenAI Blueprint account/entitlement. This agent integrates with the Pega Blueprint platform and cannot function without Pega-provided credentials (OAuth client + signing key).
• AWS Transform composable-framework access (partner-gated — see note above).
• An AWS account in us-east-1 with permissions to create IAM roles, Secrets Manager secrets, and Amazon Bedrock AgentCore runtimes.
• AWS CLI and (optionally) Docker installed, or use AWS CloudShell.

The blueprint owner is resolved automatically from the identity of the user signed in to the AWS Transform console — identity is enforced from the authenticated session, not supplied manually.

2. Create Secrets in AWS Secrets Manager (us-east-1)

Obtain the OAuth client credentials and signing key from your Pega Blueprint administrator, then create two secrets:

Signing key

Secret name: pega-blueprint-agent/jwt-signing-key
Value: the RSA private key in PEM format (plaintext). The matching public key must be registered with Pega's JWKS endpoint by your Pega administrator.

aws secretsmanager create-secret \
  --name pega-blueprint-agent/jwt-signing-key \
  --secret-string file://signing-key.pem \
  --region us-east-1

OAuth client

Secret name: pega-blueprint-agent/oauth-client
Value (JSON):

{"client_id":"<client-id>","client_secret":"<client-secret>"}

aws secretsmanager create-secret \
  --name pega-blueprint-agent/oauth-client \
  --secret-string '{"client_id":"<client-id>","client_secret":"<client-secret>"}' \
  --region us-east-1

To use different secret names, set the environment variables PEGA_JWT_KEY_SECRET and PEGA_OAUTH_CLIENT_SECRET on the runtime.

3. IAM Execution Role

The AgentCore runtime needs an execution role it can assume. Step 3a: save the trust policy below to a file named trust-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Service": "bedrock-agentcore.amazonaws.com" },
    "Action": "sts:AssumeRole"
  }]
}

Step 3b: create the role from that trust policy:

aws iam create-role \
  --role-name pega-blueprint-agent-role \
  --assume-role-policy-document file://trust-policy.json

Step 3c: save the permissions policy below to a file named permissions-policy.json (replace <ACCOUNT_ID> with your 12-digit AWS account ID):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ECRImageAccess",
      "Effect": "Allow",
      "Action": ["ecr:BatchGetImage","ecr:GetDownloadUrlForLayer"],
      "Resource": "arn:aws:ecr:us-east-1:709825985650:repository/*"
    },
    { "Sid": "ECRAuth", "Effect": "Allow", "Action": "ecr:GetAuthorizationToken", "Resource": "*" },
    {
      "Sid": "SecretsManagerAccess",
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": [
        "arn:aws:secretsmanager:us-east-1:<ACCOUNT_ID>:secret:pega-blueprint-agent/jwt-signing-key-*",
        "arn:aws:secretsmanager:us-east-1:<ACCOUNT_ID>:secret:pega-blueprint-agent/oauth-client-*"
      ]
    },
    { "Sid": "IdentityStoreAccess", "Effect": "Allow", "Action": "identitystore:DescribeUser", "Resource": "*" },
    {
      "Sid": "CloudWatchLogs",
      "Effect": "Allow",
      "Action": ["logs:CreateLogGroup","logs:CreateLogStream","logs:PutLogEvents","logs:DescribeLogStreams","logs:DescribeLogGroups"],
      "Resource": "arn:aws:logs:us-east-1:<ACCOUNT_ID>:*"
    }
  ]
}

Step 3d: attach the permissions policy to the role:

aws iam put-role-policy \
  --role-name pega-blueprint-agent-role \
  --policy-name pega-blueprint-agent-permissions \
  --policy-document file://permissions-policy.json

The role ARN printed by Step 3b (arn:aws:iam::<ACCOUNT_ID>:role/pega-blueprint-agent-role) is used as the runtime's execution role in Section 4.

4. Create the AgentCore Runtime

Create the runtime from the Marketplace container image, using the execution role from Section 3. You can do this from the Amazon Bedrock AgentCore console (AWS Marketplace provides the standard launch flow) or from the CLI below.

Create via CLI

Replace <ACCOUNT_ID> and <IDENTITY_STORE_ID> with your values:

aws bedrock-agentcore-control create-agent-runtime \
  --region us-east-1 \
  --agent-runtime-name pega_blueprint_agent \
  --agent-runtime-artifact '{"containerConfiguration":{"containerUri":"709825985650.dkr.ecr.us-east-1.amazonaws.com/pegasystems/blueprint_agent:1.0.1"}}' \
  --role-arn "arn:aws:iam::<ACCOUNT_ID>:role/pega-blueprint-agent-role" \
  --network-configuration '{"networkMode":"PUBLIC"}' \
  --environment-variables '{"IDENTITY_STORE_ID":"<IDENTITY_STORE_ID>"}'

The command returns an agentRuntimeId and agentRuntimeArn — note both, you need the ARN in Section 5. Wait until the runtime reports READY:

aws bedrock-agentcore-control get-agent-runtime \
  --agent-runtime-id <agentRuntimeId> \
  --region us-east-1 \
  --query status

To confirm the container started, check that GET /ping returns 200 in the logs at /aws/bedrock-agentcore/runtimes/<agentRuntimeId>-DEFAULT.

Find your Identity Store ID

aws sso-admin list-instances --region us-east-1 \
  --query 'Instances[0].IdentityStoreId' --output text

Required environment variable

Optional environment variables

5. Register the Agent with AWS Transform

5.1 Load the registry service model (one time)

The AWS Transform agent registry is not a standard AWS service, so you must load its service model into the AWS CLI before the aws atxagentregistryexternal commands become available. Add the model, then verify:

aws configure add-model \
  --service-name atxagentregistryexternal \
  --service-model "file://atxagentregistryexternal-2022-07-26.normal.json"

# Verify the commands are now available
aws atxagentregistryexternal help

After this, the aws atxagentregistryexternal commands are available. The prod registry endpoint is https://iad.prod.agent-registry-external.elastic-gumby.ai.aws.dev (us-east-1).

5.2 Register the agent

aws atxagentregistryexternal register-agent \
  --name <agent-name> \
  --metadata '{"type":"ORCHESTRATOR_AGENT","description":"Pega Blueprint AI Agent","ownerName":"<your-org>","ownerContactInfo":"<contact-email>"}' \
  --endpoint-url https://iad.prod.agent-registry-external.elastic-gumby.ai.aws.dev \
  --region us-east-1

Agent names must be lowercase alphanumeric with hyphens. Agents are created with RESTRICTED visibility.

5.3 Publish a version

Publish a version pointing at the runtime ARN from Section 4 and your ATX invoke role (Section 5.4). Replace the placeholders:

aws atxagentregistryexternal publish-agent-version \
  --name <agent-name> \
  --version 1.0.0 \
  --configuration '{
    "shortDescription": "Pega Blueprint AI Agent",
    "computeConfiguration": {
      "provisionedComputeConfiguration": {
        "agentCoreConfiguration": {
          "atxAccessRoleArn": "arn:aws:iam::<ACCOUNT_ID>:role/AWSTransformAgentInvokeRole",
          "runtimeArn": "arn:aws:bedrock-agentcore:us-east-1:<ACCOUNT_ID>:runtime/<runtime-id>",
          "qualifier": "DEFAULT"
        }
      }
    },
    "monitoringType": "HEALTHCHECK",
    "notificationsEnabled": "ENABLED",
    "objectiveNegotiationPrompt": "",
    "agentCard": {
      "id": "<agent-name>",
      "name": "Pega Blueprint AI Agent",
      "description": "Creates Pega GenAI Blueprint application designs from natural language prompts.",
      "version": "1.0.0",
      "capabilities": {
        "restartable": true,
        "a2aSupported": true,
        "webAppV2": true
      }
    },
    "inputPayloadSchema": {"type": "object"},
    "outputPayloadSchema": {"type": "object"}
  }' \
  --endpoint-url https://iad.prod.agent-registry-external.elastic-gumby.ai.aws.dev \
  --region us-east-1

The version progresses CREATED → IN_VERIFICATION → ACTIVE.

5.4 ATX Invoke Role

AWS Transform assumes this role in your account to invoke the runtime. Name it AWSTransformAgentInvokeRole with this trust policy:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Service": "prod.us-east-1.compute.elastic-gumby.aws.internal" },
    "Action": "sts:AssumeRole"
  }]
}

Permissions: bedrock-agentcore:InvokeAgentRuntime, GetAgentRuntime, GetAgentRuntimeEndpoint, ListAgentRuntimeEndpoints, ListAgentRuntimeVersions, ListAgentRuntimes, StopRuntimeSession on *.

5.5 Grant access to your account

aws atxagentregistryexternal update-publisher-access-control \
  --agent-name <agent-name> \
  --customer-account-id <your-12-digit-account-id> \
  --access-control ENABLED \
  --endpoint-url https://iad.prod.agent-registry-external.elastic-gumby.ai.aws.dev \
  --region us-east-1

Returns an empty body on success. The agent now appears in the AWS Transform console for that account.

6. Using the Agent

From the AWS Transform console, send a natural-language prompt, for example:

Create a blueprint called "Customer Service App" for a customer service
application. Industry: Financial Services. Upload the file from
s3://my-bucket/requirements.zip

The agent authenticates as the signed-in AWS Transform user, extracts files from a ZIP if provided (up to 20), uploads them, and returns a Blueprint ID with a direct link.

Supported file sources: S3 URI (s3://bucket/key), HTTP/HTTPS URL, or ZIP archive (HTML, Markdown, PDF, and other document types extracted and uploaded individually).

7. Troubleshooting

8. References

• AWS Transform Agent Toolkit — official tooling and steering docs for building, deploying, and registering AWS Transform agents (includes the SDK, registry service models, and registration workflow): https://github.com/kirodotdev/powers/tree/main/aws-transform-agent-toolkit
• AWS Transform Agent SDK — agent-builder-sdk-aws-transform (currently a placeholder on PyPI; the full release that ships the registry service models is forthcoming). Until then, obtain the service model through Pega onboarding.
• Listing container-based AI agents on AWS Marketplace — AWS Marketplace User Guide