Configure los nombres de dominio personalizados para los agentes de tiempo de ejecución de Amazon Bedrock

Al implementar Agentes de IA a Amazon Bedrock Agentcore Runtime (Actualmente en panorama previa), los clientes a menudo desean usar nombres de dominio personalizados para crear una experiencia profesional y perfecta.

Por defecto, los agentes de tiempo de ejecución de AgentCore usan puntos finales como https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{EncodedAgentARN}/invocations.

En esta publicación, discutimos cómo transfigurar estos puntos finales en dominios personalizados fáciles de usar (como https://agent.yourcompany.com) usando Amazon Cloudfront como un proxy inverso. La decisión combina Cloudfront, Ruta de Amazon 53y Administrador de certificados de AWS (ACM) para crear una configuración de dominio personalizada segura y escalable que funcione sin problemas con sus agentes existentes.

Beneficios del tiempo de ejecución de Amazon Bedrock Agentcore

Si está construyendo agentes de IA, probablemente haya luchado con los desafíos de alojamiento: encargar la infraestructura, el manejo de la autenticación, la escalera y el mantenimiento de la seguridad. El tiempo de ejecución de Amazon Bedrock Agentcore ayuda a invadir estos problemas.

Amazon Bedrock AgentCore Runtime es entorno descreído; puedes usarlo con Langgraph, Crewai, Agentes de hiloso agentes personalizados que ha construido desde cero. Admite tiempos de ejecución extendidos hasta 8 horasconsumado para tareas de razonamiento complejas que las funciones tradicionales sin servidor no pueden manejar. Cada sesión de heredero se ejecuta en su propia microvm aislada, proporcionando seguridad que es crucial para las aplicaciones empresariales.

El maniquí de precios basado en el consumo significa que solo paga por lo que usa, no por lo que provoca. Y a diferencia de otras soluciones de alojamiento, el tiempo de ejecución de Amazon Bedrock Agentcore incluye autenticación incorporada y observabilidad especializada para agentes de IA fuera de la caja.

Beneficios de los dominios personalizados

Cuando se usa Amazon Bedrock AgentCore Runtime con Autorización abierta (OAuth) Autenticación, sus aplicaciones realizan solicitudes HTTPS directas al punto final del servicio. Aunque esto funciona, los dominios personalizados ofrecen varios beneficios:

Marca personalizada -Aplicaciones del flanco del cliente (navegadores web, aplicaciones móviles) muestran su dominio de marca en circunstancia de detalles de infraestructura de AWS en solicitudes de red
Mejor experiencia de desarrollador – Los equipos de expansión pueden usar puntos finales memorables y de marca en circunstancia de copiar y pegar puntos finales de largos AWS a través de las bases y configuraciones de código
Mantenimiento simplificado – Los dominios personalizados hacen que sea sencillo gobernar puntos finales al implementar múltiples agentes o desempolvar configuraciones en todos los entornos

Descripción militar de la decisión

En esta decisión, utilizamos CloudFront como un proxy inverso para transfigurar las solicitudes de su dominio personalizado en las llamadas de API de tiempo de ejecución de Amazon Bedrock AgentCore. En circunstancia de usar el punto final predeterminado, sus aplicaciones pueden hacer solicitudes a una URL claro de usar como https://agent.yourcompany.com/.

El venidero diagrama ilustra la inmueble de la decisión.

El flujo de trabajo consta de los siguientes pasos:

Una aplicación de cliente se autentica con Amazon Cognito y recibe un token de portador.
El cliente realiza una solicitud HTTPS a su dominio personalizado.
La ruta 53 resuelve la solicitud DNS a CloudFront.
CloudFront reenvía la solicitud autenticada al agente de tiempo de ejecución de Amazon Bedrock.
El agente procesa la solicitud y devuelve la respuesta a través de la misma ruta.

Puede usar la misma distribución de CloudFront para servir tanto a su aplicación frontend como a los puntos finales del agente de backend, evitando Compartir fortuna de origen cruzado (CORS) problemas porque todo se origina en el mismo dominio.

Requisitos previos

Para seguir este tutorial, debe tener lo venidero en su circunstancia:

Aunque el tiempo de ejecución de Amazon Bedrock Agentcore puede estar en otro Regiones AWS apoyadasCloudFront requiere que los certificados SSL estén en el us-east-1 Región.

Puede designar entre las siguientes opciones de dominio:

Use un dominio existente – Agregue un subdominio como agent.yourcompany.com
Registre un nuevo dominio – Use la ruta 53 para registrar un dominio si no tiene uno
Use la URL predeterminada desde CloudFront – No se requiere registro o configuración de dominio

Elija la tercera opción si desea probar la decisión rápidamente ayer de configurar un dominio personalizado.

Crear un agente con autenticación entrante

Si ya tiene un agente implementado con la autenticación OAuth, puede silenciar a la venidero sección para configurar el dominio personalizado. De lo contrario, siga estos pasos para crear un nuevo agente usando Amazon Cognito como su proveedor de OAuth:

Cree un nuevo directorio para su agente con la venidero estructura:

your_project_directory/
├── agent_example.py # Your main agent code
├── requirements.txt # Dependencies for your agent
└── __init__.py # Makes the directory a Python package

Crear el código del agente principal en 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()

Juntar dependencias a requirements.txt:

# requirements.txt
strands-agents
bedrock-agentcore

Ejecute los siguientes comandos para crear un heredero de heredero de Amazon Cognito y probar el heredero:

# 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"

Implemente el agente utilizando la interfaz de renglón de comandos de bedrock de Amazon (CLI) proporcionada por el kit de herramientas de inicio:

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

Tome nota de su agente Nombre de fortuna de Amazon (ARN) de su agente luego de la implementación. Necesitará esto para la configuración de dominio personalizado.

Para ejemplos y detalles adicionales, ver Autenticar y autorizar con autenticación entrante y autora de salida.

Configurar la decisión de dominio personalizado

Ahora implementemos la decisión de dominio personalizado utilizando el AWS CDK. Esta sección le muestra cómo crear la distribución de CloudFront que proxen sus solicitudes de dominio personalizadas a los puntos finales de tiempo de ejecución de Amazon Bedrock Agentcore.

Cree un nuevo directorio e inicialice un tesina AWS CDK:

mkdir agentcore-custom-domain
cd agentcore-custom-domain
cdk init app --language python
source .venv/bin/activate
pip install aws-cdk-lib constructs

Codifique el agente ARN y prepare la configuración de origen de CloudFront:

# 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

Si su aplicación frontend se ejecuta en un dominio diferente al punto final de su agente, debe configurar los encabezados CORS. Esto es global si su frontend está alojado en un dominio diferente (por ejemplo, https://app.yourcompany.com gusto https://agent.yourcompany.com), o si se está desarrollando localmente (por ejemplo, http://localhost:3000 Golpear al punto final de su agente de producción).

Para manejar los requisitos de CORS, cree una Cloudfront Política de encabezados de respuesta:

# 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
    )
)

