For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Connect Solo Enterprise for agentregistry to an AWS Bedrock AgentCore runtime so that you can deploy agents and MCP servers to AgentCore.

This guide walks you through how to connect Solo Enterprise for agentregistry to AWS Bedrock AgentCore, so that you can deploy agents and MCP servers from the registry into it. By the end, you have a Runtime resource that points the registry at your AgentCore environment and a managed gateway that routes traffic between the registry and deployed workloads.

Before you begin

1. Set up an OIDC provider. This guide assumes that you installed Keycloak. Make sure to follow the General setup tab to install Keycloak with the required realm settings, clients, and secrets.

2. Install Solo Enterprise for agentregistry on Amazon EKS. After the install, confirm that the following environment variables are set in your current terminal session.

   echo "AWS_REGION: $AWS_REGION"
   echo "AWS_ACCOUNT_ID: $AWS_ACCOUNT_ID"
   echo "KEYCLOAK_ISSUER: $KEYCLOAK_ISSUER"

Step 1: Set up the runtime IAM role

Generate a CloudFormation template and deploy it into your account. The template creates an IAM role that Solo Enterprise for agentregistry assumes to deploy and manage Bedrock AgentCore resources on your behalf, along with all required IAM policies. With CloudFormation, you get a reviewable, auditable definition of all the resources that are created in your account.

1. Generate the AWS CloudFormation template and save it in a YAML file. The following command generates a resource stack template that is scoped to your account ID.

   arctl runtime setup bedrock-agent-core --aws-account-id $AWS_ACCOUNT_ID > cloudformation.yaml

   The External ID and Role Name are printed to your CLI output and are also embedded in the cloudformation.yaml file. However, the External ID parameter is marked NoEcho: true, which means AWS masks it when you describe the stack or view it in the console. Make sure to note the External ID from the CLI output now so you have it later.

   Example output:

   # External ID: NzqfvveAy0XSEsL4ZtKcHR1li-3puJAbipQDQG8ylmg
   # Role Name: AgentRegistryAccessRole-a11111
   

2. Save the External ID in an environment variable. Replace <external-id> with the value from the previous step.

   export AWS_EXTERNAL_ID="<external-id>"

3. Optional: Review the template before deploying it.

   cat cloudformation.yaml

4. Deploy the CloudFormation stack.

   1. Choose a name for your stack.

      export STACK_NAME="<stack-name>"

   2. Create the AWS stack. The --capabilities CAPABILITY_NAMED_IAM flag is required because the template creates an IAM role, and AWS requires explicit acknowledgment when a CloudFormation template creates IAM resources. If the command succeeds, you see a StackId and OperationId in your CLI output.

      aws cloudformation create-stack \
        --stack-name $STACK_NAME \
        --template-body file://cloudformation.yaml \
        --region $AWS_REGION \
        --capabilities CAPABILITY_NAMED_IAM

      Example output:

      {
        "StackId": "arn:aws:cloudformation:us-west-2:1234567890:stack/agentregistry-cli-stack/1a1aaa11-1111-11a1-aa11-1111a1111aa1",
        "OperationId": "1aaa1a1a-1111-11aa-1a1a-1aaa11a1a111"
      }
      

   3. Wait for the stack to reach CREATE_COMPLETE.

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

5. Store the RoleArn of the IAM role that was created by the CloudFormation template in an environment variable. Solo Enterprise for agentregistry assumes this role to deploy and manage Bedrock AgentCore resources in your AWS account.

   export AWS_ROLE_ARN=$(aws cloudformation describe-stacks \
     --stack-name $STACK_NAME \
     --query 'Stacks[0].Outputs[?OutputKey==`RoleArn`].OutputValue' \
     --output text \
     --region $AWS_REGION)
   echo $AWS_ROLE_ARN

Step 2: Register the AgentCore runtime

Register the AWS Bedrock AgentCore runtime with Solo Enterprise for agentregistry. The runtime connects the registry server to your AWS account so that agents and MCP servers can be deployed to Bedrock AgentCore.

