Amazon Bedrock AgentCore

Un conjunto de servicios para desplegar y operar agentes de IA, con cualquier framework y cualquier modelo. Son bloques independientes: puedes usar uno solo o combinarlos.

Hoy vamos a usar tres, que son los que necesita casi cualquier agente en producción: dónde corre, qué recuerda, y cómo se conecta con el mundo.

AgentCore Runtime dónde corre

Un entorno de ejecución sin servidor y aislado, hecho para agentes. Funciona con cualquier framework de código abierto, cualquier protocolo y cualquier modelo.

Tú escribes el código de tu agente: el modelo que usa, el framework, sus instrucciones. El runtime se encarga del resto, que es la parte que nadie quiere mantener: escalar, aislar cada sesión, arrancar rápido en frío, y cargar la identidad y la observabilidad.

Hoy
Tu agente va a ser un runtime. El CLI lo empaqueta, lo sube y lo lanza con un solo comando, sin que escribas nada de infraestructura. Vas a usar el framework Strands y un modelo Nova.

AgentCore Memory qué recuerda

Igual que las personas, un agente necesita memoria de corto y de largo plazo. Corto plazo para sostener una conversación de varios turnos; largo plazo para recordar entre conversaciones distintas.

Corto plazo

Los mensajes de la conversación y el estado de la sesión. Es lo que le permite entender "y si fueran cinco días" sin que le repitas todo.

Largo plazo

Lo que sobrevive a la sesión: hechos, preferencias de la persona, resúmenes. Se extrae de las conversaciones de forma automática y asíncrona.

Hoy
Vas a crear una memoria con la estrategia de preferencias de usuario, para que tu guía turístico recuerde qué le gusta a quien le pregunta, incluso en otra conversación.

AgentCore Gateway cómo se conecta

Una forma segura de que los agentes descubran y usen herramientas. Y también una puerta de acceso para que tu agente pueda ser descubierto.

Un agente sin herramientas solo puede conversar. Para hacer algo en el mundo real necesita llamar APIs, funciones, servicios. El gateway convierte todo eso en herramientas que hablan un único protocolo, MCP, y se encarga de la autenticación de entrada y de salida.

La misma pieza, en dos direcciones

Un gateway es una puerta, y lo que cambia es quién está de cada lado. Eso depende de cómo lo configures, y es la distinción que más se enreda. Hoy vas a crear los dos.

	Gateway de tools	Gateway de chat
Para qué	Que tu agente alcance herramientas	Que el mundo alcance a tu agente
Quién llama	Tu agente	Un navegador, una app, curl
Qué son los targets	Las herramientas: Lambdas, APIs, knowledge bases	Tu propio agente
Protocolo	MCP	HTTP común
Qué obtienes	Una URL que tu agente consume por dentro	Una URL pública que puedes repartir

Exponer herramientas para que el agente las vea

Registras cada herramienta como un target. El gateway las publica todas juntas detrás de una sola URL, y tu agente se conecta ahí como cliente MCP: pregunta qué herramientas hay, y luego invoca la que necesite. No sabe si detrás había una Lambda o una API; el gateway traduce.

Tu agente no lleva esa URL escrita en el código: AgentCore se la entrega como variable de entorno cuando lo despliega. Y los nombres que verá el modelo llevan el target por delante, así que la herramienta get_weather del target weather le llega como weather___get_weather.

Exponer tu agente para que lo alcancen

Aquí el target es tu agente. El gateway te da una URL pública, y a esa URL le agregas el nombre del target más /invocations para obtener la dirección final a la que se le hace un POST con la pregunta.

La razón de que esto exista: tu agente nunca acepta llamadas anónimas, exige credenciales de AWS firmadas. Un navegador no las tiene y no queremos ponerlas en una página web. El gateway sí acepta llamadas sin credenciales, y firma él por dentro con su propia identidad. Es lo que convierte a tu agente en algo que se puede compartir con un enlace.

Tipos de target

Del lado del agente todos los targets se ven igual: herramientas MCP. Del otro lado, cada uno puede ser algo distinto.

