View a markdown version of this page

Comience con la AgentCore CLI - Amazon Bedrock AgentCore
Requisitos previosPaso 1: Instalar la AgentCore CLIPaso 2: Cree su proyecto de agentePaso 3: Pon a prueba a tu agente a nivel localPaso 4: Habilite la observabilidad para su agentePaso 5: Implemente en Amazon Bedrock Runtime AgentCorePaso 6: Pruebe el agente desplegadoPaso 7: invoque al agente desplegadoPaso 8: EliminaciónEncuentre sus recursosProblemas y soluciones comunes deOpciones avanzadas (opcional)

Comience con la AgentCore CLI

En este tutorial, se muestra cómo utilizar la AgentCore CLI para crear, implementar e invocar un agente de Python en Amazon Bedrock Runtime AgentCore .

La AgentCore CLI es una herramienta de línea de comandos que estructura los proyectos de los agentes, los implementa en Amazon AgentCore Bedrock Runtime y los invoca. Puede usar la CLI con marcos de agentes de Python populares, como Strands Agents LangChain/LangGraph, Google ADK y OpenAI Agents. En este tutorial se utilizan agentes de Strands.

Para obtener información sobre el protocolo HTTP que utiliza el agente, consulte el contrato de protocolo HTTP.

Requisitos previos

Antes de empezar, asegúrese de tener:

  • AWS Cuenta con credenciales configuradas. Para configurar sus AWS credenciales, consulte Configuración y configuración del archivo de credenciales en la AWS CLI.

  • Node.js Más de 20 instalados. La AgentCore CLI se distribuye como un paquete npm.

  • Python 3.10+ instalado. El código del agente generado es Python.

  • AWS CDK instalado. La CLI usa la AWS CDK para implementar recursos. Para obtener más información, consulte Introducción al AWS CDK.

  • AWS Permisos: para crear e implementar un agente con la AgentCore CLI, debe tener los permisos adecuados. Para obtener más información, consulte Uso de la AgentCore CLI.

  • Acceso al modelo: Anthropic Claude Sonnet 4.0 habilitado en la consola de Amazon Bedrock (si utiliza Bedrock como proveedor de modelos). Para obtener información sobre el uso de un modelo diferente con Strands Agents, consulte la sección de proveedores de modelos en la documentación del SDK de Strands Agents.

Paso 1: Instalar la AgentCore CLI

Instale la AgentCore CLI globalmente:

npm install -g @aws/agentcore

Verificar la instalación:

agentcore --help

Debería ver una salida similar a esta:

Usage: agentcore [options] [command]

Build and deploy Agentic AI applications on AgentCore

Options:
  -V, --version                output the version number
  -h, --help                   Display help

Commands:
  add [subcommand]             Add resources (agent, evaluator, online-eval,
                               memory, identity, target)
  dev|d [options]              Launch local development server with hot-reload.
  deploy|p [options]           Deploy project infrastructure to AWS via CDK.
  create [options]             Create a new AgentCore project
  evals                        View past eval run results.
  fetch                        Fetch access info for deployed resources.
  help                         Display help topics
  invoke|i [options] [prompt]  Invoke a deployed agent endpoint.
  logs|l [options]             Stream or search agent runtime logs.
  package|pkg [options]        Package agent artifacts without deploying.
  pause                        Pause an online eval config.
  remove [subcommand]          Remove resources from project config.
  resume                       Resume a paused online eval config.
  run                          Run on-demand evaluation.
  status|s [options]           Show deployed resource details and status.
  traces|t                     View and download agent traces.
  update [options]             Check for and install CLI updates
  validate [options]           Validate agentcore/ config files.

Paso 2: Cree su proyecto de agente

Usa el agentcore create comando para organizar un nuevo proyecto de agente:

ejemplo
AgentCore CLI

  1. Pase las banderas directamente para crear un proyecto de forma no interactiva:

    agentcore create --name MyAgent --framework Strands --protocol HTTP --model-provider Bedrock --memory none

    Para aceptar todos los valores predeterminados (Python, Strands, Bedrock, sin memoria), usa la --defaults bandera:

    agentcore create --name MyAgent --defaults
Interactive

  1. Ejecuta agentcore create sin banderas para iniciar el asistente interactivo:

    agentcore create

  2. Introduzca el nombre de su proyecto:

    Asistente de creación: introduzca el nombre del proyecto

  3. Elija su estructura de agentes y su proveedor de modelos:

    Asistente de creación: seleccione el marco

  4. Revise la configuración y confirme:

    Asistente de creación: revise y confirme

