Agente de Python

Genera un agente de IA en Python para construir agentes con herramientas, y opcionalmente desplegarlo 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 mediante 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 el frontend mediante CopilotKit.

Uso

Generar un Agente

Puedes generar un Agente de Python de dos formas:

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

yarn

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

npm

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

bun

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

Requisito previo del proyecto

Primero usa el generador py#project para crear un proyecto donde añadir tu Agente.

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.
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 añadirá los siguientes archivos a tu proyecto Python existente. Los archivos generados dependen del protocol elegido:

protocol = http

Protocolo HTTP (por defecto)

• Directorioyour-project/

  • Directorioyour_module/

    • Directorioagent/ (o nombre personalizado si se especifica)

      • __init__.py Inicialización del paquete Python
      • init.py Configuración de aplicación FastAPI con middleware CORS y manejo de errores
      • agent.py Definición principal del agente con herramientas de ejemplo
      • main.py Punto de entrada FastAPI para Bedrock AgentCore Runtime
      • Dockerfile Punto de entrada para alojar tu agente (excluido cuando infra es None)
  • pyproject.toml Actualizado con dependencias de Strands
  • project.json Actualizado con objetivos de servicio del agente

protocol = a2a

Protocolo A2A

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

• Directorioyour-project/

  • Directorioyour_module/

    • Directorioagent/ (o nombre personalizado si se especifica)

      • __init__.py Inicialización del paquete Python
      • agent.py Definición principal del agente con herramientas de ejemplo
      • main.py Punto de entrada del servidor A2A
      • Dockerfile Punto de entrada para alojar tu agente (excluido cuando infra es None)
  • pyproject.toml Actualizado con dependencias del framework y A2A
  • project.json Actualizado con objetivos de servicio del agente

protocol = ag-ui

Protocolo AG-UI

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

• Directorioyour-project/

  • Directorioyour_module/

    • Directorioagent/ (o nombre personalizado si se especifica)

      • __init__.py Inicialización del paquete Python
      • agent.py Definición principal del agente con herramientas de ejemplo
      • main.py Punto de entrada del servidor AG-UI
      • Dockerfile Punto de entrada para alojar tu agente (excluido cuando infra es None)
  • pyproject.toml Actualizado con dependencias del framework y AG-UI
  • project.json Actualizado con objetivos de servicio del agente

Conectar a un sitio web React

Los agentes AG-UI pueden conectarse a un frontend React usando el generador connection, que configurará los componentes de CopilotKit para una experiencia de chat enriquecida.

Infraestructura

infra = agentcore

Dado que este generador proporciona infraestructura como código basada en tu proveedor de iacProvider seleccionado, creará un proyecto en packages/common que incluye los constructos CDK o módulos de Terraform correspondientes.

El proyecto común de infraestructura como código tiene la siguiente estructura:

CDK

• Directoriopackages/common/constructs

  • Directoriosrc

    • Directorioapp/ Constructos para infraestructura específica de un proyecto/generador

      • …
    • Directoriocore/ Constructos genéricos reutilizados por los constructos en app

      • …
    • index.ts Punto de entrada que exporta los constructos de app
  • project.json Objetivos de compilación y configuración del proyecto

Proyecto generado

Este proyecto se genera utilizando el ts#project generator y por lo tanto configura los mismos objetivos de compilación.

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

    • Directorioapp/ Módulos de Terraform para infraestructura específica de un proyecto/generador

      • …
    • Directoriocore/ Módulos genéricos reutilizados por los módulos en app

      • …
  • project.json Objetivos de compilación y configuración del proyecto

Proyecto generado

Este proyecto se genera utilizando el terraform#project generator y por lo tanto configura los mismos objetivos de compilación.

Para desplegar tu Agente, se generan los siguientes archivos:

CDK

• Directoriopackages/common/constructs/src

  • Directorioapp

    • Directorioagents

      • Directorio<project-name>

        • <project-name>.ts Constructo CDK para desplegar tu agente

Terraform

• Directoriopackages/common/terraform/src

  • Directorioapp

    • Directorioagents

      • Directorio<project-name>

        • <project-name>.tf Módulo para desplegar tu agente
  • Directoriocore

    • Directorioagent-core

      • runtime.tf Módulo genérico para despliegue en Bedrock AgentCore Runtime

infra = none

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.

Arquitectura

Bedrock AgentCore Runtime

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.

None (local only)

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.

Trabajando con tu Agente

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

Añadiendo 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 el docstring, y generan el esquema de entrada a partir de tus type hints.

Strands

from strands import Agent, tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """Calcula la suma de una lista de números"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Obtiene información meteorológica de una ciudad"""
    # Tu integración de API del tiempo aquí
    return f"Weather in {city}: Soleado, 25°C"