Cree una distribución de CloudFront para efectuar como un proxy inverso para los puntos finales de su agente:

# 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,
)

Colocar cache_policy=CachePolicy.CACHING_DISABLED Para comprobar de que las respuestas de su agente permanezcan dinámicas y no se almacenen en personalidad por CloudFront.

Si está utilizando un dominio personalizado, agregue un certificado SSL y una configuración DNS a su pila:

# 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)),
)

El venidero código es la pila completa de AWS CDK que combina todos los componentes:

# 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
                )
            )

        # Saco 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)"
                  )

Configurar el AWS CDK app punto de entrada:

# 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()

Implementar su dominio personalizado

Ahora puede implementar la decisión y realizar que funciona con dominios personalizados y predeterminados. Complete los siguientes pasos:

Renovar los siguientes títulos en agentcore_custom_domain_stack.py:
- Su Amazon Bedrock Agentcore Runtime Arn
- Su nombre de dominio (si usa un dominio personalizado)
- Su ID de zona alojada (si usa un dominio personalizado)
Implementar usando el AWS CDK:

Pon a prueba tu punto final

A posteriori de implementar el dominio personalizado, puede probar sus puntos finales utilizando el dominio personalizado o el dominio predeterminado de CloudFront.

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 el venidero código para probar con su dominio personalizado:

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?"}'

