Despliegue directo de código para Node.js

La implementación directa del código le permite llevar a 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 vienen node_modules/ en tu ZIP o como un único archivo empaquetado con esbuild. .js

Requisitos previos

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

Paso 1: Configurar el proyecto e instalar las dependencias

Inicialice su 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 los rastreos de AgentCore observabilidad de Amazon Bedrock.

Paso 2: Crea tu código de agente

Crea el punto de entrada de tu agente. Su agente debe implementar el contrato HTTP en tiempo de AgentCore ejecución 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 el puerto 8080 en uso (solo local) en Problemas y soluciones comunes.

Abre una ventana de terminal e inicia tu 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, 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 .

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úyelo en el ZIP y usa el opentelemetry-instrument prefijo en el punto de entrada (consulta el paso 5).

Paso 5: Implemente en AgentCore Runtime e invoque

Cree un archivo.zip con el código de agente y las dependencias. AgentCore El tiempo de ejecución solo es compatible con la arquitectura de conjuntos de instrucciones arm64; asegúrese de que todos los módulos (.nodearchivos) nativos estén compilados para arm64.

Es necesario cargar en S3 un archivo ZIP que contenga las dependencias arm64 de Linux como requisito previo para crear Agent Runtime. El siguiente código requiere que el bucket de S3 especificado ya exista. Siga la AWS documentación que se indica aquí para crear un depósito. 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 instrumentación automática de OTEL, node_modules/@aws/aws-distro-opentelemetry-node-autoinstrumentation/ inclúyalo en su código postal y utilice el opentelemetry-instrument prefijo en el punto de entrada:

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

Para invocar un agente en el entorno de AgentCore ejecución de Amazon Bedrock mediante programación, consulte: Invocar un agente mediante programación

Paso 6: Detener la sesión, actualizarla o limpiarla

TypeScript El siguiente código actualizará un AgentCore tiempo de ejecución. Cargue el nuevo paquete de implementación en 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 sesión configurable IdleRuntimeSessionTimeout (el valor predeterminado es de 15 minutos) y ahorrar en posibles costes excesivos, 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á un entorno de AgentCore ejecución de Amazon Bedrock y el archivo de archivo.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 el despliegue directo de código

Obtenga información sobre Node.js-specific los conceptos relacionados con 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" } }