Despliegue directo de código para Node.js

La implementación directa de código le permite llevar su Node.js-based agente a Amazon Bedrock AgentCore Runtime simplemente empaquetando el código del agente y sus dependencias en un archivo zip. Su agente aún debe cumplir con los requisitos de AgentCore tiempo de ejecución: tener un .js archivo de punto de entrada que implemente los puntos de enlace de los servidores /invocations POST y GET. /ping

Puedes incluir las dependencias tal y como están distribuidas node_modules/ en tu ZIP o como un archivo único incluido en esbuild. .js

Requisitos previos

Antes de comenzar, asegúrese de que dispone de lo siguiente:

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, ejecútelo npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation para habilitar los rastreos de AgentCore observabilidad de Amazon Bedrock.

Paso 2: Crea tu código de agente

Crea tu punto de entrada para agentes. Su agente debe implementar el contrato HTTP AgentCore de Runtime con un terminal /ping GET Health y un controlador /invocations POST.

Paso 3: Probar localmente

Asegúrese de que el puerto 8080 esté libre antes de comenzar. Consulte Solucionar problemas si el puerto ya está en uso.

Abra una ventana de terminal e inicie su agente:

Paso 4: Habilite la observabilidad para su agente

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

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

Al realizar la implementación, node_modules/ inclúyala en su ZIP y utilice el opentelemetry-instrument prefijo en su punto de entrada (consulte el paso 5).

Paso 5: Despliegue en AgentCore Runtime e invoque

Cree un archivo.zip con el código de su agente y sus dependencias. AgentCore Runtime solo admite la arquitectura del conjunto de instrucciones arm64; asegúrese de que todos los módulos (.nodearchivos) nativos estén compilados para arm64.

Como requisito previo para crear Agent Runtime, es necesario subir a S3 un archivo ZIP que contenga las dependencias de arm64 de Linux. El código siguiente requiere que el bucket de S3 especificado ya exista. Siga la AWS documentación que aparece aquí para crear un bucket. El siguiente TypeScript código cargará el archivo .zip en S3 y creará un entorno de ejecución de Amazon Bedrock AgentCore .

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 autoinstrumentación de OTEL, inclúyala node_modules/@aws/aws-distro-opentelemetry-node-autoinstrumentation/ en su ZIP y utilice el opentelemetry-instrument prefijo del punto de entrada:

entryPoint: ["opentelemetry-instrument", "dist/app.js"],

Para invocar un agente en Amazon Bedrock AgentCore Runtime mediante programación, consulte Invocar un agente mediante programación. Invoca un agente mediante programación

Paso 6: Detenga la sesión, actualice o limpie

TypeScript El siguiente código actualizará un AgentCore Runtime. Suba el nuevo paquete de implementación a S3 y, a continuación, llame aUpdateAgentRuntimeCommand:

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 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!");

TypeScript El siguiente código eliminará el tiempo de AgentCore ejecución de Amazon Bedrock y el archivo archivador.zip de 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 los conceptos relacionados con el uso de la implementación directa de código con Amazon Bedrock AgentCore Runtime.

npm install --production
zip -r my-agent.zip app.js node_modules/ package.json

my-agent.zip
├── app.js
├── package.json
└── node_modules/

npx esbuild app.js --bundle --platform=node --target=node22 --outfile=bundle.js
zip my-agent.zip bundle.js

my-agent.zip
└── bundle.js

npm install -g typescript
npx tsc --init --target ES2022 --module commonjs --outDir ./dist
npx tsc

cd dist
zip -r ../deployment_package.zip .

npx esbuild app.ts --bundle --platform=node --target=node22 --outfile=app.js
zip deployment_package.zip app.js

{ "engines": { "node": ">=18" } }
{ "engines": { "node": ">=14 <18 || >=20" } }
{ "engines": { "node": "22" } }

{ "engines": { "node": "<18" } }
{ "engines": { "node": ">=14 <18" } }