Alternativamente, use el venidero código para probar con el dominio predeterminado de CloudFront:

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?"}'

Si todo funciona correctamente, recibirá una respuesta de su agente a través de cualquier punto final. ¡Ha creado con éxito un dominio personalizado para su agente de ejecución de Amazon Bedrock Agentcore!

Consideraciones

A medida que implementa esta decisión en la producción, las siguientes son algunas consideraciones importantes:

Implicaciones de costos – CloudFront agrega costos para la transferencia de datos y las solicitudes. Revisar Precios de Amazon Cloudfront Para comprender el impacto de sus patrones de uso.
Mejoras de seguridad – Considere implementar las siguientes medidas de seguridad:
- AWS WAF Reglas para ayudar a proteger contra las exploits web comunes.
- Restricción de tasas para ayudar a alertar el despotismo.
- Geo-Restricciones Si su agente solo debe ser accesible desde regiones específicas.
Audición – Habilitar CloudFront registros de ataque y configurar Amazon CloudWatch alarmas para monitorear las tasas de error, la latencia y el convexidad de solicitud.

Alejar

Para evitar costos continuos, elimine los fortuna cuando ya no los necesite:

Es posible que deba eliminar manualmente las zonas alojadas de la Ruta 53 y los certificados ACM de sus respectivas consolas de servicio.

Conclusión

En esta publicación, le mostramos cómo crear nombres de dominio personalizados para su agente de ejecución de Amazon Bedrock Agent de agente de ejecución utilizando CloudFront como un proxy inverso. Esta decisión proporciona varios beneficios esencia: integración simplificada para equipos de expansión, dominios personalizados que se alinean con su estructura, percepción de infraestructura más limpia y mantenimiento directo cuando los puntos finales necesitan actualizaciones. Al usar CloudFront como un proxy inverso, además puede servir tanto en los puntos finales de la aplicación frontend y el agente de backend del mismo dominio, evitando los desafíos comunes de CORS.

Le recomendamos que explore esta decisión aún más adaptándola a sus micción específicas. Es posible que desee mejorarlo con características de seguridad adicionales, configurar el monitoreo o integrarlo con su infraestructura existente.

Para obtener más información sobre la construcción y la implementación de agentes de IA, vea el Lazarillo de desarrolladores de Amazon Bedrock Agentcore. Para configuraciones avanzadas y mejores prácticas con CloudFront, consulte el Documentación de Amazon Cloudfront. Puede encontrar información detallada sobre los certificados SSL en el Documentación del administrador de certificados de AWSy gobierno del dominio en el Documentación de Amazon Route 53.

Amazon Bedrock AgentCore está actualmente en panorama previa y está sujeto a cambios. El precio habitual de AWS se aplica a los servicios adicionales utilizados, como CloudFront, Route 53 y Certificate Manager.

Sobre los autores

Rahmat Fedayizada es un arquitecto de soluciones senior con el equipo de AWS Energy and Utilities. Trabaja con compañías de energía para diseñar e implementar arquitecturas escalables, seguras y en extremo disponibles. Rahmat es un apasionado de traducir requisitos técnicos complejos en soluciones prácticas que generen el valía comercial.

Paras bhuva es directivo senior de inmueble de soluciones en AWS, donde lidera un equipo de arquitectos de soluciones que ayudan a los clientes de energía a innovar y acelerar su transformación. Habiendo comenzado como arquitecto de soluciones en 2012, Paras es un apasionado de inmueble de soluciones escalables y organizaciones de construcción centradas en la modernización de aplicaciones e iniciativas de IA.

Etiquetado agentes, Amazon, Bedrock, Configure, dominio, ejecución, los, nombres, para, personalizados, tiempo