Python Agent

Genera un agente de IA en Python para construir agentes con herramientas, y opcionalmente despliégalo en Amazon Bedrock AgentCore Runtime. Elige el framework del agente con la opción framework: Strands (el predeterminado) o LangChain (construido sobre LangGraph).

El generador expone tu agente a través de un protocol de servidor. Ambos frameworks soportan HTTP (el predeterminado), el protocolo Agent-to-Agent (A2A) para interoperabilidad con otros agentes compatibles con A2A, y el protocolo AG-UI para integración directa con frontend a través de CopilotKit.

Uso

Generar un Agente

Puedes generar un Python Agent de dos maneras:

CLI
VSCode

pnpm nx g @aws/nx-plugin:py#agent

yarn nx g @aws/nx-plugin:py#agent

npx nx g @aws/nx-plugin:py#agent

bunx nx g @aws/nx-plugin:py#agent

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm nx g @aws/nx-plugin:py#agent --dry-run

yarn nx g @aws/nx-plugin:py#agent --dry-run

npx nx g @aws/nx-plugin:py#agent --dry-run

bunx nx g @aws/nx-plugin:py#agent --dry-run

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - py#agent
Complete los parámetros requeridos
Haga clic en Generate

Opciones

Parámetro	Tipo	Predeterminado	Descripción
project Requerido	string	-	El proyecto al que agregar el Agent
framework	strands \| langchain	strands	El SDK del agente a utilizar.
name	string	-	El nombre de tu Agent (predeterminado: agent)
auth	iam \| cognito	iam	El método utilizado para autenticar con tu Agent. Solo aplicable cuando infra está configurado (se ignora cuando infra es none).
protocol	http \| a2a \| ag-ui	http	El protocolo del servidor para tu Agent. HTTP expone un servidor HTTP FastAPI. A2A expone un servidor de protocolo Agent-to-Agent. AG-UI expone un servidor de protocolo Agent-User Interaction para integración directa con el frontend.
iac	inherit \| cdk \| terraform	inherit	El proveedor de IaC preferido. Por defecto, se hereda de tu selección inicial.
infra	agentcore \| none	agentcore	El tipo de infraestructura para alojar tu Agent.
session	s3 \| dynamodb-s3 \| in-memory	s3	El almacenamiento utilizado para persistir la sesión de tu Agent. LangChain admite 's3' o 'dynamodb-s3'; Strands admite 's3'; 'in-memory' es válido para ambos.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establece en false para diferir la instalación cuando se ejecutan múltiples generadores en lote (la instalación aún se ejecuta si es necesaria para que los generadores subsecuentes puedan calcular el grafo de proyectos de Nx); instala una vez al final.

Salida del Generador

El generador agregará los siguientes archivos a tu proyecto Python existente. Los archivos generados dependen del protocol elegido:

Protocolo HTTP (predeterminado)

Directorioyour-project/
- Directorioyour_module/
  - Directorioagent/ (or custom name if specified)
    __init__.py Python package initialization
    init.py FastAPI application setup with CORS and error handling middleware
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    main.py FastAPI entry point for Bedrock AgentCore Runtime
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- pyproject.toml Updated with Strands dependencies
- project.json Updated with agent serve targets

Protocolo A2A

El punto de entrada expone tu agente a través del protocolo A2A (Strands usa el Strands A2A Server; LangChain envuelve el grafo en un ejecutor a2a-sdk), montado en una aplicación FastAPI:

Directorioyour-project/
- Directorioyour_module/
  - Directorioagent/ (or custom name if specified)
    __init__.py Python package initialization
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    main.py A2A server entry point
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- pyproject.toml Updated with framework and A2A dependencies
- project.json Updated with agent serve targets

Protocolo AG-UI

El punto de entrada expone tu agente a través del protocolo AG-UI para integración directa con frontend con CopilotKit. Los agentes Strands usan la integración ag-ui-strands; los agentes LangChain usan ag-ui-langgraph:

Directorioyour-project/
- Directorioyour_module/
  - Directorioagent/ (or custom name if specified)
    __init__.py Python package initialization
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    main.py AG-UI server entry point
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- pyproject.toml Updated with framework and AG-UI dependencies
- project.json Updated with agent serve targets

Infraestructura

Dado que este generador proporciona infraestructura como código basada en tu iac elegido, creará un proyecto en packages/common que incluye las construcciones CDK o módulos Terraform relevantes.