El agentcore create comando acepta los siguientes indicadores:

  • --name— El nombre del proyecto (alfanumérico, comienza con una letra, máximo 36 caracteres).

  • --framework— El marco de agentes. Valores admitidos:Strands,LangChain_LangGraph,GoogleADK,OpenAIAgents.

  • --protocol— El modo de protocolo. Valores admitidos: HTTP (predeterminado),MCP,A2A.

  • --build— El tipo de construcción. Valores admitidos: CodeZip (por defecto),Container.

  • --model-provider— El proveedor del modelo. Valores admitidos:Bedrock,Anthropic,OpenAI,Gemini.

  • --memory— Configuración de memoria. Valores admitidos:none,shortTerm,longAndShortTerm.

El comando genera un directorio de proyectos con la siguiente estructura:

MyAgent/
  agentcore/
    agentcore.json        # Project and agent configuration
    aws-targets.json      # AWS account and region targets
    .env.local            # Local environment variables (gitignored)
  app/
    MyAgent/
      main.py             # Agent entrypoint
      pyproject.toml      # Python dependencies
  README.md

El agentcore/agentcore.json archivo contiene la configuración del proyecto y del agente. El app/MyAgent/main.py archivo contiene el código de agente inicial que utiliza el marco seleccionado.

Para añadir capacidades de pago a tu proyecto, ejecuta:

agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00
agentcore add payment-connector --manager MyPayments --name MyConnector --provider CoinbaseCDP \
  --api-key-id <KEY_ID> --api-key-secret <KEY_SECRET> --wallet-secret <WALLET_SECRET>

Esto configura la infraestructura de pago AgentCorePaymentsPlugin de su agente y aprovisiona al desplegarla. Consulta la página de inicio rápido de Payments para ver todo el flujo de trabajo.

Paso 3: Pon a prueba a tu agente a nivel local

Antes de realizar la implementación AWS, pruebe el agente de forma local mediante el servidor de desarrollo. Primero, vaya al directorio del proyecto:

cd MyAgent

Si seleccionó un proveedor de modelos que requiere una clave de API (OpenAI, Anthropic o Gemini), asegúrese de que la clave esté configurada en. agentcore/.env.local

Inicie el servidor de desarrollo local:

ejemplo
AgentCore CLI

  1. agentcore dev
Interactive

  1. Ejecute agentcore para abrir la pantalla de inicio de TUI y, a continuación, seleccione dev para iniciar el servidor de desarrollo local:

    agentcore
    AgentCore agente inspector con mensaje de chat

El agentcore dev comando:

  • Abre el inspector de agentes en su navegador web

  • Crea automáticamente un entorno virtual de Python e instala dependencias

  • Inicia un servidor local que imita el entorno de ejecución AgentCore

  • Se ejecuta de forma http://localhost:8080 predeterminada (se usa -p para cambiar el puerto)

Para ver los registros del servidor en tiempo real (modo no interactivo), utilice el --logs indicador:

agentcore dev --logs

En una terminal independiente, invoca a tu agente local:

agentcore dev "Hello, tell me a joke"

Al pasar un mensaje, se envía al servidor de desarrollo local en ejecución. Se usa --stream para ver la respuesta transmitida en tiempo real.

Paso 4: Habilite la observabilidad para su agente

Amazon Bedrock AgentCore Observability le ayuda a rastrear, depurar y supervisar los agentes que aloja en Amazon Bedrock Runtime. AgentCore En primer lugar, active la búsqueda de CloudWatch transacciones siguiendo las instrucciones de Habilitar la observabilidad en tiempo de AgentCore ejecución de Amazon Bedrock. Para observar a su agente, consulte Ver datos de observabilidad de sus agentes de Amazon Bedrock AgentCore .

Después de implementar el agente, puede usar la AgentCore CLI para transmitir los registros y ver los seguimientos:

# Stream agent logs
agentcore logs

# List recent traces
agentcore traces list

Paso 5: Implemente en Amazon Bedrock Runtime AgentCore

Implemente su agente en Amazon Bedrock AgentCore Runtime:

ejemplo
AgentCore CLI

  1. agentcore deploy
Interactive

  1. Ejecute agentcore deploy para iniciar la implementación. La CLI muestra el progreso de la implementación a medida que crea e implementa el proyecto:

    agentcore deploy
    Progreso de la implementación: creación CloudFormation de recursos y estado de implementación

Para obtener una vista previa del despliegue sin realizar cambios, utilice el --dry-run indicador:

agentcore deploy --dry-run

