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.
Despliegue directo de código para Node.js
Con la implementación directa de código, usted empaqueta su Node.js el código del agente y sus dependencias en un archivo .zip y lo implementa en AgentCore Tiempo de ejecución. Tu agente aún tiene que seguirte AgentCore Requisitos de tiempo de ejecución : tener un punto de entrada .js archivo que implementa /invocations POST y /ping Puntos finales de servidor GET.
Puede incluir las dependencias según el proveedor node_modules/ en tu ZIP o como un sencillo incluido en esbuild .js archivo.
Requisitos previos
Antes de comenzar, asegúrese de que dispone de lo siguiente:
-
AWS Cuenta con las credenciales configuradas. Para configurar su AWS credenciales, consulte Los ajustes del archivo de configuración y credenciales en el AWS CLI.
-
Node.js
y npm instalado. Te recomendamos instalar la misma versión principal en la que planeas implementarla AgentCore Runtime (por ejemplo, Node.js 22 para el NODE_22tiempo de ejecución). Para ver las versiones compatibles, consulte Tiempos de ejecución en los idiomas compatibles. -
AWS Permisos : Para crear e implementar un agente, debe tener los permisos adecuados. Para obtener más información, consulte AgentCore Permisos de ejecución.
-
Acceso modelo : 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.
Paso 1: configurar el proyecto e instalar las dependencias
Inicializa tu proyecto con los siguientes comandos:
mkdir agentcore_runtime_node_deploy cd agentcore_runtime_node_deploy npm init -y
Si lo desea, ejecute npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation para habilitar Amazon Bedrock AgentCore rastros de observabilidad.
Paso 2: Crea tu código de agente
Crea tu punto de entrada para agentes. Su agente debe implementar el AgentCore Contrato HTTP en tiempo de ejecución con un /ping Punto final GET Health y /invocations Controlador POST.
ejemplo
Paso 3: Probar localmente
Asegúrese de que el puerto 8080 esté libre antes de comenzar.
Abra una ventana de terminal e inicie su agente:
ejemplo
Paso 4: Habilite la observabilidad para su agente
Amazon Bedrock AgentCore Observabilidad le ayuda a rastrear, depurar y supervisar los agentes que aloja AgentCore Tiempo de ejecución. Primero, habilita CloudWatch Busque transacciones siguiendo las instrucciones que se encuentran en Habilitar Amazon Bedrock AgentCore observabilidad en tiempo de ejecución . Para observar a su agente, consulte Consulte los datos de observabilidad de su Amazon Bedrock AgentCore agentes.
Para habilitar la instrumentación automática para su Node.js agente, añada el paquete ADOT:
npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
La autoinstrumentación de ADOT funciona mediante parches Node.js require() llamadas en tiempo de ejecución. Esto significa que solo es compatible con la salida del módulo CommonJS. Si compilas TypeScript con --module nodenext o --module esnext (produciendo ESM import declaraciones), la instrumentación de ADOT falla silenciosamente y no se emiten rastros. Para usar ADOT, compile con --module commonjs o usa esbuild con --platform=node (que conserva require() pide Node.js módulos integrados).
Al realizar la implementación, incluya node_modules/ en su ZIP y utilice el opentelemetry-instrument prefijo en su punto de entrada (consulte el paso 5).
Paso 5: Despliegue en AgentCore Ejecutar e invocar
AgentCore El tiempo de ejecución no se ejecuta TypeScript (.ts) archivos de forma nativa. Debes transpilar TypeScript a JavaScript antes de la implementación. Para obtener más información, consulte Trabajando con TypeScript .
Cree un archivo.zip con el código de su agente y sus dependencias. AgentCore Runtime solo admite arm64 arquitectura del conjunto de instrucciones: asegúrese de que todos los módulos sean nativos (.node (archivos) están compilados para arm64.
ejemplo
-
El tamaño máximo de un paquete de implementación .zip para AgentCore El tiempo de ejecución es de 250 MB (comprimido) y 750 MB (descomprimido). Este límite se aplica al tamaño combinado de todos los archivos que subas.
-
El AgentCore Runtime necesita permiso para leer los archivos de su paquete de implementación. En la notación octal de los permisos de Linux, AgentCore Runtime necesita 644 permisos para los archivos no ejecutables (rw-r—r--) y 755 permisos (rwxr-xr-x) para los directorios y los archivos ejecutables.
-
En Linux y macOS, utilice el comando
chmodpara cambiar los permisos de los archivos y directorios del paquete de implementación. Por ejemplo, para conceder los permisos correctos a un archivo no ejecutable, ejecute el siguiente comando:chmod 644 <filepath>. Para cambiar los permisos de los archivos en Windows, consulte Set, View, Change, or Remove Permissions on an Objecten la documentación de Microsoft Windows. -
Si no concedes AgentCore Ejecute los permisos que necesita para acceder a los directorios de su paquete de implementación, AgentCore Runtime establece los permisos de esos directorios en 755 (rwxr-xr-x).
-
Un archivo ZIP que contiene Linux arm64 las dependencias deben cargarse a S3 como requisito previo para crear Agent Runtime. El siguiente código requiere que el bucket de S3 especificado ya exista. Para crear un bucket, consulte Crear un bucket de uso general en la guía del usuario de Amazon S3. Lo siguiente TypeScript el código cargará el archivo .zip en S3 y creará un Amazon Bedrock AgentCore tiempo de ejecución.
import { readFileSync } from "node:fs"; import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3"; import { BedrockAgentCoreControlClient, CreateAgentRuntimeCommand, } from "@aws-sdk/client-bedrock-agentcore-control"; const accountId = "your-aws-account-id"; const agentName = "nodejs_agent"; const region = "us-west-2"; const bucketName = `bedrock-agentcore-code-${accountId}-${region}`; const s3Client = new S3Client({ region }); console.log("Uploading deployment_package.zip to S3..."); await s3Client.send(new PutObjectCommand({ Bucket: bucketName, Key: `${agentName}/deployment_package.zip`, Body: readFileSync("deployment_package.zip"), ExpectedBucketOwner: accountId, })); console.log(`Upload completed. S3 location: s3://${bucketName}/${agentName}/deployment_package.zip`); const controlClient = new BedrockAgentCoreControlClient({ region }); const response = await controlClient.send(new CreateAgentRuntimeCommand({ agentRuntimeName: agentName, agentRuntimeArtifact: { codeConfiguration: { code: { s3: { bucket: bucketName, prefix: `${agentName}/deployment_package.zip`, }, }, runtime: "NODE_22", entryPoint: ["dist/app.js"], }, }, networkConfiguration: { networkMode: "PUBLIC" }, roleArn: `arn:aws:iam::${accountId}:role/AmazonBedrockAgentCoreSDKRuntime-${region}`, lifecycleConfiguration: { idleRuntimeSessionTimeout: 300, maxLifetime: 1800, }, })); console.log(`Agent Runtime created successfully!`); console.log(`Agent Runtime ARN: ${response.agentRuntimeArn}`); console.log(`Status: ${response.status}`);
Para habilitar la instrumentación automática de OTEL, incluya node_modules/@aws/aws-distro-opentelemetry-node-autoinstrumentation/ en su ZIP y utilice el opentelemetry-instrument prefijo en el punto de entrada:
entryPoint: ["opentelemetry-instrument", "dist/app.js"],
Para invocar a un agente en Amazon Bedrock AgentCore En tiempo de ejecución mediante programación, consulte Invoca un AgentCore Agente de ejecución con el AWS SDK.
Paso 6: Detener la sesión, actualizar o limpiar
Siguiendo TypeScript el código actualizará un AgentCore Tiempo de ejecución. Cargue el nuevo paquete de implementación en S3 y, a continuación, llame UpdateAgentRuntimeCommand :
import { readFileSync } from "node:fs"; import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3"; import { BedrockAgentCoreControlClient, UpdateAgentRuntimeCommand, } from "@aws-sdk/client-bedrock-agentcore-control"; const accountId = "your-aws-account-id"; const agentName = "nodejs_agent"; const region = "us-west-2"; const bucketName = `bedrock-agentcore-code-${accountId}-${region}`; const s3Client = new S3Client({ region }); console.log("Uploading deployment_package.zip to S3..."); await s3Client.send(new PutObjectCommand({ Bucket: bucketName, Key: `${agentName}/deployment_package.zip`, Body: readFileSync("deployment_package.zip"), ExpectedBucketOwner: accountId, })); console.log("Upload completed successfully!"); const controlClient = new BedrockAgentCoreControlClient({ region }); const response = await controlClient.send(new UpdateAgentRuntimeCommand({ agentRuntimeId: "<your-agent-runtime-id>", agentRuntimeArtifact: { codeConfiguration: { code: { s3: { bucket: bucketName, prefix: `${agentName}/deployment_package.zip`, }, }, runtime: "NODE_22", entryPoint: ["dist/app.js"], }, }, networkConfiguration: { networkMode: "PUBLIC" }, roleArn: `arn:aws:iam::${accountId}:role/AmazonBedrockAgentCoreSDKRuntime-${region}`, })); console.log(`Agent Runtime updated successfully!`); console.log(`Agent Runtime ARN: ${response.agentRuntimeArn}`); console.log(`Status: ${response.status}`);
Para detener la sesión en ejecución antes de la configurable IdleRuntimeSessionTimeout (el valor predeterminado es de 15 minutos) y ahorrar en cualquier posible coste adicional, utilice el siguiente código:
import { BedrockAgentCoreClient, StopRuntimeSessionCommand, } from "@aws-sdk/client-bedrock-agentcore"; const region = "us-west-2"; const dataClient = new BedrockAgentCoreClient({ region }); const response = await dataClient.send(new StopRuntimeSessionCommand({ agentRuntimeArn: "arn:aws:bedrock-agentcore:us-west-2:<account-id>:runtime/<agent-runtime-id>", runtimeSessionId: "<your-session-id>", qualifier: "DEFAULT", })); console.log("Session stopped successfully!");
Siguiendo TypeScript el código eliminará un Amazon Bedrock AgentCore el tiempo de ejecución y el archivo de archivo.zip en S3.
import { S3Client, DeleteObjectCommand } from "@aws-sdk/client-s3"; import { BedrockAgentCoreControlClient, DeleteAgentRuntimeCommand, } from "@aws-sdk/client-bedrock-agentcore-control"; const accountId = "your-aws-account-id"; const agentName = "nodejs_agent"; const region = "us-west-2"; const bucketName = `bedrock-agentcore-code-${accountId}-${region}`; const controlClient = new BedrockAgentCoreControlClient({ region }); console.log("Deleting Agent from Amazon Bedrock AgentCore Runtime!"); const response = await controlClient.send(new DeleteAgentRuntimeCommand({ agentRuntimeId: "<your-agent-runtime-id>", })); console.log(`Agent Runtime deleted successfully!`); console.log(`Status: ${response.status}`); const s3Client = new S3Client({ region }); console.log("Deleting deployment archive from S3..."); await s3Client.send(new DeleteObjectCommand({ Bucket: bucketName, Key: `${agentName}/deployment_package.zip`, ExpectedBucketOwner: accountId, })); console.log("Archive deleted successfully from S3!");
Node.js-specific conceptos para la implementación directa de código
Obtenga más información sobre Node.js-specific conceptos sobre el uso de la implementación directa de código con Amazon Bedrock AgentCore Tiempo de ejecución.
Temas
AgentCore Tiempo de ejecución para Node.js solo acepta .js puntos de entrada. TypeScript archivos (.ts) no se aceptan directamente; debes transpilarlos a JavaScript antes del embalaje. Recomendamos usar esbuildnpm install -D esbuild .
Los puntos de entrada pueden estar en subdirectorios. Por ejemplo, src/app.js o dist/index.js son puntos de entrada válidos. Node.js la resolución del módulo recorre el árbol de directorios desde la ubicación del punto de entrada, por lo que las dependencias en node_modules/ en la raíz de su ZIP se encuentran automáticamente, no NODE_PATH es necesaria la configuración.
Al especificar un punto de entrada de subdirectorio, asegúrese de que la ruta esté en su entryPoint la configuración coincide con la ruta del archivo ZIP.
Hay dos enfoques para empaquetar las dependencias para Node.js agentes:
Dependencias de proveedores (las más simples):
Incluir node_modules/ directamente en tu código postal junto a tu punto de entrada:
npm install --production zip -r my-agent.zip app.js node_modules/ package.json
Esto produce un ZIP con la siguiente estructura:
my-agent.zip ├── app.js ├── package.json └── node_modules/
Incluido con esbuild (el ZIP más pequeño):
Utilice esbuild
npx esbuild app.js --bundle --platform=node --target=node22 --outfile=bundle.js zip my-agent.zip bundle.js
Esto produce un ZIP mínimo:
my-agent.zip └── bundle.js
Ambos enfoques funcionan. Las implementaciones agrupadas suelen tener menos de 10 MB y se implementan más rápido. Las implementaciones de los proveedores son más sencillas y no requieren un paso de creación, pero pueden ser más grandes.
AgentCore Runtime solo es compatible con arm64 arquitectura del conjunto de instrucciones. Si su agente usa paquetes npm que incluyen módulos nativos (compilados) .node o .so archivos), esos archivos binarios deben compilarse para Linux arm64.
AgentCore El tiempo de ejecución valida la arquitectura de todos .node y .so archivos de su paquete de despliegue leyendo sus encabezados ELF. Si se compila algún binario para una arquitectura diferente (como x86_64 o macOS), la creación del agente fallará y mostrará el estado CREATE_FAILED .
Para instalar módulos nativos compatibles con arm64:
-
Instale las dependencias en una máquina arm64 (como una AWS Graviton-based (instancia Amazon EC2)
-
Usa npm
--archy--platformbanderas:npm install --arch=arm64 --platform=linux -
Usa esbuild para empaquetar tu código si puedes evitar el módulo nativo en tiempo de ejecución
Los paquetes npm más populares (Express, Axios, Fastify, Hono, ws) son puros JavaScript y no contienen módulos nativos.
AgentCore El tiempo de ejecución no se ejecuta TypeScript archivos directamente. Debe compilar su TypeScript código fuente para JavaScript antes de la implementación. Este es el mismo patrón usado por AWS Lambda.
Usando el TypeScript compilador (tsc):
npm install -g typescript npx tsc --init --target ES2022 --module commonjs --outDir ./dist npx tsc
Luego empaqueta la salida compilada:
cd dist zip -r ../deployment_package.zip .
Al crear el agente, defina como punto de entrada el compilado .js archivo (por ejemplo, app.js o dist/app.js dependiendo de su estructura ZIP).
Uso de esbuild (recomendado para empaques más sencillos):
npx esbuild app.ts --bundle --platform=node --target=node22 --outfile=app.js zip deployment_package.zip app.js
esbuild compila TypeScript y agrupa las dependencias en un solo paso, produciendo una pequeña e independiente .js archivo.
Si tu package.json incluye un engines.node campo, AgentCore El tiempo de ejecución valida que el rango especificado es compatible con Node.js la versión que seleccionó (por ejemplo, Node.js 22 cuando se usa el NODE_22 tiempo de ejecución). Si el rango excluye esa versión, la creación del agente fallará y mostrará el estado CREATE_FAILED .
Por ejemplo, lo siguiente engines las declaraciones son compatibles con Node.js 22:
{ "engines": { "node": ">=18" } } { "engines": { "node": ">=14 <18 || >=20" } } { "engines": { "node": "22" } }
Las siguientes declaraciones son incompatibles y provocarán un error en la creación del agente:
{ "engines": { "node": "<18" } } { "engines": { "node": ">=14 <18" } }
AgentCore Runtime también comprueba el engines.node campo para las dependencias comunes en su node_modules/ . Si alguno de estos declara un Node.js el rango de versiones que excluye la versión en tiempo de ejecución de destino, no se podrá crear el agente.
Si encuentra un engines.node incompatibilidad, actualice el paquete a una versión que sea compatible con su objetivo Node.js versión o eliminar la engines campo de tu package.json . Para soporte Node.js versiones, consulte Tiempos de ejecución en idiomas compatibles.