El proyecto común de infraestructura como código está estructurado de la siguiente manera:

CDK
Terraform

Directoriopackages/common/constructs
- Directoriosrc
  - Directorioapp/ Constructs for infrastructure specific to a project/generator
    …
  - Directoriocore/ Generic constructs which are reused by constructs in app
    …
  - index.ts Entry point exporting constructs from app
- project.json Project build targets and configuration

Directoriopackages/common/terraform
- Directoriosrc
  - Directorioapp/ Terraform modules for infrastructure specific to a project/generator
    …
  - Directoriocore/ Generic modules which are reused by modules in app
    …
- project.json Project build targets and configuration

Para desplegar tu Agente, se generan los siguientes archivos:

CDK
Terraform

Directoriopackages/common/constructs/src
- Directorioapp
  - Directorioagents
    Directorio<project-name>
    <project-name>.ts CDK construct for deploying your agent

Si seleccionaste none para infra, no se generan constructos CDK ni módulos Terraform — el Agente solo puede ejecutarse localmente. La opción auth se ignora en este modo ya que no hay un endpoint alojado para autenticar.

Cuando se despliega en Bedrock AgentCore Runtime, el agente se construye en una imagen de contenedor, se envía a Amazon ECR y se ejecuta en AgentCore Runtime. Los clientes invocan el endpoint del plano de datos de AgentCore Runtime, que reenvía las solicitudes a tu agente. El agente llama a Amazon Bedrock para la inferencia del modelo y puede invocar herramientas, servidores MCP o APIs descendentes.

Con infra: none, no se genera infraestructura de AWS. El agente se ejecuta como un proceso local y llama a Amazon Bedrock para la inferencia del modelo.

Trabajar con tu Agente

Puedes editar agent.py para agregar herramientas, configurar el modelo y personalizar el prompt del sistema. La API depende del framework que elegiste.

Agregar Herramientas

Las herramientas son funciones que el agente de IA puede llamar para realizar acciones. Ambos frameworks usan un enfoque basado en decoradores para definir herramientas, derivan el nombre y descripción de la herramienta del nombre de la función y docstring, y generan el esquema de entrada a partir de tus anotaciones de tipo.

Strands
LangChain

from strands import Agent, tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """Calculate the sum of a list of numbers"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Get weather information for a city"""
    # Your weather API integration here
    return f"Weather in {city}: Sunny, 25°C"

# Add tools to your agent
agent = Agent(
    system_prompt="You are a helpful assistant with access to various tools.",
    tools=[calculate_sum, get_weather],
)

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse
from langchain_core.tools import tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """Calculate the sum of a list of numbers"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Get weather information for a city"""
    # Your weather API integration here
    return f"Weather in {city}: Sunny, 25°C"

# Add tools to your agent
agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[calculate_sum, get_weather],
    system_prompt="You are a helpful assistant with access to various tools.",
)

Usar Herramientas Preconstruidas

Strands
LangChain

Strands proporciona una colección de herramientas preconstruidas a través del paquete strands-tools:

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="You are a helpful assistant.",
    tools=[current_time, http_request, file_read],
)

LangChain proporciona un gran ecosistema de herramientas e integraciones. Instala el paquete de integración relevante, luego pasa las herramientas a create_agent:

from langchain_community.tools import DuckDuckGoSearchRun

agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[DuckDuckGoSearchRun()],
    system_prompt="You are a helpful assistant.",
)

Configuración del Modelo

Strands
LangChain

Por defecto, los agentes Strands usan Claude 4 Sonnet, pero puedes personalizar el proveedor del modelo. Consulta la documentación de Strands sobre proveedores de modelos para opciones de configuración:

from strands import Agent
from strands.models import BedrockModel