Tipo	Qué conecta
lambda-function-arn	Una función Lambda. Le declaras qué parámetros recibe con un archivo de esquema. Hoy: el clima y las rutas
connector	Integraciones que AWS ya trae hechas: knowledge bases de Bedrock, o búsqueda web. Hoy: la knowledge base
http-runtime	Un agente desplegado en AgentCore Runtime. Es el que usa el gateway de chat. Hoy: tu agente
open-api-schema	Cualquier API REST que tenga su especificación OpenAPI
api-gateway	Una API tuya en Amazon API Gateway, por su id y su stage
mcp-server	Otro servidor MCP que ya exista, propio o de un tercero
smithy-model	Servicios descritos con Smithy, el lenguaje de modelado de AWS
passthrough	Reenvía la llamada sin transformarla

Los tres primeros son los que vas a usar. Los demás están en la lista para que veas el alcance: casi cualquier cosa que ya tengas corriendo puede convertirse en herramienta de un agente sin reescribirla.

Hoy
Dos gateways: el de tools con tres targets, la knowledge base, el clima y las rutas; y el de chat con un solo target que apunta a tu agente. Al final vas a pegar esa URL pública en el sitio del taller y conversar con tu agente desde el navegador.

Construye un guía turístico

Un agente que arma itinerarios de Guatemala: busca lugares en una knowledge base, calcula rutas reales y consulta el clima. Al final lo pruebas en un chat desde el navegador.

Cómo se arma

Tu agente no habla directo con sus herramientas: las alcanza a través de un gateway, la pieza que traduce y autentica. Y para que el navegador pueda hablarle a tu agente hace falta un segundo gateway, en el otro sentido.

Las cajas con borde punteado son los dos gateways que vas a crear. Los pasos siguen ese orden: primero las herramientas, luego el agente, luego la puerta por la que se le habla.

Datos que vas a necesitar

Hemos desplegado ciertos recursos para que puedas usarlos sin construirlos: la knowledge base con lugares de Guatemala y dos herramientas, una de clima y una de rutas. Tú no las creas, solo las conectas a tu agente. Copia estos valores tal cual.

1. Instala el CLI

   Se distribuye por npm. La versión va fija para que todos trabajen sobre la misma.

   npm install -g @aws/agentcore@0.30.0

   Cuando termine, comprueba la versión:

   agentcore --version

   Necesitas Node 22.

   Necesitas Node 22 para el CLI, y además Python 3.10 o superior con uv, que es el gestor de paquetes que usa el agente.

   curl -LsSf https://astral.sh/uv/install.sh | sh

   ✓Listo si
   agentcore --version imprime 0.30.0.

2. Comprueba que sigues dentro de AWS

   Iniciaste sesión en la sección anterior. Este paso solo verifica que siga activa.

   aws sts get-caller-identity

   Y que la región sea la correcta:

   aws configure get region

   ✓Listo si
   ves tu correo en el Arn, la cuenta 112604073803 y la región us-east-1.
   !Ojo
   Si dice session has expired, corre aws login. Si te pregunta la región, responde us-east-1: con otra, los pasos siguientes fallan con un error de permisos que no explica la causa.

3. Crea el proyecto y el agente

   El primer comando arma la estructura del proyecto. El segundo agrega un agente de ejemplo que vas a ir modificando.

   Crea el proyecto y entra a la carpeta que genera:

   agentcore create --project-name GuiaTuristica --no-agent \
     && cd GuiaTuristica

   Ya dentro, agrega el agente:

   agentcore add agent --name Guia \
     --type create --build CodeZip \
     --language TypeScript --framework Strands \
     --model-provider Bedrock --memory none

   Crea el proyecto y entra a la carpeta que genera:

   agentcore create --project-name GuiaTuristica --no-agent \
     && cd GuiaTuristica

   Ya dentro, agrega el agente:

   agentcore add agent --name Guia \
     --type create --build CodeZip \
     --language Python --framework Strands \
     --model-provider Bedrock --memory none

   Dos carpetas importan de aquí en adelante:

   Carpeta	Qué tiene
   agentcore/	La configuración de lo que se va a desplegar, en agentcore.json
   app/Guia/	El código de tu agente

4. Instala las dependencias del agente

   Ojo con este paso: es fácil de olvidar y el despliegue falla sin decir por qué.

   Entra a la carpeta del agente, instala, y vuelve a la raíz del proyecto:

   cd app/Guia && npm install && cd ../..

   Entra a la carpeta del agente, instala, y vuelve a la raíz del proyecto:

   cd app/Guia && uv sync && cd ../..