El agentcore deploy comando:

  • Lee tu agentcore/aws-targets.json configuración agentcore/agentcore.json y

  • Empaqueta el código del agente (como un CodeZip archivo o un contenedor de Docker, según el tipo de compilación)

  • Usa el AWS CDK para sintetizar e implementar recursos CloudFormation

  • Crea los AWS recursos necesarios (funciones de IAM, Amazon Bedrock AgentCore Runtime, etc.)

-vUtilícelo para obtener un resultado detallado que muestre los eventos de implementación a nivel de recursos. Se utiliza -y para confirmar automáticamente la implementación sin un aviso.

Si se produce un error en la implementación, compruebe si hay problemas comunes.

Paso 6: Pruebe el agente desplegado

Una vez completada la implementación, invoque al agente desplegado:

ejemplo
AgentCore CLI

  1. agentcore invoke "Tell me a joke"

    También puede transmitir la solicitud con el --prompt indicador, especificar un tiempo de ejecución o transmitir la respuesta en tiempo real con--stream: --runtime

    agentcore invoke --prompt "Tell me a joke" --stream

    Para mantener una conversación a través de múltiples invocaciones, usa el --session-id indicador:

    agentcore invoke --session-id my-session "What else can you tell me?"

    Si su agente ha configurado los pagos, proporcione el contexto de pago:

    agentcore invoke \
  --prompt "Access https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id user@example.com
Interactive

  1. Ejecute agentcore para abrir la pantalla de inicio de TUI y, a continuación, seleccione la opción de invocación para charlar con el agente desplegado:

    agentcore
    Invoca la pantalla TUI que muestra la interfaz de chat

Si ve un chiste en la respuesta, significa que su agente está trabajando en Amazon Bedrock AgentCore Runtime y puede invocarlo. Si no es así, compruebe si hay problemas comunes.

Paso 7: invoque al agente desplegado

ejemplo
AgentCore CLI

  1. Invoca al agente desplegado con un mensaje:

    agentcore invoke --runtime MyAgent "Hello, what can you do?"

    Transmita la respuesta en tiempo real:

    agentcore invoke --runtime MyAgent "Tell me a joke" --stream

    Abre la TUI del chat interactivo agentcore invoke sin que te lo pida, que transmite las respuestas de forma predeterminada y mantiene la sesión automáticamente.

AWS Python SDK (Boto3)

  1. También puede invocar al agente mediante la operación del AWS SDK InvokeAgentRuntime. Para obtener el ARN del agente desplegado, utilice el agentcore status comando:

    agentcore status

    Usa el siguiente código boto3 (AWS SDK para Python) para invocar a tu agente. Agent ARNSustitúyalo por el ARN de su agente. Asegúrese de tener bedrock-agentcore:InvokeAgentRuntime permisos. Cree un archivo con el nombre invoke_agent.py y añada el siguiente código:

    import json
import uuid
import boto3

agent_arn = "Agent ARN"
prompt = "Tell me a joke"

# Initialize the Amazon Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore')

# Prepare the payload
payload = json.dumps({"prompt": prompt}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=payload,
    qualifier="DEFAULT"
)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode('utf-8'))
print(json.loads(''.join(content)))

    Abre una ventana de terminal y ejecuta el código con el siguiente comando:

    python invoke_agent.py

    Si tiene éxito, debería ver un chiste en la respuesta. Si se produce un error en la llamada, consulta los registros agentcore logs o búscalos en Amazon CloudWatch.

    nota

    Si planeas integrar tu agente con OAuth, no puedes usar el AWS SDK para llamar. InvokeAgentRuntime En su lugar, haz una solicitud HTTPS a. InvokeAgentRuntime Para obtener más información, consulta Autenticar y autorizar con autenticación entrante y autenticación saliente.

Paso 8: Eliminación

Si ya no desea alojar el agente en Amazon Bedrock AgentCore Runtime, elimine los AWS recursos desplegados. En primer lugar, elimine todos los recursos de la configuración local:

ejemplo
AgentCore CLI

  1. agentcore remove all
Interactive

  1. Ejecute agentcore para abrir la pantalla de inicio de la TUI y, a continuación, seleccione la opción de eliminar para elegir los recursos que desea eliminar:

    agentcore
    Eliminar la selección de recursos (TUI)

A continuación, vuelva a desplegarlos para reducir los AWS recursos:

ejemplo
AgentCore CLI

  1. agentcore deploy
Interactive

  1. En la pantalla de inicio de la AgentCore CLI, seleccione deploy aplicar los AWS recursos de eliminación y desmontaje:

    Progreso de la implementación: CloudFormation estado de eliminación y desmontaje de los recursos

El remove all comando restablece el archivo de agentcore/agentcore.json configuración agentcore/aws-targets.json y, al mismo tiempo, conserva el estado de despliegue. Lo siguiente deploy detecta los recursos eliminados y elimina los AWS recursos correspondientes.