# Create a BedrockModel
bedrock_model = BedrockModel(
    model_id="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

agent = Agent(model=bedrock_model)

Los agentes LangChain usan un modelo ChatBedrockConverse. El agente generado lee el id del modelo y la región de las variables de entorno MODEL_ID y AWS_REGION, pero puedes configurar el modelo directamente en agent.py:

from langchain_aws import ChatBedrockConverse

model = ChatBedrockConverse(
    model="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

Consumir Servidores MCP

Para consumir Servidores MCP que hayas creado usando los generadores py#mcp-server o ts#mcp-server puedes hacer uso del generador connection, que conecta las herramientas del servidor MCP a tu agente para ambos frameworks.

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - connection
Complete los parámetros requeridos
Haga clic en Generate

Consulta la guía del generador connection para detalles sobre cómo se configura la conexión.

Para otros servidores MCP, consulta la documentación MCP de Strands o LangChain.

Más

Para una guía más detallada sobre cómo escribir agentes, consulta la documentación de Strands o LangChain.

Protocolo

El protocolo del servidor de tu agente determina cómo se comunica. Todas las opciones son servidas por FastAPI — el punto de entrada difiere:

HTTP (predeterminado): Un servidor FastAPI estándar con un endpoint /invocations personalizado, CORS y streaming. Mejor para integraciones de cliente personalizadas.
A2A: Un servidor Agent-to-Agent montado en una aplicación FastAPI (Strands usa el Strands A2A Server; LangChain usa el a2a-sdk agnóstico del framework). Mejor cuando tu agente necesita ser descubrible e invocable por otros agentes compatibles con A2A.
AG-UI: El protocolo AG-UI sobre SSE (Strands usa ag-ui-strands; LangChain usa ag-ui-langgraph). Mejor para integración directa con frontend con CopilotKit en un sitio web React.

El punto de entrada del servidor difiere según el framework (Strands produce un Agent gestionado por contexto, mientras que LangChain impulsa un grafo create_agent compilado), pero el contrato externo para cada protocolo es el mismo.

Todos los protocolos exponen /ping para el contrato de verificación de salud del runtime AgentCore. Los agentes A2A escuchan en el puerto 9000; los agentes HTTP y AG-UI escuchan en el puerto 8080. El Dockerfile y la infraestructura generados están configurados para ti.

Servidor FastAPI (protocolo HTTP)

El servidor HTTP generado incluye:

Configuración de aplicación FastAPI con middleware CORS
Middleware de manejo de errores
Generación de esquema OpenAPI
Endpoint de verificación de salud (/ping)
Endpoint de invocación del agente (/invocations)

Personalizar Entradas y Salidas de Invocación con Pydantic

El endpoint de invocación del agente usa modelos Pydantic para definir y validar los esquemas de solicitud y respuesta. Puedes personalizar estos modelos en main.py para que coincidan con los requisitos de tu agente.

Definir Modelos de Entrada

El modelo InvokeInput predeterminado acepta un prompt.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    prompt: str

Puedes extender este modelo para incluir cualquier campo adicional que tu agente necesite.

El ID de sesión se extrae del encabezado HTTP x-amzn-bedrock-agentcore-runtime-session-id, consistente con el contrato de sesión de Bedrock AgentCore Runtime. Si el encabezado no se proporciona, se genera un UUID aleatorio como respaldo.

Definir Modelos de Salida

Para respuestas de streaming, el generador proporciona JsonStreamingResponse que serializa automáticamente modelos Pydantic al formato JSON Lines (application/jsonl). Este formato es compatible con la especificación de streaming de OpenAPI 3.2 y funciona sin problemas con el cliente TypeScript generado.

Por defecto, el agente produce objetos StreamChunk que contienen el texto de respuesta del agente:

class StreamChunk(BaseModel):
    content: str

Puedes personalizar el modelo StreamChunk para adaptarlo a tus necesidades:

from pydantic import BaseModel

class StreamChunk(BaseModel):
    content: str
    timestamp: str
    token_count: int

Ten en cuenta que dado que FastAPI actualmente no admite la generación de una especificación OpenAPI para respuestas de streaming, debemos establecer explícitamente el modelo de respuesta para cada operación de streaming, es decir:

@app.post(
    "/invocations",
    response_class=JsonStreamingResponse,
    responses={200: JsonStreamingResponse.openapi_response(StreamChunk)},
)
async def invoke(input: InvokeInput) -> JsonStreamingResponse:
    return JsonStreamingResponse(handle_invoke(input))

Hay una solicitud de función abierta para soporte nativo en FastAPI.

Bedrock AgentCore Python SDK

El generador incluye una dependencia en el Bedrock AgentCore Python SDK para las constantes PingStatus. Si lo deseas, es sencillo usar BedrockAgentCoreApp en lugar de FastAPI, sin embargo, ten en cuenta que se pierde la seguridad de tipos.

Puedes encontrar más detalles sobre las capacidades del SDK en la documentación aquí.

Servidor A2A (protocolo A2A)

El main.py generado monta un servidor A2A en una aplicación FastAPI padre que también expone /ping. Los agentes Strands usan el A2AServer de Strands; los agentes LangChain envuelven el grafo compilado en un AgentExecutor de a2a-sdk. Cuando se despliega en AgentCore, el punto de entrada resuelve el ARN público del runtime desde AppConfig y lo anuncia en la tarjeta del agente.

La mayoría de los usuarios no necesitarán modificar este archivo; edita agent.py para cambiar herramientas o el prompt del sistema. El servidor A2A completa la tarjeta del agente (/.well-known/agent-card.json) a partir del name y description del agente.

Servidor AG-UI (protocolo AG-UI)

El main.py generado expone un único endpoint POST que transmite eventos AG-UI a través de Server-Sent Events (SSE), así como /ping para la verificación de salud del runtime AgentCore. El cableado depende del framework:

Strands: envuelve tu Agent en un ag_ui_strands.StrandsAgent, construido dentro de un manejador lifespan de FastAPI (para que la construcción ocurra al inicio del contenedor/sesión en lugar de en el momento de la importación), y servido desde un bucle /invocations de FastAPI hecho a mano.
LangChain: envuelve el grafo compilado en un ag_ui_langgraph.LangGraphAgent, construido de la misma manera dentro de lifespan, y servido desde un bucle /invocations de FastAPI hecho a mano.

La mayoría de los usuarios no necesitarán modificar este archivo — edita agent.py para cambiar herramientas o el prompt del sistema.

Ejecutar tu Agente

Desarrollo Local

Para ejecutar tu Agente (y todo lo conectado a él) localmente, usa el target dev del proyecto:

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

Si has agregado múltiples componentes a tu proyecto (agentes, servidores MCP, etc.), esto los inicia todos. Para ejecutar solo este agente, apunta a su target <your-agent-name>-dev:

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Esto usa uv run para ejecutar tu Agente usando el Bedrock AgentCore Python SDK.

Chatear con tu Agente

El generador configura un target Nx <your-agent-name>-chat que te lleva a un chat interactivo de terminal con tu agente.

El target de chat se ejecuta de forma independiente. Por defecto se conecta a tu agente ejecutándose localmente, así que primero inicia el target <your-agent-name>-dev del agente (en una terminal separada):

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Luego, en otra terminal, inicia el chat:

pnpm nx run your-project:agent-chat

yarn nx run your-project:agent-chat

npx nx run your-project:agent-chat

bunx nx run your-project:agent-chat

El generador emite un scripts/<your-agent-name>/chat.ts para cada protocolo. Se conecta al agente local por defecto, o a tu agente desplegado cuando se establece RUNTIME_CONFIG_APP_ID (consulta Chatear con tu agente desplegado a continuación).

Para agentes HTTP, el script de chat usa un cliente TypeScript con seguridad de tipos generado a partir de la especificación OpenAPI del agente. El generador también emite:

scripts/<your-agent-name>_openapi.py — un pequeño script que exporta la especificación OpenAPI del agente
Un target Nx <your-agent-name>-openapi que lo ejecuta
Un target Nx <your-agent-name>-generate-client que produce un cliente TypeScript con seguridad de tipos bajo scripts/<your-agent-name>/generated/

Cuando personalices la forma de entrada del agente (por ejemplo, agregar nuevos campos a InvokeInput), actualiza chat.ts para pasar los nuevos campos al invocar el agente y el resto funciona automáticamente.

Chatear con tu agente desplegado

Para chatear con tu agente desplegado en Bedrock AgentCore, establece la variable de entorno RUNTIME_CONFIG_APP_ID al id de aplicación AppConfig del despliegue (salida como RuntimeConfigApplicationId por el stack desplegado). El script de chat resuelve el ARN del runtime de tu agente desde la configuración del runtime y se conecta al endpoint desplegado:

IAM
Cognito

Para agentes autenticados con IAM, las solicitudes se firman con SigV4 usando tus credenciales AWS predeterminadas. Asegúrate de que el entorno tenga credenciales AWS con permiso para invocar el runtime:

RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> bunx nx run your-project:agent-chat

Para agentes autenticados con Cognito, proporciona un token de acceso de Cognito a través de la variable de entorno AGENT_ACCESS_TOKEN, que se envía como un token bearer:

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> bunx nx run your-project:agent-chat

Puedes obtener un token de acceso usando el comando cognito-idp admin-initiate-auth de AWS CLI, por ejemplo:

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

Desplegar tu Agente en Bedrock AgentCore Runtime

Infraestructura como Código

Si seleccionaste agentcore para infra, se genera la infraestructura CDK o Terraform relevante que puedes usar para desplegar tu Agent en Amazon Bedrock AgentCore Runtime.

CDK
Terraform

Se genera un constructo CDK para tu agente, nombrado según el name que elegiste al ejecutar el generador, o <ProjectName>Agent por defecto.

Puedes usar este constructo CDK en una aplicación CDK:

import { MyProjectAgent } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Se genera un módulo Terraform para ti, nombrado según el name que elegiste al ejecutar el generador, o <ProjectName>-agent por defecto.

Pasa las salidas del módulo compartido runtime_config_appconfig al módulo del agente:

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Se requiere Docker para construir y desplegar tu Agent. Asegúrate de haber instalado e iniciado Docker para evitar errores como:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

Autenticación

El generador proporciona una opción auth para configurar la autenticación de tu Agent. Puedes elegir entre autenticación IAM (predeterminada) o Cognito al generar tu agente.

IAM

Por defecto, tu Agent estará protegido usando autenticación IAM, simplemente despliégalo sin ningún argumento:

CDK
Terraform

import { MyProjectAgent } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Puedes otorgar acceso para invocar tu agente en Bedrock AgentCore Runtime usando el método grantInvokeAccess, por ejemplo:

import { MyProjectAgent } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');
    const lambdaFunction = new Function(this, ...);

    agent.grantInvokeAccess(lambdaFunction);
  }
}

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Para otorgar acceso para invocar tu agente, necesitarás agregar una política como la siguiente, haciendo referencia a la salida module.my_project_agent.agent_core_runtime_arn:

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_agent.agent_core_runtime_arn,
    "${module.my_project_agent.agent_core_runtime_arn}/*"
  ]
}