5. Cambia el modelo a Nova

   El CLI genera el agente con un modelo de Anthropic. En esta cuenta solo están habilitados los modelos Nova, así que hay que cambiarlo.

   Abre app/Guia/model/load.ts y cambia el identificador del modelo:

   app/Guia/model/load.ts

   import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
   
   export function loadModel(): BedrockModel {
     return new BedrockModel({ modelId: 'us.amazon.nova-pro-v1:0' });
   }

   Abre app/Guia/model/load.py y cambia el identificador del modelo:

   app/Guia/model/load.py

   from strands.models.bedrock import BedrockModel
   
   
   def load_model() -> BedrockModel:
       return BedrockModel(model_id="us.amazon.nova-pro-v1:0")

   El prefijo us. no es un typo: es un perfil de inferencia, que reparte la carga del modelo entre varias regiones.

6. Crea el gateway de tools

   Es el intermediario entre tu agente y sus herramientas. Tu agente habla un solo protocolo, MCP, y el gateway traduce hacia cada herramienta.

   agentcore add gateway --name tools --authorizer-type NONE

   Fíjate que no lleva --runtimes: este gateway no expone tu agente, expone herramientas para tu agente.

7. Registra las tres herramientas

   La knowledge base se conecta sola, pero de las dos Lambdas hay que declarar qué parámetros reciben. Eso se hace con un archivo por herramienta.

   Crea una carpeta tool-schemas/ en la raíz de tu proyecto, al mismo nivel que agentcore/, y guarda ahí estos dos archivos. Puedes descargarlos con el botón.

   tool-schemas/weather.json Descargar

   [
     {
       "name": "get_weather",
       "description": "Pronostico del clima para unas coordenadas. Devuelve temperatura maxima, minima y probabilidad de lluvia por dia.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "latitude": { "type": "number", "description": "Latitud del lugar" },
           "longitude": { "type": "number", "description": "Longitud del lugar" },
           "days": { "type": "number", "description": "Dias de pronostico, 1 a 7" }
         },
         "required": ["latitude", "longitude"]
       }
     }
   ]

   tool-schemas/route.json Descargar

   [
     {
       "name": "get_route",
       "description": "Distancia y tiempo de conduccion entre dos lugares. Devuelve kilometros y minutos.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "originLatitude": { "type": "number", "description": "Latitud de partida" },
           "originLongitude": { "type": "number", "description": "Longitud de partida" },
           "destinationLatitude": { "type": "number", "description": "Latitud del destino" },
           "destinationLongitude": { "type": "number", "description": "Longitud del destino" }
         },
         "required": [
           "originLatitude",
           "originLongitude",
           "destinationLatitude",
           "destinationLongitude"
         ]
       }
     }
   ]

   Con los archivos en su lugar, registra una herramienta a la vez. El clima:

   agentcore add gateway-target --name weather \
     --type lambda-function-arn \
     --lambda-arn arn:aws:lambda:us-east-1:112604073803:function:workshop-tools-weather \
     --tool-schema-file tool-schemas/weather.json \
     --gateway tools

   Las rutas:

   agentcore add gateway-target --name route \
     --type lambda-function-arn \
     --lambda-arn arn:aws:lambda:us-east-1:112604073803:function:workshop-tools-route \
     --tool-schema-file tool-schemas/route.json \
     --gateway tools

   Y la knowledge base, que va como connector porque AgentCore ya sabe hablar con ella:

   agentcore add gateway-target --name lugares \
     --type connector --connector bedrock-knowledge-bases \
     --knowledge-base-id UPNPXRMV67 \
     --gateway tools

   ✓Listo si
   agentcore status muestra el gateway tools con 3 targets.

8. Deja una sola forma de consultar la knowledge base

   Al registrar la knowledge base, el CLI escribió dos maneras de consultarla dentro de la configuración de tu proyecto. Una de ellas usa modelos adicionales que esta cuenta no tiene habilitados, así que hay que quitarla a mano. El CLI no tiene una opción para omitirla.

   Abre agentcore/agentcore.json, busca el target llamado lugares y mira su lista configurations. Borra el bloque cuyo name es AgenticRetrieveStream, y deja solo el de Retrieve. Tiene que quedar así:

   agentcore/agentcore.json

   {
     "name": "lugares",
     "targetType": "connector",
     "connectorId": "bedrock-knowledge-bases",
     "configurations": [
       {
         "name": "Retrieve",
         "description": "Queries a knowledge base and retrieves information from it.",
         "parameterValues": { "knowledgeBaseId": "UPNPXRMV67" },
         "parameterOverrides": []
       }
     ]
   }

   agentcore status

   ✓Listo si
   junto al gateway tools dice 1 retrieve. Si dice 1 retrieve, agentic ×1, el bloque todavía está ahí.

