When deploying AI agents to Amazon Bedrock AgentCore Runtime (currently in preview), customers often want to use custom domain names to create a professional and seamless experience.
By default, AgentCore Runtime agents use endpoints like https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{EncodedAgentARN}/invocations.
In this post, we discuss how to transform these endpoints into user-friendly custom domains (like https://agent.yourcompany.com) using Amazon CloudFront as a reverse proxy. The solution combines CloudFront, Amazon Route 53, and AWS Certificate Manager (ACM) to create a secure, scalable custom domain setup that works seamlessly with your existing agents.
Benefits of Amazon Bedrock AgentCore Runtime
If you’re building AI agents, you have probably wrestled with hosting challenges: managing infrastructure, handling authentication, scaling, and maintaining security. Amazon Bedrock AgentCore Runtime helps address these problems.
Amazon Bedrock AgentCore Runtime is framework agnostic; you can use it with LangGraph, CrewAI, Strands Agents, or custom agents you have built from scratch. It supports extended execution times up to 8 hours, perfect for complex reasoning tasks that traditional serverless functions can’t handle. Each user session runs in its own isolated microVM, providing security that’s crucial for enterprise applications.
The consumption-based pricing model means you only pay for what you use, not what you provision. And unlike other hosting solutions, Amazon Bedrock AgentCore Runtime includes built-in authentication and specialized observability for AI agents out of the box.
Benefits of custom domains
When using Amazon Bedrock AgentCore Runtime with Open Authorization (OAuth) authentication, your applications make direct HTTPS requests to the service endpoint. Although this works, custom domains offer several benefits:
- Custom branding – Client-side applications (web browsers, mobile apps) display your branded domain instead of AWS infrastructure details in network requests
- Better developer experience – Development teams can use memorable, branded endpoints instead of copying and pasting long AWS endpoints across code bases and configurations
- Simplified maintenance – Custom domains make it straightforward to manage endpoints when deploying multiple agents or updating configurations across environments
Solution overview
In this solution, we use CloudFront as a reverse proxy to transform requests from your custom domain into Amazon Bedrock AgentCore Runtime API calls. Instead of using the default endpoint, your applications can make requests to a user-friendly URL like https://agent.yourcompany.com/.
The following diagram illustrates the solution architecture.
The workflow consists of the following steps:
- A client application authenticates with Amazon Cognito and receives a bearer token.
- The client makes an HTTPS request to your custom domain.
- Route 53 resolves the DNS request to CloudFront.
- CloudFront forwards the authenticated request to the Amazon Bedrock Runtime agent.
- The agent processes the request and returns the response through the same path.
You can use the same CloudFront distribution to serve both your frontend application and backend agent endpoints, avoiding cross-origin resource sharing (CORS) issues because everything originates from the same domain.
Prerequisites
To follow this walkthrough, you must have the following in place:
Although Amazon Bedrock AgentCore Runtime can be in other supported AWS Regions, CloudFront requires SSL certificates to be in the us-east-1 Region.
You can choose from the following domain options:
- Use an existing domain – Add a subdomain like
agent.yourcompany.com
- Register a new domain – Use Route 53 to register a domain if you don’t have one
- Use the default URL from CloudFront – No domain registration or configuration required
Choose the third option if you want to test the solution quickly before setting up a custom domain.
Create an agent with inbound authentication
If you already have an agent deployed with OAuth authentication, you can skip to the next section to set up the custom domain. Otherwise, follow these steps to create a new agent using Amazon Cognito as your OAuth provider:
- Create a new directory for your agent with the following structure:
your_project_directory/
├── agent_example.py # Your main agent code
├── requirements.txt # Dependencies for your agent
└── __init__.py # Makes the directory a Python package
- Create the main agent code in
agent_example.py:
# agent_example.py
from strands import Agent
from bedrock_agentcore.runtime import BedrockAgentCoreApp
agent = Agent()
app = BedrockAgentCoreApp()
@app.entrypoint
def invoke(payload):
"""Process user input and return a response"""
user_message = payload.get("prompt", "Hello")
response = agent(user_message)
return str(response) # response should be json serializable
if __name__ == "__main__":
app.run()
- Add dependencies to
requirements.txt:
# requirements.txt
strands-agents
bedrock-agentcore
- Run the following commands to create an Amazon Cognito user pool and test user:
# Create User Pool and capture Pool ID
export POOL_ID=$(aws cognito-idp create-user-pool \
--pool-name "MyUserPool" \
--policies '{"PasswordPolicy":{"MinimumLength":8}}' \
--region us-east-1 | jq -r '.UserPool.Id')
# Create App Client and capture Client ID
export CLIENT_ID=$(aws cognito-idp create-user-pool-client \
--user-pool-id $POOL_ID \
--client-name "MyClient" \
--no-generate-secret \
--explicit-auth-flows "ALLOW_USER_PASSWORD_AUTH" "ALLOW_REFRESH_TOKEN_AUTH" \
--region us-east-1 | jq -r '.UserPoolClient.ClientId')
# Create and configure a test user
aws cognito-idp admin-create-user \
--user-pool-id $POOL_ID \
--username "testuser" \
--temporary-password "Temp1234" \
--region us-east-1 \
--message-action SUPPRESS
aws cognito-idp admin-set-user-password \
--user-pool-id $POOL_ID \
--username "testuser" \
--password "MyPassword123" \
--region us-east-1 \
--permanent
echo "Pool ID: $POOL_ID"
echo "Discovery URL: https://cognito-idp.us-east-1.amazonaws.com/$POOL_ID/.well-known/openid-configuration"
echo "Client ID: $CLIENT_ID"
- Deploy the agent using the Amazon Bedrock AgentCore command line interface (CLI) provided by the starter toolkit:
pip install bedrock-agentcore-starter-toolkit #install the starter toolkit
agentcore configure --entrypoint agent_example.py \
--name my_agent \
--execution-role your-execution-role-arn \
--requirements-file requirements.txt \
--authorizer-config "{\"customJWTAuthorizer\":{\"discoveryUrl\":\"https://cognito-idp.us-east-1.amazonaws.com/$POOL_ID/.well-known/openid-configuration\",\"allowedClients\":[\"$CLIENT_ID\"]}}"
agentcore launch
Make note of your agent runtime Amazon Resource Name (ARN) after deployment. You will need this for the custom domain configuration.
For additional examples and details, see Authenticate and authorize with Inbound Auth and Outbound Auth.
Set up the custom domain solution
Now let’s implement the custom domain solution using the AWS CDK. This section shows you how to create the CloudFront distribution that proxies your custom domain requests to Amazon Bedrock AgentCore Runtime endpoints.
- Create a new directory and initialize an AWS CDK project:
mkdir agentcore-custom-domain
cd agentcore-custom-domain
cdk init app --language python
source .venv/bin/activate
pip install aws-cdk-lib constructs
- Encode the agent ARN and prepare the CloudFront origin configuration:
# agentcore_custom_domain_stack.py
import urllib.parse
agent_runtime_arn = "arn:aws:bedrock-agentcore:us-east-1:accountId:runtime/my_agent-xbcDkz4FR9"
encoded_arn = urllib.parse.quote(agent_runtime_arn, safe="") # URL-encode the ARN
region = agent_runtime_arn.split(':')[3] # Extract region from ARN
If your frontend application runs on a different domain than your agent endpoint, you must configure CORS headers. This is common if your frontend is hosted on a different domain (for example, https://app.yourcompany.com calling https://agent.yourcompany.com), or if you’re developing locally (for example, http://localhost:3000 calling your production agent endpoint).
- To handle CORS requirements, create a CloudFront response headers policy:
# agentcore_custom_domain_stack.py
from aws_cdk.aws_cloudfront import ResponseHeadersPolicy, ResponseHeadersCorsBehavior
# Create CORS response headers policy
cors_policy = ResponseHeadersPolicy(self, 'CorsPolicy',
cors_behavior=ResponseHeadersCorsBehavior(
access_control_allow_origins=['*'], # Or specify your frontend domains
access_control_allow_headers=[
'Authorization',
'Content-Type',
'X-Amzn-*',
'X-Requested-With'
],
access_control_allow_methods=['GET', 'POST', 'OPTIONS'],
access_control_allow_credentials=False,
access_control_expose_headers=['*'],
origin_override=True # Overrides CORS headers from origin
)
)
- Create a CloudFront distribution to act as a reverse proxy for your agent endpoints:
# agentcore_custom_domain_stack.py
from aws_cdk.aws_cloudfront import (
Distribution, BehaviorOptions, CachePolicy,
AllowedMethods, ViewerProtocolPolicy,
OriginProtocolPolicy, OriginRequestPolicy
)
from aws_cdk.aws_cloudfront_origins import HttpOrigin
bedrock_agentcore_hostname = f"bedrock-agentcore.{region}.amazonaws.com"
origin_path = f"/runtimes/{encoded_arn}/invocations"
distribution = Distribution(self, 'Distribution',
default_behavior=BehaviorOptions(
origin=HttpOrigin(
bedrock_agentcore_hostname,
origin_path=origin_path,
protocol_policy=OriginProtocolPolicy.HTTPS_ONLY,
read_timeout=Duration.seconds(120) # Optional: for responses >30s, adjust as needed
),
viewer_protocol_policy=ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
cache_policy=CachePolicy.CACHING_DISABLED, # Critical for dynamic APIs
allowed_methods=AllowedMethods.ALLOW_ALL,
response_headers_policy=cors_policy, # Add CORS policy if created
origin_request_policy=OriginRequestPolicy.ALL_VIEWER, # Forward headers for MCP
),
# Add domain configuration if using custom domains
domain_names=[domain_name] if domain_name else None,
certificate=certificate if domain_name else None,
)
Set cache_policy=CachePolicy.CACHING_DISABLED to make sure your agent responses remain dynamic and aren’t cached by CloudFront.
- If you’re using a custom domain, add an SSL certificate and DNS configuration to your stack:
# agentcore_custom_domain_stack.py
from aws_cdk.aws_certificatemanager import Certificate, CertificateValidation
from aws_cdk.aws_route53 import HostedZone, ARecord, RecordTarget
from aws_cdk.aws_route53_targets import CloudFrontTarget
# For existing domains
hosted_zone = HostedZone.from_lookup(self, 'HostedZone',
domain_name="yourcompany.com"
)
# SSL certificate with automatic DNS validation
certificate = Certificate(self, 'Certificate',
domain_name="my-agent.yourcompany.com",
validation=CertificateValidation.from_dns(hosted_zone),
)
# DNS record pointing to CloudFront
ARecord(self, 'AliasRecord',
zone=hosted_zone,
record_name="my-agent.yourcompany.com",
target=RecordTarget.from_alias(CloudFrontTarget(distribution)),
)
The following code is the complete AWS CDK stack that combines all the components:
# agentcore_custom_domain_stack.py
import urllib.parse
from aws_cdk import Stack, CfnOutput, Duration
from aws_cdk.aws_cloudfront import (
Distribution, BehaviorOptions,
CachePolicy, AllowedMethods,
ViewerProtocolPolicy, OriginProtocolPolicy,
ResponseHeadersPolicy, ResponseHeadersCorsBehavior,
OriginRequestPolicy
)
from aws_cdk.aws_cloudfront_origins import HttpOrigin
from aws_cdk.aws_certificatemanager import Certificate, CertificateValidation
from aws_cdk.aws_route53 import HostedZone, ARecord, RecordTarget
from aws_cdk.aws_route53_targets import CloudFrontTarget
from constructs import Construct
class AgentcoreCustomDomainStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Configuration - Update these for your setup
agent_runtime_arn = "arn:aws:bedrock-agentcore:us-east-1:accountId:runtime/my_agent-xbcDkz4FR9"
region = agent_runtime_arn.split(':')[3] # Extract region from ARN
domain_name = "agent.yourcompany.com" # Using your hosted zone
hosted_zone_id = "Z1234567890ABC" # Your hosted zone ID
enable_cors = True # Set to False if serving frontend and backend from same domain
# Encode the agent ARN for the origin path
encoded_arn = urllib.parse.quote(agent_runtime_arn, safe="")
bedrock_agentcore_hostname = f"bedrock-agentcore.{region}.amazonaws.com"
origin_path = f"/runtimes/{encoded_arn}/invocations"
# Create CORS response headers policy if needed
cors_policy = None
if enable_cors:
cors_policy = ResponseHeadersPolicy(self, 'CorsPolicy',
cors_behavior=ResponseHeadersCorsBehavior(
access_control_allow_origins=['*'], # Or specify your frontend domains
access_control_allow_headers=[
'Authorization',
'Content-Type',
'X-Amzn-*',
'X-Requested-With'
],
access_control_allow_methods=['GET', 'POST', 'OPTIONS'],
access_control_expose_headers=['*'],
access_control_allow_credentials=False,
origin_override=True # Overrides CORS headers from origin
)
)
# Base distribution configuration
distribution_props = {
"default_behavior": BehaviorOptions(
origin=HttpOrigin(
bedrock_agentcore_hostname,
origin_path=origin_path, # Direct path to agent endpoint
protocol_policy=OriginProtocolPolicy.HTTPS_ONLY,
read_timeout=Duration.seconds(120) # Optional: for responses >30s, adjust as needed
),
viewer_protocol_policy=ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
cache_policy=CachePolicy.CACHING_DISABLED,
allowed_methods=AllowedMethods.ALLOW_ALL,
response_headers_policy=cors_policy, # Add CORS policy if enabled
origin_request_policy=OriginRequestPolicy.ALL_VIEWER, # Forward headers for MCP
)
}
# Optional: Add custom domain
if domain_name:
# Use from_hosted_zone_attributes for specific zone
hosted_zone = HostedZone.from_hosted_zone_attributes(self, 'HostedZone',
zone_name="yourcompany.com", # Your root domain
hosted_zone_id=hosted_zone_id
)
certificate = Certificate(self, 'Certificate',
domain_name=domain_name,
validation=CertificateValidation.from_dns(
hosted_zone),
)
# Add custom domain to distribution
distribution_props["domain_names"] = [domain_name]
distribution_props["certificate"] = certificate
distribution = Distribution(self, 'Distribution', **distribution_props)
# Create DNS record if using custom domain
if domain_name:
ARecord(self, 'AliasRecord',
zone=hosted_zone,
record_name=domain_name,
target=RecordTarget.from_alias(
CloudFrontTarget(distribution)),
)
# Outputs
if domain_name:
domain_url = f"https://{domain_name}/"
CfnOutput(self, "AgentEndpoint",
value=domain_url,
description="Your custom domain endpoint"
)
CfnOutput(self, "CloudFrontDistribution",
value=f"https://{distribution.distribution_domain_name}/",
description="CloudFront default domain (works without custom domain)"
)
- Configure the AWS CDK
app entry point:
# app.py
#!/usr/bin/env python3
import aws_cdk as cdk
from agentcore_custom_domain.agentcore_custom_domain_stack import AgentCoreCustomDomainStack
app = cdk.App()
AgentcoreCustomDomainStack(app, "AgentCoreCustomDomainStack",
# CloudFront requires certificates in us-east-1
env=cdk.Environment(region='us-east-1'),
)
app.synth()
Deploy your custom domain
Now you can deploy the solution and verify it works with both custom and default domains. Complete the following steps:
- Update the following values in
agentcore_custom_domain_stack.py:
- Your Amazon Bedrock AgentCore Runtime ARN
- Your domain name (if using a custom domain)
- Your hosted zone ID (if using a custom domain)
- Deploy using the AWS CDK:
Test your endpoint
After you deploy the custom domain, you can test your endpoints using either the custom domain or the CloudFront default domain.First, get a JWT token from Amazon Cognito:
export TOKEN=$(aws cognito-idp initiate-auth \
--client-id "your-client-id" \
--auth-flow USER_PASSWORD_AUTH \
--auth-parameters USERNAME='testuser',PASSWORD='MyPassword123' \
--region us-east-1 | jq -r '.AuthenticationResult.AccessToken')
Use the following code to test with your custom domain:
curl -X POST "https://my-agent.yourcompany.com/" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: session-12345678901234567890123456789012345" \
-d '{"prompt": "Hello, how can you help me today?"}'
Alternatively, use the following code to test with the CloudFront default domain:
curl -X POST "https://d1234567890123.cloudfront.net/" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: session-12345678901234567890123456789012345" \
-d '{"prompt": "Hello, how can you help me today?"}'
If everything works correctly, you will receive a response from your agent through either endpoint. You’ve successfully created a custom domain for your Amazon Bedrock AgentCore Runtime agent!
Considerations
As you implement this solution in production, the following are some important considerations:
- Cost implications – CloudFront adds costs for data transfer and requests. Review Amazon CloudFront pricing to understand the impact for your usage patterns.
- Security enhancements – Consider implementing the following security measures:
- AWS WAF rules to help protect against common web exploits.
- Rate limiting to help prevent abuse.
- Geo-restrictions if your agent should only be accessible from specific Regions.
- Monitoring – Enable CloudFront access logs and set up Amazon CloudWatch alarms to monitor error rates, latency, and request volume.
Clean up
To avoid ongoing costs, delete the resources when you no longer need them:
You might need to manually delete the Route 53 hosted zones and ACM certificates from their respective service consoles.
Conclusion
In this post, we showed you how to create custom domain names for your Amazon Bedrock AgentCore Runtime agent endpoints using CloudFront as a reverse proxy. This solution provides several key benefits: simplified integration for development teams, custom domains that align with your organization, cleaner infrastructure abstraction, and straightforward maintenance when endpoints need updates. By using CloudFront as a reverse proxy, you can also serve both your frontend application and backend agent endpoints from the same domain, avoiding common CORS challenges.
We encourage you to explore this solution further by adapting it to your specific needs. You might want to enhance it with additional security features, set up monitoring, or integrate it with your existing infrastructure.
To learn more about building and deploying AI agents, see the Amazon Bedrock AgentCore Developer Guide. For advanced configurations and best practices with CloudFront, refer to the Amazon CloudFront documentation. You can find detailed information about SSL certificates in the AWS Certificate Manager documentation, and domain management in the Amazon Route 53 documentation.
Amazon Bedrock AgentCore is currently in preview and subject to change. Standard AWS pricing applies to additional services used, such as CloudFront, Route 53, and Certificate Manager.
About the authors
Rahmat Fedayizada is a Senior Solutions Architect with the AWS Energy and Utilities team. He works with energy companies to design and implement scalable, secure, and highly available architectures. Rahmat is passionate about translating complex technical requirements into practical solutions that drive business value.
Paras Bhuva is a Senior Manager of Solutions Architecture at AWS, where he leads a team of solution architects helping energy customers innovate and accelerate their transformation. Having started as a Solution Architect in 2012, Paras is passionate about architecting scalable solutions and building organizations focused on application modernization and AI initiatives.