Autenticación Cognito

Cuando seleccionas autenticación Cognito, el generador configura el agente para usar Cognito para la autenticación.

CDK
Terraform

El constructo generado acepta una prop identity que configura la autenticación Cognito:

import { MyProjectAgent, UserIdentity } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

    new MyProjectAgent(this, 'MyProjectAgent', {
      identity,
    });
  }
}

El constructo UserIdentity se puede generar usando el generador ts#website#auth, o puedes crear tu propio UserPool y UserPoolClient de CDK.

El módulo generado acepta las variables user_pool_id y user_pool_client_ids para la autenticación Cognito:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Targets de Bundle y Docker

Para construir tu Agente para Bedrock AgentCore Runtime, se agrega un target bundle a tu proyecto, que:

Exporta tus dependencias de Python a un archivo requirements.txt usando uv export
Instala dependencias para la plataforma objetivo (aarch64-manylinux_2_28) usando uv pip install

También se agrega un target docker específico para tu Agente, que copia el Dockerfile y los artefactos empaquetados en un directorio de contexto docker. Esto coloca el Dockerfile junto con la salida construida, permitiendo que CDK construya la imagen Docker directamente usando AgentRuntimeArtifact.fromAsset.

Escaneo de Imágenes

La imagen Docker construida para este proyecto puede ser escaneada en busca de vulnerabilidades usando Trivy, ejecutándose desde la imagen Trivy alojada en ECR.