9. Agrega memoria

   Para que tu agente recuerde las preferencias de la persona entre conversaciones.

   agentcore add memory --name GuiaMemoria --strategies USER_PREFERENCE

10. Crea el gateway de chat, y su target

    El gateway anterior servía para que tu agente alcance sus herramientas. Este es al revés: para que el mundo alcance a tu agente.

    Primero la puerta:

    agentcore add gateway --name chat --authorizer-type NONE --runtimes Guia

    Y después a dónde lleva:

    agentcore add gateway-target --name agente \
      --type http-runtime \
      --runtime Guia --gateway chat

    Hacen falta los dos comandos: el primero crea la puerta, el segundo dice a dónde lleva. El nombre que le pongas al target, aquí agente, va después en la dirección pública.

    ✓Listo si
    agentcore status muestra chat con 1 target. Si aparece sin targets, falta el segundo comando.

    Por curiosidad: tu agente no acepta llamadas anónimas, exige credenciales firmadas. El gateway sí las acepta, y firma él por dentro. Eso es lo que permite que una página web converse con tu agente sin pedirle a nadie que inicie sesión.

11. Conecta tu agente con su gateway

    El CLI dejó el cliente de herramientas apuntando a un servidor de ejemplo público, mcp.exa.ai, que no tiene relación con este ejercicio.

    La dirección de tu gateway todavía no existe: AWS la asigna cuando lo crea. No hace falta desplegar dos veces para averiguarla, porque AgentCore la inyecta en tu agente como variable de entorno:

    Variable	Contiene
    AGENTCORE_GATEWAY_TOOLS_URL	la dirección del gateway tools
    AGENTCORE_GATEWAY_CHAT_URL	la dirección del gateway chat
    MEMORY_GUIAMEMORIA_ID	el identificador de la memoria

    Abre app/Guia/mcp_client/client.ts, quita la constante del ejemplo y usa la variable:

    app/Guia/mcp_client/client.ts

    const MCP_ENDPOINT = process.env.AGENTCORE_GATEWAY_TOOLS_URL;
    
    export function getStreamableHttpMcpClient(): McpClient | undefined {
      if (!MCP_ENDPOINT) return undefined;
    
      const transport = new StreamableHTTPClientTransport(new URL(MCP_ENDPOINT));
      return new McpClient({ transport });
    }

    Abre app/Guia/mcp_client/client.py, quita la constante del ejemplo y usa la variable:

    app/Guia/mcp_client/client.py

    MCP_ENDPOINT = os.environ.get("AGENTCORE_GATEWAY_TOOLS_URL")
    
    
    def get_streamable_http_mcp_client():
        """Returns an MCP Client compatible with Strands"""
        if not MCP_ENDPOINT:
            return None
        return MCPClient(lambda: streamablehttp_client(MCP_ENDPOINT))

    Cuando la variable no existe la función no falla, devuelve vacío. Eso te permite correr el agente en tu máquina antes de que el gateway exista: arranca sin herramientas en lugar de reventar.