1. Get the OpenTelemetry collector load balancer hostname. The registry deploys an OTel collector alongside the control plane. Agent and MCP server runtimes use this endpoint to export traces and metrics.

   export OTEL_HOST=$(kubectl -n agentregistry-system get svc \
     agentregistry-enterprise-telemetry-collector \
     -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
   echo "OTel endpoint: http://${OTEL_HOST}:4318"

2. Register the AWS Bedrock AgentCore runtime.

   arctl apply -f- <<EOF
   apiVersion: ar.dev/v1alpha1
   kind: Runtime
   metadata:
     name: agentcore
   spec:
     type: BedrockAgentCore
     telemetryEndpoint: http://${OTEL_HOST}:4318
     config:
       roleArn: $AWS_ROLE_ARN
       externalId: $AWS_EXTERNAL_ID
       region: $AWS_REGION
   EOF

   Example output:

   ✓ Runtime/agentcore created
   

3. List the runtimes that are connected to Solo Enterprise for agentregistry and verify that the Bedrock AgentCore runtime is listed.

   arctl get runtimes

   Example output:

   NAME                 TYPE
   agentcore            BedrockAgentCore
   kubernetes-default   kubernetes
   local                local
   

Step 3: Create the managed gateway (optional)

Create a gateway proxy to route traffic between agents and MCP servers, or to enforce RuntimeAccessPolicy resources. The gateway runs as a Kubernetes deployment in your EKS cluster.

1. Create the managed gateway. The registry provisions the AWS compute infrastructure for your gateway by using the role ARN that you set in the Runtime resource and spins up a Kubernetes deployment for the gateway in your cluster.

   arctl apply -f- <<EOF
   apiVersion: ar.dev/v1alpha1
   kind: Gateway
   metadata:
     name: gateway-agentcore
   spec:
     kubernetes: {}
   EOF

   Example output:

   ✓ Gateway/gateway-agentcore created
   

2. Wait for the gateway to reach phase=ready. Provisioning the EC2 instance and installing the agentgateway binary typically takes 5–10 minutes to complete.

   arctl get gateways

   Repeat the command every minute until you see ready in the PHASE column:

   NAME               PROVIDER   MODE      PHASE
   gateway-agentcore  agentcore  managed   ready
   

   Note

   If the gateway reaches phase=failed, check the gateway details for an error message: arctl get gateway gateway-agentcore -o yaml.

3. Update the Runtime to reference the gateway that you created in the spec.config.gatewayRef field.

   arctl apply -f- <<EOF
   apiVersion: ar.dev/v1alpha1
   kind: Runtime
   metadata:
     name: agentcore
   spec:
     type: BedrockAgentCore
     telemetryEndpoint: http://${OTEL_HOST}:4318
     config:
       roleArn: $AWS_ROLE_ARN
       externalId: $AWS_EXTERNAL_ID
       region: $AWS_REGION
       gatewayRef:
         name: gateway-agentcore
   EOF

   Field	Description
   spec.config.gatewayRef.name	The name of the Gateway resource to attach to this Runtime. Must be in the same namespace. When set, the registry rewrites all agent MCP server URLs to route through the gateway and, for harness agents, injects the agent-proxy bootstrap so outbound traffic is captured.

Step 4: Set up the harness runner (harness agents only)

If you plan to deploy harness agents to AgentCore, you must configure a harness runner image on the Runtime for each harness type you want to use. A harness agent is an agent that is composed from plugins, skills, and a system prompt that you added to the registry catalog. Instead of running your own agent code, the registry deploys a prebuilt harness runner container to AgentCore that assembles and runs the agent for you. Two harness types are supported: Claude Code and OpenClaw.

About the harness runner

A harness runner is a container that receives the components that were defined in the agent definition from the registry at startup and configures them for the harness:

• Plugins are mounted as plugin directories. Each plugin adds slash commands that the harness can invoke during a conversation.
• Skills are linked into the harness configuration directory and auto-discovered as available workflows.
• Instructions are written to the workspace system prompt file and loaded at session start.
• MCP servers are configured so the agent sees exactly the configured servers. Remote MCP servers at public URLs are called directly by the agent. When spec.config.gatewayRef is set on the Runtime, MCP server URLs are instead rewritten to route through the managed gateway — required for MCP servers deployed to AgentCore.
• Model is passed to the harness by using the spec.model field from the Model catalog entry.

In addition to agent-specific components, every harness runner includes the harness’s built-in capabilities. For Claude Code, this includes software engineering tools (read, write, and edit code, run shell commands, search codebases), built-in slash commands (such as /code-review, /deep-research, and /security-review), and git and GitHub operations.

Set up the harness runner image

Repeat the following steps for each harness type you want to use. The steps below show the Claude Code harness; substitute the OpenClaw values where indicated.

1. Create a private ECR repository for the harness runner image.

   aws ecr create-repository \
     --repository-name agentregistry/agentcore-claude-runner \
     --region $AWS_REGION

   aws ecr create-repository \
     --repository-name agentregistry/agentcore-openclaw-runner \
     --region $AWS_REGION

   Example output:

   {
     "repository": {
       "repositoryUri": "802411188784.dkr.ecr.us-east-1.amazonaws.com/agentregistry/agentcore-claude-runner",
       ...
     }
   }
   

2. Save the repository URI in an environment variable.

   export CLAUDE_HARNESS_IMAGE_REPO=$(aws ecr describe-repositories \
     --repository-names agentregistry/agentcore-claude-runner \
     --region $AWS_REGION \
     --query 'repositories[0].repositoryUri' \
     --output text)
   echo $CLAUDE_HARNESS_IMAGE_REPO

   export OPENCLAW_HARNESS_IMAGE_REPO=$(aws ecr describe-repositories \
     --repository-names agentregistry/agentcore-openclaw-runner \
     --region $AWS_REGION \
     --query 'repositories[0].repositoryUri' \
     --output text)
   echo $OPENCLAW_HARNESS_IMAGE_REPO

3. Authenticate Docker to your ECR registry.

   aws ecr get-login-password --region $AWS_REGION \
     | docker login --username AWS --password-stdin \
       ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com

4. Pull the published harness runner image and push it to your ECR repository. Replace <published-image> with the harness runner image reference that is provided by your Solo account team, and <tag> with the version tag.

   export CLAUDE_HARNESS_IMAGE_TAG="<tag>"
   docker pull <claude-published-image>
   docker tag <claude-published-image> ${CLAUDE_HARNESS_IMAGE_REPO}:${CLAUDE_HARNESS_IMAGE_TAG}
   docker push ${CLAUDE_HARNESS_IMAGE_REPO}:${CLAUDE_HARNESS_IMAGE_TAG}
   export CLAUDE_HARNESS_IMAGE_REF="${CLAUDE_HARNESS_IMAGE_REPO}:${CLAUDE_HARNESS_IMAGE_TAG}"
   echo $CLAUDE_HARNESS_IMAGE_REF

   export OPENCLAW_HARNESS_IMAGE_TAG="<tag>"
   docker pull <openclaw-published-image>
   docker tag <openclaw-published-image> ${OPENCLAW_HARNESS_IMAGE_REPO}:${OPENCLAW_HARNESS_IMAGE_TAG}
   docker push ${OPENCLAW_HARNESS_IMAGE_REPO}:${OPENCLAW_HARNESS_IMAGE_TAG}
   export OPENCLAW_HARNESS_IMAGE_REF="${OPENCLAW_HARNESS_IMAGE_REPO}:${OPENCLAW_HARNESS_IMAGE_TAG}"
   echo $OPENCLAW_HARNESS_IMAGE_REF

5. Update the Runtime resource to include the harness image references. Add one entry for each harness type that you set up. When you first deploy a harness agent against this Runtime, the registry automatically scopes the AgentCore execution role to allow pulling from the configured ECR repositories.

   arctl apply -f- <<EOF
   apiVersion: ar.dev/v1alpha1
   kind: Runtime
   metadata:
     name: agentcore
   spec:
     type: BedrockAgentCore
     telemetryEndpoint: http://${OTEL_HOST}:4318
     config:
       roleArn: $AWS_ROLE_ARN
       externalId: $AWS_EXTERNAL_ID
       region: $AWS_REGION
       harnessImages:
         claude-code: "${CLAUDE_HARNESS_IMAGE_REF}"
         openclaw: "${OPENCLAW_HARNESS_IMAGE_REF}"
       gatewayRef:
         name: gateway-agentcore
   EOF

   Field	Description
   spec.config.harnessImages.claude-code	The ECR image URI for the Claude Code harness runner.
   spec.config.harnessImages.openclaw	The ECR image URI for the OpenClaw harness runner.

Next steps