Se agrega un target trivy a tu proyecto que escanea la imagen construida y termina con código distinto de cero si se encuentra alguna vulnerabilidad de severidad HIGH o CRITICAL. El Dockerfile generado usa una imagen base sin vulnerabilidades corregibles conocidas de estas severidades al momento de la generación, y actualiza las herramientas incluidas (como npm) para mantenerlo así.

El escaneo usa el mismo motor de contenedores que tu construcción de imagen (docker o finch), por lo que no se requieren herramientas adicionales. Dado que el escaneo solo se vuelve a ejecutar cuando la imagen cambia, una imagen sin cambios no se vuelve a escanear. El script raíz trivy proporcionado escanea cada imagen en el workspace:

pnpm trivy

yarn trivy

npm run trivy

bun trivy

Suprimiendo Hallazgos de Trivy

Puede haber instancias en las que desees suprimir una vulnerabilidad específica, por ejemplo cuando aún no hay una corrección disponible y has evaluado el riesgo como aceptable.

Agrega el ID de vulnerabilidad (uno por línea) al archivo .trivyignore en la raíz de tu proyecto (es decir, junto a tu project.json):

# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

Para más detalles sobre el filtrado de hallazgos, consulta la documentación de filtrado de Trivy.

Observabilidad

Tu agente se configura automáticamente con observabilidad usando AWS Distro for Open Telemetry (ADOT), configurando la auto-instrumentación en tu Dockerfile.

