Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Comience a usar Amazon Bedrock AgentCore
Esta guía de inicio rápido le permite pasar de cero a tener un agente en ejecución en unos minutos con el AgentCore CLIP. Instalará la CLI, estructurará un proyecto, lo probará localmente y lo implementará en AWS e invocará a su agente.
Dos formas de crear un agente AgentCore, la misma CLI:
-
Arnés gestionado. Usted declara el agente en un archivo de configuración (modelo, indicador, herramientas, memoria) y AgentCore ejecuta el ciclo por ti. Sin marco, sin código de orquestación. Es una buena opción si quieres la ruta más rápida desde la idea hasta un agente en ejecución. Más información.
-
Code-based agente. Escribes el bucle del agente en Python o TypeScript usando un marco que ya conoces (Strands, LangChain, o el Vercel AI (SDK), e impleméntelo en AgentCore Tiempo de ejecución. Control total sobre la lógica de orquestación.
En esta página se describe el flujo basado en código. Para ver el arnés, consulte ¿Qué es el AgentCore arnés.
Regístrate para un AWS inscrita
Inscríbase para un AWS inscrita
Para empezar con AWS, necesitas un AWS cuenta. Para obtener información sobre la creación de una AWS cuenta, consulte Cómo empezar con un AWS cuenta en la AWS Guía de referencia para la administración de cuentas.
Requisitos previos
-
Node.js 20.12 o posterior. El AgentCore La CLI se distribuye como un paquete npm. Consulte con
node --version. Instalar desde nodejs.orgsi es necesario. -
npm. Incluido con Node.js.
-
Un AWS cuenta con credenciales configuradas. Configurar mediante AWS CLI, variables de entorno o un AWS perfil. Ver Configurar el AWS CLI.
-
Python 3.10 o posterior (para código de agente). Consulte con
python3 --version. -
UV. El proyecto Python generado usa
uvpara instalar y administrar dependencias. Consulte Instalación de uv. -
Permisos de IAM. Tu identidad necesita permisos para hacer AgentCore Llamadas a la API y para asumir las funciones de arranque del CDK utilizadas durante la implementación. Consulte Usa el AgentCore CLI.
-
Acceso modelo. Amazon Bedrock permite el acceso a los modelos básicos de forma predeterminada. Los modelos disponibles incluyen los modelos Amazon Nova, Anthropic Claude, Meta Llama y Mistral AI. Para usar modelos que no sean básicos, siga las pasos de acceso al modelo.
-
Motor de contenedores (solo para el desarrollo de contenedores locales). Se requieren Docker, Podman o Finch para funcionar
agentcore devcon elagent-python-strands-containerplantilla. Las compilaciones e implementaciones de contenedores en la nube utilizan AWS CodeBuild y no requieren un motor de contenedores local. Elagent-python-strandsla plantilla de esta guía de inicio rápido usa unCodeZipconstruir.
Esta guía de inicio rápido utiliza Amazon Bedrock y AgentCore Memoria. La receta predeterminada de la CLI no se aplica a las regiones de China. Para el CLI-specific alternativas y restricciones, consulte Alcance del proyecto CLI en las regiones de China.
Paso 1: instala el AgentCore CLI
npm install -g @aws/agentcore
Verificar:
agentcore --version
Si esto indica un error en lugar de un número de versión, un Python anterior agentcore el comando está sombreando el de npm en tu PATH. Esto ocurre si ya ha instalado el bedrock-agentcore-starter-toolkit paquete pip, y es más común en Windows. Ejecute pip uninstall bedrock-agentcore-starter-toolkity, a continuación, abre una nueva terminal e inténtalo de nuevo.
Para actualizar más adelante, vuelva a ejecutar el comando de instalación o agentcore update. Fuente y problemas: agentcore-cli en GitHub
Corre agentcore sin argumentos para buscar comandos de forma interactiva. Escriba para filtrar la lista y, a continuación, seleccione un comando para abrir su flujo de trabajo o la ayuda de la línea de comandos.
Paso 2: Crea tu proyecto
agentcore create \ --name MyProject \ --template agent-python-strands
El --template agent-python-strands la opción crea un agente de Python basado en código que usa el SDK de Strands Agents y Amazon Bedrock. La CLI también:
-
Crea el
agentRuntime y su código de aplicación. -
Añade un AgentCore Recurso de memoria.
-
Instala las dependencias de CDK y Python con
npm installyuv sync. -
Inicializa un repositorio de Git.
Ejecuta agentcore create sin banderas para usar el asistente interactivo. El asistente utiliza de forma predeterminada un arnés gestionado. Para un proyecto basado en código, elija basado en código, una plantilla y, en el caso de las plantillas que la admiten, un proveedor de modelos y un modelo antes de revisar la configuración. Solo para aprobar --name crea un proyecto de arnés gestionado, así que especifique --template al crear un proyecto basado en código de forma no interactiva.
Para ver todos los comandos y opciones disponibles, consulte AgentCore CLI.
Tipos de construcción
El agent-python-strands la plantilla crea un CodeZip Tiempo de ejecución. Este tipo de compilación empaqueta tu código en un archivo zip y no requiere Docker.
Para crear el mismo agente de Strands que una imagen de contenedor, usa la plantilla de contenedor:
agentcore create \ --name MyProject \ --template agent-python-strands-container
La aplicación CDK carga la fuente del contenedor y usa AWS CodeBuild para crear la imagen y enviarla a Amazon ECR durante la implementación. Solo necesitará un motor Docker, Podman o Finch en ejecución cuando pruebe este contenedor localmente con agentcore dev.
Elija un proveedor de modelos de tiempo de ejecución
Python Strands, el contenedor Python Strands, A2A Python Strands, AG-UI Python Strands, y TypeScript Las plantillas de Strands admiten la elección del proveedor de modelos en el modo interactivo agentcore create mago. Corre agentcore create sin banderas, elige basado en códigoy, a continuación, elija la plantilla, el proveedor, el modelo y API-key archivo.
El no interactivo agentcore create --template <template> El comando usa el proveedor de modelos predeterminado de la plantilla. No acepta marcas de proveedores de modelos. El agentcore add runtime el comando es para código que escribes tú mismo. No selecciona un proveedor de modelos ni genera código de integración de modelos.
El asistente admite los siguientes proveedores de modelos para las plantillas que los implementan:
-
Amazon Bedrock
-
Anthropic
-
OpenAI
-
Gemini
-
LiteLLM
-
OpenAI-compatible puntos finales
TypeScript Strands no es compatible con LitellM. Usa un OpenAI-compatible punto final en su lugar. Amazon Bedrock usa AWS credenciales. Para los proveedores que necesitan una clave de API, seleccione un archivo de claves local o stdin en el asistente. La CLI almacena la clave en agentcore/.env.local. No confirme ese archivo ni el archivo de claves de origen.
¿Un OpenAI-compatible El proveedor necesita una URL de punto final, un ID de modelo explícito servido por ese punto final y una clave de API. Utilice solo un punto final confiable porque recibe la clave de API. El asistente muestra los valores predeterminados del proveedor y los enlaces al catálogo de modelos. Confirme el acceso al modelo con su proveedor.
La configuración del modelo de arnés utiliza un conjunto diferente de opciones. Consulte Modelos e instrucciones.
Alcance del proyecto CLI en las regiones de China
En cn-north-1 y cn-northwest-1, esta versión de la CLI admite las siguientes adiciones al proyecto:
-
Tiempos de ejecución y puntos finales de tiempo de ejecución
-
Credenciales
-
Destinos de puertas de enlace y puertas de enlace que no son conectores
Bloquea los siguientes recursos y plantillas del proyecto:
-
arneses
-
Memoria
-
Objetivos del conector Gateway
-
El
environment-python-bmamodelo
En el asistente de creación interactivo, puede elegir un OpenAI-compatible punto final con un punto final, un identificador de modelo y una clave explícitos. Con las plantillas de Python, también puede elegir LitellM con un ID de modelo explícito que no utilice el bedrock/ prefijo. Provider-free plantillas como agent-python-minimal y mcp-python-fastmcp son otra alternativa. La CLI omite la memoria predeterminada al estructurar una plantilla permitida en una región de China.
También puedes usar agentcore add runtime para registrar Python o TypeScript código que escribes tú mismo. Como la CLI no genera ni inspecciona la integración de tu modelo, comprueba que tu código llame a un modelo o punto final al que se pueda acceder desde la región de China de destino.
Se trata de reglas de validación de la CLI, no de una garantía de accesibilidad del modelo o punto final desde China ni de una lista completa de la disponibilidad de los servicios regionales. Verifique el acceso al punto final elegido y a los servicios que utiliza la aplicación.
Estructura de un proyecto
El comando create genera el siguiente proyecto basado en código:
MyProject/ ├── .gitignore ├── agentcore/ │ ├── .env.local │ ├── agentcore.json │ ├── aws-targets.json │ └── cdk/ └── app/ └── agent/ ├── .gitignore ├── README.md ├── main.py ├── memory/ │ ├── __init__.py │ └── session.py ├── model/ │ ├── __init__.py │ └── load.py ├── parse.py └── pyproject.toml
Archivos clave:
-
agentcore/agentcore.json- La especificación del proyecto. Define los tiempos de ejecución, los arneses, los almacenes de memoria, las puertas de enlace, las credenciales y otros recursos. Elagentcore addyagentcore removelos comandos administran este archivo. -
agentcore/aws-targets.json- El AWS cuentas y regiones para el despliegue. -
agentcore/.env.local- Secretos locales, como las claves de API para los proveedores de modelos de Runtime y las credenciales de Harness gestionadas por proyectos. -
agentcore/cdk/- La aplicación CDK que crea e implementa los recursos del proyecto. Consulte Personalice el código CDK del proyecto para agregar recursos más allá de las especificaciones del proyecto. -
app/agent/main.py- La implementación del agente Runtime Entrypoint y Strands. -
app/agent/model/load.py- El modelo que usa el agente. -
app/agent/memory/session.py- El AgentCore Administrador de sesiones de memoria y configuración de recuperación.
Paso 3: Probar localmente
cd MyProject agentcore dev --mode browser
El comando inicia el Runtime localmente con una recarga en caliente y abre el inspector de agentes en su navegador para poder chatear con el agente e inspeccionar los rastros locales. El comando create instaló las dependencias y creó el entorno virtual de Python en el paso 2.
Sin --mode browser, agentcore dev pasa al modo headless de forma predeterminada y transmite la salida de Runtime a tu terminal.
Paso 4: Despliegue su agente
Cree los artefactos desplegables y valide el proyecto antes de implementarlo:
agentcore build
Implemente el proyecto:
agentcore deploy
El comando deploy hace lo siguiente:
-
Empaqueta el código en un artefacto zip
-
Usos AWS CDK bajo el capó para sintetizar y aprovisionar recursos
-
Crea un AgentCore Punto final de tiempo de ejecución para su agente
-
Configura CloudWatch registro y observabilidad
La primera implementación tarda unos minutos mientras CDK arranca tu cuenta. Los despliegues posteriores son más rápidos.
Compruebe el estado:
agentcore status
Paso 5: Invoca al agente desplegado
agentcore invoke --runtime agent \ --payload '{"prompt":"Hello, what can you do?"}'
Para iterar, edite app/agent/main.py, pruebe con agentcore dev --mode browser, despliega con agentcore deploy, e invoca con agentcore invoke --runtime agent.
Añada capacidades a su proyecto
agentcore add administra los recursos en agentcore.json. Ejecútelo sin argumentos para el menú interactivo o diríjase directamente a un recurso. Cada recurso abre un asistente cuando se ejecuta sin opciones.
Por ejemplo, agentcore add runtime solicita un nombre, un idioma y un protocolo y, a continuación, muestra la configuración para su revisión. Registra un tiempo de ejecución para el código que escribes tú mismo. El comando crea app/<name>/README.md y app/<name>/AGENTS.md con el contrato de protocolo seleccionado, pero no genera código de aplicación ni dependencias ni sobrescribe los archivos que ya están en el directorio.
agentcore add memory # Store conversation context agentcore add runtime # Add another Runtime agentcore add gateway # Connect APIs and tools through Gateway
Para agregar un Runtime sin el asistente, indique su idioma y protocolo:
agentcore add runtime \ --name worker \ --language python \ --protocol HTTP
El Runtime comienza como un código directo (CodeZip) construya con main.py para Python o main.js por TypeScript. Siga el README generado para agregar el punto de entrada y el manifiesto de dependencia. Cuando corres agentcore dev, agentcore build, o agentcore deploy, la CLI se sincroniza agentcore.json con el código. UN Dockerfile cambia el Runtime a una compilación de contenedor. Para Python, requires-python en pyproject.toml restringe la versión de tiempo de ejecución gestionada y [tool.agentcore].entrypoint puede seleccionar otro punto de entrada. Para TypeScript, engines.node restringe el Node.js la versión y los paquetes de CLI main.ts.
Para traducir un agente existente de Agentes de Amazon Bedrock en Amazon Bedrock AgentCore Código de ejecución, en su lugar, pase su ID de agente. No apruebe --language o --protocol con una importación.
Reemplazar <bedrock-agent-id> con su ID de agente y <prepared-agent-alias-id> con el seudónimo que has preparado:
agentcore add runtime \ --name imported_agent \ --agent-id <bedrock-agent-id> \ --agent-alias-id <prepared-agent-alias-id> \ --framework strands
Para agregar otro tipo de recurso sin su asistente, pase sus opciones a la línea de comandos. Ejecute agentcore add <resource> --help para ver las opciones.
Después de agregar los recursos, ejecute agentcore deploy para aprovisionarlos.
Descubre en profundidad las capacidades que puedes adjuntar:
-
AgentCore Memoria - memoria a corto y largo plazo, estrategias de recuperación
-
AgentCore Portal - conectividad regulada con API y servidores MCP
-
AgentCore - Navegador - navegación web gestionada para agentes
-
AgentCore - Interpretador de código - ejecución de código en espacio aislado
-
AgentCore Identidad - OAuth, proveedores de credenciales de claves de API, identidad de carga de trabajo
-
AgentCore - Observabilidad - trazas, registros y métricas en CloudWatch
-
AgentCore VPC - ejecuta agentes dentro de tu VPC
-
AgentCore - Pagos - pagos por microtransacciones para agentes a través de x402
Ver registros y trazas
# Stream Runtime logs agentcore logs runtime # Search a past window agentcore logs runtime --since 30m --level error agentcore logs runtime --since 1h --query "timeout" # List recent Runtime traces agentcore traces runtime list --since 30m # Download a specific trace agentcore traces runtime get <trace-id>
Solución de problemas
- Errores de permiso denegado
-
Verifique sus credenciales con
aws sts get-caller-identity. Asegúrese de que su identidad tenga los permisos en Usa el AgentCore CLI. - Acceso al modelo denegado
-
Amazon Bedrock permite el acceso a los modelos básicos de forma predeterminada. Para usar un modelo que no sea básico, siga las pasos de acceso al modelo.
- El puerto ya está en uso
-
¡Ejecute
agentcore dev --port 8081para usar un puerto local diferente para el Runtime, o agregar--ui-portpara cambiar el puerto del Agent Inspector. Cuando invoque localmente, pase el mismo puerto poragentcore invoke --runtime agent --local --port 8081. - Errores de implementación
-
Ejecutar
agentcore build --debugpara reconstruir los artefactos desplegables con un registro de depuración antes de volver a intentarloagentcore deploy --debug. - Errores de validación de la configuración
-
Ejecute
agentcore buildpara validar la especificación del proyecto y crear sus artefactos desplegables.
Para obtener más información, consulte Solucionar problemas de Amazon Bedrock AgentCore Tiempo de ejecución.
Limpieza
agentcore remove all --yes agentcore deploy --yes
remove all elimina todos los recursos de la especificación del proyecto. La implementación de seguimiento detecta el estado vacío y elimina la pila implementada del proyecto. El --yes la opción confirma el desmontaje sin un mensaje interactivo.
Siguientes pasos
-
¿Qué es el AgentCore arnés - la ruta basada en la configuración a un agente en ejecución. Utilice cualquier modelo, conéctese a las herramientas, mantenga el estado, impleméntelo en su VPC y actualice el código cuando lo necesite.
-
AgentCore ejemplos de código
- ejemplos de principio a fin en todos los marcos y capacidades.