# Añade herramientas al agente
agent = Agent(
    system_prompt="Eres un asistente útil con acceso a varias herramientas.",
    tools=[calculate_sum, get_weather],
)

LangChain

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:
    """Calcula la suma de una lista de números"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Obtiene información meteorológica de una ciudad"""
    # Tu integración de API del tiempo aquí
    return f"Weather in {city}: Soleado, 25°C"

# Añade herramientas al agente
agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[calculate_sum, get_weather],
    system_prompt="Eres un asistente útil con acceso a varias herramientas.",
)

Usando Herramientas Preconstruidas

Strands

Strands provee 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="Eres un asistente útil.",
    tools=[current_time, http_request, file_read],
)

LangChain

LangChain proporciona un amplio 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="Eres un asistente útil.",
)

Configuración de Modelos

Strands

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

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

LangChain

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

Consumiendo Servidores MCP

Para consumir servidores MCP creados con 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.

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

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

yarn

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

npm

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

bun

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

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 de MCP de Strands o LangChain.

Más información

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

Protocolo

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

• HTTP (por defecto): Un servidor FastAPI estándar con un endpoint personalizado /invocations, CORS y streaming. Mejor para integraciones de clientes personalizados.
• A2A: Un servidor Agent-to-Agent montado sobre 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 mediante SSE (Strands usa ag-ui-strands; LangChain usa ag-ui-langgraph). Mejor para integración directa con el frontend usando 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 ejecuta un grafo compilado create_agent), 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 de 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.

protocol = http

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)

Personalizando 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.

Definiendo Modelos de Entrada

El modelo InvokeInput por defecto acepta un mensaje.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    message: str

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

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

Organización del código

Probablemente querrás abstraer parte o todo el ID de sesión del llamador si los usuarios van a invocar tu agente directamente. Por ejemplo, puedes usar el ID de usuario autenticado como parte del ID de sesión.

También vale la pena señalar que dependiendo de tu caso de uso, puede que necesites implementar autorización para las sesiones, por ejemplo asegurándote de que los usuarios solo puedan acceder a sus propias sesiones y no a las de otros usuarios.

Definiendo 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 perfectamente 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 según tus necesidades:

from pydantic import BaseModel

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

Limitación de streaming de FastAPI

Ten en cuenta que dado que FastAPI actualmente no soporta generar 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))

Existe una solicitud de característica abierta para soporte nativo en FastAPI.

SDK Python de Bedrock AgentCore

El generador incluye una dependencia del SDK Python de Bedrock AgentCore 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 detalles sobre las capacidades del SDK en la documentación.

Infraestructura como código

Como el generador provee infraestructura CDK/Terraform para desplegar tu agente, no necesitas usar el bedrock-agentcore-starter-toolkit mencionado en los docs.

protocol = a2a

Servidor A2A (protocolo A2A)

El main.py generado monta un servidor A2A sobre 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.

protocol = ag-ui

Servidor AG-UI (protocolo AG-UI)

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

• Strands: envuelve tu Agent en un ag_ui_strands.StrandsAgent y crea la aplicación FastAPI mediante create_strands_app().
• LangChain: envuelve el grafo compilado en un ag_ui_langgraph.LangGraphAgent y lo sirve desde un bucle FastAPI /invocations 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.

Conectar a un sitio web React

Los agentes AG-UI están diseñados para ser consumidos directamente por un frontend. Usa el generador connection para conectar tu sitio web React al agente con un proveedor de CopilotKit y un cliente AG-UI HttpAgent.

Ejecutando tu Agente

Desarrollo Local

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

pnpm

pnpm nx dev your-project

yarn

yarn nx dev your-project

npm

npx nx dev your-project

bun

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

pnpm nx agent-dev your-project

yarn

yarn nx agent-dev your-project

npm

npx nx agent-dev your-project

bun

bunx nx agent-dev your-project

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

Chatear con tu Agente

El generador configura un target Nx <your-agent-name>-chat que te lleva a un chat interactivo en la 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

pnpm nx agent-dev your-project

yarn

yarn nx agent-dev your-project

npm

npx nx agent-dev your-project

bun

bunx nx agent-dev your-project

Luego, en otra terminal, inicia el chat:

pnpm

pnpm nx run your-project:agent-chat

yarn

yarn nx run your-project:agent-chat

npm

npx nx run your-project:agent-chat

bun

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 más abajo).

Para agentes HTTP, el script de chat usa un cliente TypeScript con 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 tipos bajo scripts/<your-agent-name>/generated/

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

infra = agentcore

Chat with your deployed agent

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

IAM

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:

pnpm

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

yarn

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

npm

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

bun

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

Cognito

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:

pnpm

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

yarn

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

npm

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

bun

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

infra = agentcore

Desplegando tu Agente a 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

Se genera una construcción CDK para tu agente, nombrada según el name que elegiste al ejecutar el generador, o <ProjectName>Agent por defecto.

Puedes usar esta construcción 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');
  }
}

Constructo CDK

Esta construcción utiliza el módulo aws-cdk-lib/aws-bedrockagentcore.

Terraform

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
}

Permisos de Modelos Bedrock

La construcción del agente generada otorga permiso para invocar todos los modelos fundacionales y perfiles de inferencia de Bedrock por defecto (bedrock:InvokeModel y bedrock:InvokeModelWithResponseStream en arn:aws:bedrock:*:*:foundation-model/* y arn:aws:bedrock:*:*:inference-profile/*).

Es posible que desees limitar esto a los modelos específicos que usa tu agente. Puedes encontrar el modelo predeterminado utilizado por los agentes Strands en la documentación de Strands; consulta la guía de proveedores de modelos de Strands para configurar un modelo diferente.

Docker requerido

Docker es necesario 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

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);
  }
}

Terraform

# 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

La construcción generada acepta una propiedad 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,
    });
  }
}

La construcción UserIdentity puede generarse usando el generador ts#website#auth, o puedes crear tu propio UserPool y UserPoolClient de CDK.

Terraform

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]
}

Proveedores OIDC personalizados

Si requieres autenticación JWT personalizada con un proveedor OIDC que no sea Cognito, puedes modificar directamente la construcción CDK o el módulo Terraform generado para tu agente. Ten en cuenta que el generador de conexión solo admitirá autenticación IAM o Cognito.

Mejores Prácticas de Seguridad

Al implementar la lógica de negocio de tu agente, revisa las mejores prácticas de seguridad de Bedrock AgentCore Runtime.

Targets de Bundle y Docker

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

• Exporta dependencias Python a requirements.txt usando uv export
• Instala dependencias para la plataforma objetivo (aarch64-manylinux_2_28) con uv pip install

También se añade un target docker específico de tu Agente, que copia el Dockerfile y los artefactos empaquetados en un directorio de contexto docker. Esto co-localiza el Dockerfile con la salida construida, permitiendo a CDK construir la imagen Docker directamente usando AgentRuntimeArtifact.fromAsset.

Observabilidad

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

Puedes encontrar trazas en CloudWatch seleccionando “GenAI Observability”. Para ver trazas, habilita Transaction Search.

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

Invocando tu Agente

protocol = http

Invocar el Servidor Local

Para invocar un Agente ejecutándose localmente mediante el target <your-agent-name>-serve, puedes enviar una simple solicitud POST a /invocations en el puerto donde se ejecuta tu agente local. Por ejemplo, con curl:

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

Flag de streaming de Curl

El argumento -N dado a curl deshabilita el buffering del flujo de salida, para que puedas ver la respuesta de streaming en tiempo real.

Invocar el Agente Desplegado

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

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

CDK

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,
    });
  }
}

Terraform

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

Consola del navegador

Esto es sencillo en una consola de navegador o Node REPL 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 agente es la siguiente:

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

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

IAM

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 '{"message": "what is 3 + 5?"}' \
-H 'Content-Type: application/json'

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

Cognito

Autenticación JWT / Cognito

Para autenticación Cognito, pasa el Access Token de Cognito en el header Authorization:

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

Puedes obtener el access token usando el comando cognito-idp admin-initiate-auth del 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).

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

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

yarn

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

npm

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

bun

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

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

protocol = a2a

Invocando 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. Este genera un cliente autenticado con SigV4 para el agente objetivo y transforma mediante AST el agent.py de este agente para registrar el agente A2A remoto como un delegado decorado con @tool.

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

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

yarn

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

npm

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

bun

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

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

protocol = ag-ui

Invocando un Agente AG-UI

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

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

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

yarn

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

npm

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

bun

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

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

Conexiones

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

React a Python Agent Llama a un Python Agent desde un sitio web React

React a AG-UI Agent Llama a un Agent que expone el protocolo AG-UI desde un sitio web React a través de CopilotKit

Python Agent a MCP Conecta un Python Agent a un servidor MCP

Python Agent a A2A Agent Conecta un Python Agent a un agente A2A remoto

TypeScript Agent a A2A Agent Conecta un TypeScript Agent a un agente A2A remoto

Python Agent a Python DynamoDB Conecta un Python Agent a una tabla DynamoDB

Python Agent a AgentCore Gateway Conecta un Python Agent a un AgentCore Gateway