Puedes encontrar trazas en la Consola AWS de CloudWatch, seleccionando “GenAI Observability” en el menú. Ten en cuenta que para que las trazas se completen necesitarás habilitar Transaction Search.

Para más detalles, consulta la documentación de AgentCore sobre observabilidad.

Gestión de Sesiones

La opción session se mapea a un concepto de persistencia subyacente diferente dependiendo del framework elegido: el concepto de gestión de sesiones de Strands para el framework strands, o el concepto de checkpointer de LangGraph para el framework langchain.

La opción session controla cómo tu agente persiste el estado de la conversación (historial de mensajes, estado de herramientas, etc.) entre invocaciones, usando el SessionManager del SDK de Strands:

s3 (predeterminado): La infraestructura CDK/Terraform aprovisiona un bucket S3 dedicado para datos de sesión, cifrado con una clave KMS dedicada y con todo el acceso público bloqueado; los registros de acceso al servidor se entregan a un grupo de registros de CloudWatch Logs a través de la misma clave. El rol IAM del agente recibe acceso de lectura/escritura/lista/eliminación al bucket y acceso de descifrado/generación-de-clave-de-datos a la clave, y el nombre del bucket se registra junto con el ARN del agente en la configuración del runtime de AppConfig.
in-memory: No se aprovisiona ningún bucket. El estado de la conversación se mantiene en memoria solo durante la vida útil del proceso en ejecución y no sobrevive a reinicios o reducciones de escala.

Esto se implementa en el session.py generado, que exporta una función get_session_manager() que resuelve un SessionManager para la sesión actual.

El ID de sesión en sí proviene de la sesión de AgentCore Runtime (propagada a través del encabezado x-amzn-bedrock-agentcore-runtime-session-id) y está vinculado a un contexto basado en contextvars.ContextVar para que get_current_session_id() pueda resolverlo en cualquier lugar de la solicitud — incluyendo en cualquier cliente MCP o A2A descendente conectado a través del generador connection, por lo que toda la cadena de llamadas comparte una sesión consistente.

La opción session controla cómo el checkpointer de LangGraph de tu agente persiste el estado de la conversación:

s3 (predeterminado): El agente desplegado usa un S3CheckpointSaver con el bucket de sesión aprovisionado, almacenando checkpoints y escrituras pendientes bajo el prefijo checkpoints/. Esta clase vive en s3_checkpoint_saver_langchain.py en el proyecto compartido de conexión de agentes.
dynamodb-s3: La infraestructura CDK/Terraform aprovisiona una tabla DynamoDB para checkpoints, configurada como se recomienda en la documentación de AWS sobre el uso de DynamoDB como almacén de checkpoints para agentes LangGraph (esquema unificado PK/SK, facturación PAY_PER_REQUEST, recuperación point-in-time, y un atributo ttl), más un bucket S3 para descargar checkpoints de más de 350KB. Ambos están cifrados con una clave KMS dedicada; los registros de acceso al servidor del bucket se entregan a un grupo de registros de CloudWatch Logs a través de la misma clave. El rol IAM del agente recibe acceso de lectura/escritura a la tabla y al bucket, y los nombres de la tabla/bucket se registran junto con el ARN del agente en la configuración del runtime de AppConfig.
in-memory: No se aprovisiona ninguna tabla ni bucket. El estado de la conversación se mantiene en memoria solo durante la vida útil del proceso en ejecución y no sobrevive a reinicios o reducciones de escala.

Esto se implementa en el session.py generado, que exporta una función get_checkpointer() llamada desde create_agent(..., checkpointer=get_checkpointer()) de agent.py.

Invocar tu Agente

Invocar el Servidor Local

Para invocar un Agente ejecutándose localmente a través del target <your-agent-name>-serve, puedes enviar una simple solicitud POST a /invocations en el puerto en el que se está ejecutando tu agente local. Por ejemplo, con curl:

curl -N -X POST http://localhost:8081/invocations \
  -d '{"prompt": "what is 3 + 5?"}' \
  -H "Content-Type: application/json"

Invocar el Agente Desplegado

Para invocar tu Agent desplegado en Bedrock AgentCore Runtime, puedes enviar una solicitud POST al endpoint del plano de datos de Bedrock AgentCore Runtime con tu ARN codificado en URL.

Puedes obtener el ARN del runtime desde tu infraestructura de la siguiente manera:

CDK
Terraform

import { CfnOutput } from 'aws-cdk-lib';
import { MyProjectAgent } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    new CfnOutput(this, 'AgentArn', {
      value: agent.agentCoreRuntime.agentRuntimeArn,
    });
  }
}

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

output "agent_arn" {
  value = module.my_project_agent.agent_core_runtime_arn
}

El ARN tendrá el siguiente formato: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Luego puedes codificar el ARN en URL reemplazando : con %3A y / con %2F.

Esto es sencillo en una consola del navegador o en un REPL de Node usando el método integrado encodeURIComponent:

encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')

La URL del plano de datos de Bedrock AgentCore Runtime para invocar el agent es la siguiente:

https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations

Tu infraestructura también puede generar la URL de invocación completa directamente, con la codificación del ARN manejada por ti:

CDK
Terraform

new CfnOutput(this, 'AgentUrl', {
  value: agent.invocationUrl,
});

output "agent_url" {
  value = module.my_project_agent.invocation_url
}

La forma exacta de invocar esta URL depende del método de autenticación utilizado.

IAM
Cognito

Autenticación IAM

Para Autenticación IAM, la solicitud debe firmarse usando AWS Signature Version 4 (SigV4).

acurl <region> bedrock-agentcore -N -X POST \
'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-d '{"prompt": "what is 3 + 5?"}' \
-H 'Content-Type: application/json'

Haz clic aquí para más detalles sobre cómo configurar el comando acurl anterior

Autenticación JWT / Cognito

Para Autenticación Cognito, pasa el Token de Acceso de Cognito en el encabezado Authorization:

curl -N -X POST 'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
  -d '{"prompt": "what is 3 + 5?"}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>"

Puedes obtener el token de acceso usando el comando cognito-idp admin-initiate-auth de AWS CLI, por ejemplo:

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --region <region> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

Navegador / Sitio Web React

Para invocar tu Agente desde un sitio web React, puedes hacer uso del generador connection, que configura automáticamente un cliente con la autenticación correcta (IAM o Cognito).

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - connection
Complete los parámetros requeridos
Haga clic en Generate

Consulta la guía del generador connection para detalles sobre cómo se configura la conexión.

Invocar un Agente A2A como Herramienta

Para delegar trabajo desde este agente a un agente A2A remoto (ya sea TypeScript o Python), usa el generador connection. Proporciona un cliente autenticado con SigV4 para el agente objetivo y transforma con AST el agent.py de este agente para registrar el agente A2A remoto como un delegado decorado con @tool.

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - connection
Complete los parámetros requeridos
Haga clic en Generate

Consulta la guía del generador connection para detalles sobre cómo se configura la conexión.

Invocar un Agente AG-UI

Para invocar tu agente AG-UI desde un sitio web React, usa el generador connection, que conecta un cliente CopilotKit configurado para tu agente desplegado con la autenticación correcta (IAM o Cognito).

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - connection
Complete los parámetros requeridos
Haga clic en Generate

Consulta la guía del generador connection para detalles sobre cómo se configura la conexión.

Asegurar tu Agente

Los agentes actúan sobre entradas no confiables y pueden ejecutar acciones reales a través de sus herramientas, por lo que vale la pena considerar la seguridad desde el principio. Las siguientes prácticas se aplican al agente generado.

Trata la entrada y salida del modelo como no confiables

Los prompts pueden contener instrucciones adversarias (inyección de prompts), y la salida del modelo es no determinística — ninguna debe ser confiable en lógica sensible a la seguridad:

Define esquemas de entrada estrictos para tus herramientas, como en la herramienta de ejemplo generada. Restringe los valores a lo que la herramienta realmente necesita (enums, límites de longitud, rangos numéricos) en lugar de aceptar cadenas de forma libre.
Nunca pases la salida del modelo directamente a comandos de shell, consultas SQL, evaluación de código o HTML renderizado sin validación o codificación.
Aplica verificaciones de autorización en tus herramientas y servicios descendentes — no confíes en el prompt del sistema para evitar que el modelo haga mal uso de una herramienta a la que tiene acceso.

Las guías de Prompt Engineering y Responsible AI de Strands cubren cómo escribir prompts de sistema robustos y conscientes de la seguridad.

Limita los permisos de las herramientas de forma estricta

Otorga al rol IAM del agente solo los permisos que sus herramientas necesitan. Los constructos CDK y módulos Terraform proporcionados exponen métodos grant* y políticas con alcance limitado para este propósito — por ejemplo, otorgar a un agente acceso para invocar una API específica en lugar de adjuntar políticas administradas amplias. Cuando una herramienta actúa en nombre de un usuario, prefiere autorizar la acción usando la identidad del usuario que llama (pasada a través del contexto de la solicitud) sobre los permisos ambientales propios del agente.

Proporciona un interruptor de emergencia

Debido a que el comportamiento del modelo puede cambiar de formas inesperadas, planifica para deshabilitar o intercambiar rápidamente el modelo sin un cambio de código:

Lee el ID del modelo desde la configuración (por ejemplo, una variable de entorno MODEL_ID) para que los operadores puedan cambiar o revertir a un modelo diferente actualizando la configuración.
Coloca el agente detrás de un feature flag para que su funcionalidad de IA pueda deshabilitarse por completo. Cuando esté deshabilitado, devuelve un mensaje genérico en lugar de un error, y asegúrate de que el resto de tu aplicación se degrade de manera elegante.

Documenta cómo activar estos controles en tu manual operativo.

Protege los datos sensibles

Evita registrar prompts y completaciones, que pueden contener datos de usuario. El hook de registro de errores del modelo del agente generado registra solo metadatos de error, no contenido de conversación — mantén esta propiedad al agregar tu propio registro.
Devuelve mensajes de error genéricos a los usuarios; registra errores detallados del lado del servidor.
Aísla el estado de conversación entre usuarios y sesiones, y autoriza el acceso a cualquier dato de sesión persistido.
Redacta información de identificación personal (PII) de los prompts y salidas — ya sea con un filtro de información sensible de Bedrock Guardrail (abajo) o, para agentes Strands, los enfoques en la guía de PII Redaction.

Amazon Bedrock Guardrails

Amazon Bedrock Guardrails proporciona filtros de contenido configurables, temas denegados y filtros de información sensible (PII) que se evalúan en la entrada y salida del modelo. Puedes adjuntar un guardrail al modelo utilizado por el agente generado:

Strands
LangChain

import os

from strands import Agent
from strands.models import BedrockModel

model = BedrockModel(
    model_id=os.environ.get("MODEL_ID"),
    guardrail_id=os.environ["GUARDRAIL_ID"],
    guardrail_version=os.environ.get("GUARDRAIL_VERSION", "DRAFT"),
)

agent = Agent(model=model)

Consulta la guía de Guardrails de Strands para más detalles.

import os

from langchain_aws import ChatBedrockConverse

model = ChatBedrockConverse(
    model=os.environ.get("MODEL_ID"),
    guardrail_config={
        "guardrailIdentifier": os.environ["GUARDRAIL_ID"],
        "guardrailVersion": os.environ.get("GUARDRAIL_VERSION", "DRAFT"),
    },
)

Consulta la documentación de ChatBedrockConverse para los campos de guardrail_config.

Conexiones

Usa el generador connection para integrar este proyecto con otros en tu workspace. Las siguientes conexiones involucran este proyecto:

React to Python AgentCall a Python Agent from a React website

React to AG-UI AgentCall an Agent exposing the AG-UI protocol from a React website via CopilotKit

Python Agent to MCPConnect a Python Agent to an MCP server

Python Agent to A2A AgentConnect a Python Agent to a remote A2A agent

TypeScript Agent to A2A AgentConnect a TypeScript Agent to a remote A2A agent

Python Agent to Python DynamoDBConnect a Python Agent to a DynamoDB table

Python Agent to AgentCore GatewayConnect a Python Agent to an AgentCore Gateway

AgentCore Gateway to AgentFront an agent with an AgentCore Gateway as a runtime target