12. Escribe tu prompt

    Aquí está el trabajo interesante. Empieza leyendo el archivo principal de tu agente, porque el CLI ya resolvió la parte mecánica y conviene saber qué no tienes que escribir.

    El archivo es app/Guia/main.ts.

    El archivo es app/Guia/main.py.

    Ya viene resuelto	Qué hace
    La lista de clientes de herramientas	Recoge el gateway y descarta lo que no arrancó
    El registro en tools	Le entrega esas herramientas al agente
    Un agente por sesión	Cada conversación mantiene su propio historial
    La respuesta en streaming	El texto sale token por token, no de golpe

    Primero, borra la herramienta de ejemplo. El CLI dejó una que suma dos números, con su registro en la lista de herramientas. No la necesitas: las tres tuyas llegan por el gateway.

    Busca el bloque const addNumbers = tool({ ... }) y la línea tools.push(addNumbers), y bórralos. Si tool queda sin usarse, quítalo también del import.

    Busca la función add_numbers con su decorador @tool y la línea tools.append(add_numbers), y bórralos.

    Ahora el system prompt, que es lo que convierte un modelo genérico en un guía turístico. El CLI dejó uno de relleno que dice "You are a helpful assistant". Con ese, el agente contesta, pero inventa lugares y propone itinerarios imposibles.

    Reemplaza el contenido de SYSTEM_PROMPT, la plantilla de texto que está cerca del inicio del archivo:

    app/Guia/main.ts

    const SYSTEM_PROMPT = `
    Escribe aqui tus instrucciones, en español y en varias lineas.
    `;

    Reemplaza el contenido de DEFAULT_SYSTEM_PROMPT, la cadena de texto que está cerca del inicio del archivo:

    app/Guia/main.py

    DEFAULT_SYSTEM_PROMPT = """
    Escribe aqui tus instrucciones, en español y en varias lineas.
    """

    Antes de escribir, conviene saber qué herramientas tiene tu agente y qué devuelve cada una:

    Herramienta	Recibe	Devuelve
    lugares___Retrieve	una consulta en texto	fragmentos sobre lugares de Guatemala, con sus coordenadas
    route___get_route	coordenadas de origen y destino	kilómetros y minutos de conducción reales
    weather___get_weather	coordenadas y número de días	temperatura máxima, mínima y probabilidad de lluvia

    Decide tú. No hay una respuesta correcta, hay decisiones. Tu prompt debería responder esto:

    1. ¿Qué es el agente y en qué idioma responde?
    2. ¿Qué necesita saber antes de proponer un itinerario? ¿Días disponibles, punto de salida, intereses?
    3. ¿Pregunta o asume cuando le falta un dato? ¿Cuántas preguntas hace por turno?
    4. ¿Cómo le exiges que los lugares salgan de la knowledge base y no de su memoria?
    5. ¿Cuántas horas de traslado al día son razonables? ¿Le pides agrupar por región?
    6. ¿Cuándo debe consultar el clima? ¿Le pides citar la temperatura en la que se basa?
    7. ¿Qué no debe inventar nunca? ¿Qué responde si le piden precios u horarios?
    8. ¿Qué hace si una herramienta le devuelve un error?

    Esto es iterativo: despliega, pregúntale, corrige el prompt, vuelve a desplegar. Dos señales típicas:

    Si notas que...	Al prompt le falta
    Propone lugares que no existen	Exigirle consultar la knowledge base antes de responder
    Propone Tikal y Atitlán el mismo día	Un límite de horas de traslado, y respetar lo que devuelve la herramienta de rutas

13. Despliega

    Compila tu código, lo empaqueta y crea todo en AWS. Tarda unos minutos.

    agentcore deploy -y

    !Ojo
    Sin -y el comando espera una confirmación interactiva y no avanza.

14. Pruébalo desde la terminal

    Una pregunta que obliga a usar las tres herramientas:

    agentcore invoke \
      --prompt "Cuanto se tarda en carro de Antigua a Panajachel, y que clima habra?"

    ✓Listo si
    la respuesta trae kilómetros y minutos concretos, y temperaturas. Si son vagos o redondos, probablemente no usó las herramientas.

    Para seguir la conversación, reusa el identificador de sesión que imprimió:

    agentcore invoke --session-id <el que te imprimió> \
      --prompt "Y si tuviera 5 dias?"

    Y si algo no cuadra, mira lo que pasó por dentro:

    agentcore logs

15. Pruébalo desde el navegador

    Pide al CLI la dirección pública de tu gateway de chat:

    agentcore fetch access --name chat

    Imprime la URL y el tipo de autenticación. Copia la URL y agrégale /agente/invocations al final, donde agente es el nombre que le diste al target del gateway de chat.

    Entra a demo.aibuildersgt.com, registra tu agente con esa dirección, y conversa con él.

    ✓Listo si
    aparece en la lista de agentes y responde en el chat.

agentcore remove all && agentcore deploy -y

Comandos del CLI

Referencia de lo que puedes hacer con agentcore. Los marcados con son los que vas a usar en la práctica.

Empezar

Agregar y quitar piezas

Todos escriben en la configuración. remove tiene los mismos subcomandos que add.

Probar en tu máquina

Desplegar

Usar y observar lo desplegado

Evaluar