Encuentre sus recursos

Tras la implementación, puede comprobar el estado de los recursos mediante la AgentCore CLI:

ejemplo
AgentCore CLI

  1. agentcore status
Interactive

  1. Ejecute agentcore y seleccione status para ver un panel en vivo de todos los recursos implementados:

    agentcore
    AgentCore Panel de estado CLI TUI

También puede ver sus recursos en la AWS consola:

Recurso Ubicación

Registros de agentes

CloudWatch → Grupos de registros → /aws/bedrock-agentcore/runtimes/{agent-id}-DEFAULT

CloudFormation Pila

CloudFormation → Stacks → busca el nombre de tu proyecto

IAM Role

IAM → Funciones → Busque "» BedrockAgentCore

S3 Assets () CodeZip

S3 → Cubos → Depósito de almacenamiento CDK

Problemas y soluciones comunes de

Problemas y soluciones comunes al empezar con la AgentCore CLI. Para obtener más información sobre solución de problemas, consulte Solución de problemas de Amazon Bedrock Runtime AgentCore .

Errores de permiso denegado

Compruebe sus AWS credenciales y permisos:

  • Verifica AWS las credenciales: aws sts get-caller-identity

  • Compruebe que tiene adjuntas las políticas requeridas

  • Revisa la política de permisos de las personas que llaman para conocer los requisitos detallados

Acceso al modelo denegado

Habilite el acceso al modelo en la consola de Bedrock:

  • Habilite Anthropic Claude 4.0 en la consola de Bedrock

  • Asegúrate de estar en la AWS región correcta (us-west-2 de forma predeterminada)

Errores de despliegue del CDK

Compruebe la configuración y los permisos del CDK:

  • Asegúrese de haber iniciado su AWS cuenta para el CDK: cdk bootstrap

  • Verifica que los permisos de la persona que llama incluyan el acceso al CDK CloudFormation

  • Utilícelo como salida detallada agentcore deploy -v para identificar el recurso que falla

El puerto 8080 está en uso (solo local)

Busque y detenga los procesos que utilizan el puerto 8080:

Se utiliza lsof -ti:8080 para obtener una lista de procesos mediante el puerto 8080.

Se utiliza kill -9 PID para detener el proceso. PIDSustitúyalo por el identificador del proceso.

Como alternativa, inicie el servidor de desarrollo en un puerto diferente: agentcore dev -p 3000

Discrepancia entre regiones

Verifica la AWS región aws configure get region y asegúrate de que agentcore/aws-targets.json coincide con la región en la que deberían desplegarse tus recursos.

Errores de validación de la configuración

Valide sus archivos de configuración:

Se utiliza agentcore validate para comprobar si hay errores de sintaxis o de esquema en los archivos de configuración agentcore/agentcore.json y los archivos de configuración relacionados.

Opciones avanzadas (opcional)

Después de crear su proyecto de agente conagentcore create, puede ampliarlo mediante los agentcore add comandos. Para obtener la referencia completa de la CLI, consulte la documentación de la AgentCore CLI.

Tipos de compilación

Al crear tu proyecto, elige un tipo de construcción que se adapte a tus necesidades:

CodeZip (predeterminado)

El código de agente se empaqueta en un archivo zip y se carga en S3. Esta es la opción más sencilla y no requiere Docker:

agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build CodeZip
Contenedor

El código de su agente está empaquetado como una imagen de contenedor de Docker. Utilice esta opción cuando necesite dependencias personalizadas a nivel de sistema o una imagen base específica:

agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build Container

Añada recursos a su proyecto

Puedes añadir recursos adicionales a tu proyecto después de crearlo:

# Add another agent to the same project
agentcore add agent --name SecondAgent --language Python --framework Strands --model-provider Bedrock

# Add a memory store for conversational context
agentcore add memory --name MyMemory --strategies SEMANTIC

# Add an API key credential for external services
agentcore add credential --name MyApiKey --type api-key --api-key your-api-key

# Add a payment manager for x402 microtransactions
agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00

Tras añadir los recursos, ejecuta agentcore deploy para aprovisionar los nuevos recursos AWS.

¿Por qué ARM64?

Amazon Bedrock AgentCore Runtime se ejecuta en ARM64 (AWS Graviton). La AgentCore CLI gestiona la compatibilidad de la arquitectura automáticamente tanto para el CodeZip tipo de compilación como para el de contenedor. En el caso de las compilaciones de contenedores, solo las imágenes creadas para ARM64 funcionarán cuando se desplieguen en Amazon Bedrock Runtime AgentCore .