Prasyarat Langkah 1: Siapkan proyek dan instal dependensi Langkah 2: Buat kode agen Anda Langkah 3: Uji secara lokal Langkah 4: Aktifkan observabilitas untuk agen Anda Langkah 5: Terapkan ke AgentCore Runtime dan panggil Langkah 6: Hentikan sesi, perbarui, atau pembersihan Node.js-specific konsep untuk penyebaran kode langsung

Penyebaran kode langsung untuk Node.js

Penerapan kode langsung memungkinkan Anda membawa Node.js-based agen Anda ke Amazon Bedrock AgentCore Runtime hanya dengan mengemas kode agen dan dependensinya dalam arsip file.zip. Agen Anda masih harus mengikuti persyaratan AgentCore Runtime: memiliki .js file entrypoint yang mengimplementasikan titik akhir server /invocations POST dan /ping GET.

Anda dapat menyertakan dependensi baik sebagai vendor node_modules/ di ZIP Anda atau sebagai file tunggal yang dibundel esbuild. .js

Prasyarat

Sebelum Anda mulai, pastikan Anda memiliki:

AWS Akun dengan kredensil dikonfigurasi. Untuk mengonfigurasi AWS kredensil Anda, lihat Konfigurasi dan pengaturan file kredenal di CLI. AWS
Node.jsdan npm diinstal. Sebaiknya instal versi utama yang sama yang Anda rencanakan untuk diterapkan di AgentCore Runtime (misalnya, Node.js 22 untuk NODE_22 runtime). Untuk versi yang didukung, lihat Runtime bahasa yang didukung.
AWS Izin: Untuk membuat dan menyebarkan agen, Anda harus memiliki izin yang sesuai. Untuk informasi selengkapnya, lihat AgentCore Izin waktu proses.
Akses model: Anthropic Claude Sonnet 4.0 diaktifkan di konsol Amazon Bedrock. Untuk informasi tentang penggunaan model yang berbeda dengan Agen Strands, lihat bagian Penyedia Model dalam dokumentasi Strands Agents SDK.

Langkah 1: Siapkan proyek dan instal dependensi

Inisialisasi proyek Anda dengan perintah berikut:


mkdir agentcore_runtime_node_deploy
cd agentcore_runtime_node_deploy
npm init -y

Secara opsional, jalankan npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation untuk mengaktifkan jejak AgentCore observabilitas Amazon Bedrock.

Langkah 2: Buat kode agen Anda

Buat titik masuk agen Anda. Agen Anda harus menerapkan kontrak HTTP AgentCore Runtime dengan titik akhir kesehatan /ping GET dan penangan /invocations POST.

contoh

Strands Agents SDK

Instal Strands Agents SDK dan dependensinya:


npm install @strands-agents/sdk express zod
npm install -D @types/express @types/node typescript

Buat file bernamasrc/app.ts:


import express, { Request, Response } from "express";
import { Agent, tool } from "@strands-agents/sdk";
import z from "zod";

const PORT = 8080;
const app = express();

app.use(express.json());

const currentTime = tool({
    name: "current_time",
    description: "Returns the current date and time",
    inputSchema: z.object({}),
    callback: () => {
        return new Date().toISOString();
    },
});

const agent = new Agent({
    tools: [currentTime],
    printer: false,
});

app.get("/ping", (_req: Request, res: Response) => {
    res.json({ status: "Healthy" });
});

app.post("/invocations", async (req: Request, res: Response) => {
    const prompt = req.body?.prompt || "No prompt provided";

    try {
        const result = await agent.invoke(prompt);
        res.json({ result: result.lastMessage });
    } catch (error: unknown) {
        const message = error instanceof Error ? error.message : String(error);
        res.status(500).json({ error: message });
    }
});

app.listen(PORT, "0.0.0.0", () => {
    console.log("Strands agent listening on port " + PORT);
});

Kompilasi TypeScript ke JavaScript:


npx tsc --init --target ES2022 --module commonjs --outDir ./dist
npx tsc

Output yang dikompilasi dist/app.js adalah apa yang Anda terapkan. Saat membuat agen, gunakan "entryPoint": ["dist/app.js"] — JavaScript output yang dikompilasi, bukan .ts sumbernya.

HTTP (no framework)

Contoh ini menggunakan node:http modul bawaan tanpa dependensi eksternal.

Buat file bernamaapp.js:


const http = require("node:http");
const PORT = 8080;

const server = http.createServer((req, res) => {
    if (req.url === "/ping" && req.method === "GET") {
        res.writeHead(200, { "Content-Type": "application/json" });
        res.end(JSON.stringify({ status: "Healthy" }));
    } else if (req.url === "/invocations" && req.method === "POST") {
        let body = "";
        req.on("data", (chunk) => { body += chunk; });
        req.on("end", () => {
            try {
                const input = JSON.parse(body);
                const prompt = input.prompt || input.command || "No prompt provided";
                res.writeHead(200, { "Content-Type": "application/json" });
                res.end(JSON.stringify({
                    result: "Hello from Node.js managed runtime! You said: " + prompt,
                    runtime: "NODE_22",
                    nodeVersion: process.version,
                    timestamp: new Date().toISOString()
                }));
            } catch (e) {
                res.writeHead(200, { "Content-Type": "application/json" });
                res.end(JSON.stringify({
                    result: "Hello from Node.js managed runtime!",
                    runtime: "NODE_22",
                    nodeVersion: process.version,
                    input: body,
                    timestamp: new Date().toISOString()
                }));
            }
        });
    } else {
        res.writeHead(200, { "Content-Type": "application/json" });
        res.end(JSON.stringify({ message: "Node.js managed runtime agent is running" }));
    }
});

server.listen(PORT, "0.0.0.0", () => {
    console.log("Node.js agent listening on port " + PORT);
});

Langkah 3: Uji secara lokal

Pastikan port 8080 gratis sebelum memulai. Lihat Port 8080 yang digunakan (hanya lokal) dalam Masalah dan solusi umum.

Buka jendela terminal dan mulai agen Anda:

contoh

Langkah 4: Aktifkan observabilitas untuk agen Anda

Amazon Bedrock AgentCore Observability membantu Anda melacak, men-debug, dan memantau agen yang Anda host di Runtime. AgentCore Pertama aktifkan Penelusuran CloudWatch Transaksi dengan mengikuti petunjuk di Mengaktifkan observabilitas AgentCore runtime Amazon Bedrock. Untuk mengamati agen Anda, lihat Melihat data observabilitas untuk agen Amazon Bedrock AgentCore Anda.

Untuk mengaktifkan instrumentasi otomatis untuk Node.js agen Anda, tambahkan paket ADOT:


npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation

penting

Instrumentasi otomatis ADOT bekerja dengan menambal Node.js require() panggilan saat runtime. Ini berarti hanya kompatibel dengan output modul CommonJS. Jika Anda mengkompilasi TypeScript dengan --module nodenext atau --module esnext (menghasilkan import pernyataan ESM), instrumentasi ADOT diam-diam gagal dan tidak ada jejak yang dipancarkan. Untuk menggunakan ADOT, kompilasi dengan --module commonjs atau gunakan esbuild with --platform=node (yang mempertahankan require() panggilan untuk Node.js modul bawaan).

Saat menerapkan, sertakan node_modules/ dalam ZIP Anda dan gunakan opentelemetry-instrument awalan di titik masuk Anda (lihat Langkah 5).

Langkah 5: Terapkan ke AgentCore Runtime dan panggil

catatan

AgentCore Runtime tidak menjalankan TypeScript (.ts) file secara native. Anda harus mentranspile JavaScript sebelum TypeScript menerapkan. Untuk detailnya, lihat Bekerja dengan TypeScript.

Buat file.zip dengan kode agen dan dependensi Anda. AgentCore Runtime hanya mendukung arsitektur set instruksi arm64 - pastikan modul asli (.nodefile) dikompilasi untuk arm64.

contoh

catatan

. Ukuran maksimum untuk paket deployment .zip untuk AgentCore Runtime adalah 250 MB (zip) dan 750 MB (unzip). Perhatikan bahwa batas ini berlaku untuk ukuran gabungan semua file yang Anda unggah. AgentCore Runtime memerlukan izin untuk membaca file dalam paket penerapan Anda. Dalam notasi oktal izin Linux, AgentCore Runtime membutuhkan 644 izin untuk file yang tidak dapat dieksekusi (rw-r—r--) dan 755 izin (rwxr-xr-x) untuk direktori dan file yang dapat dieksekusi. Di Linux dan macOS, gunakan chmod perintah untuk mengubah izin file pada file dan direktori dalam paket penyebaran Anda. Misalnya, untuk memberikan file yang tidak dapat dieksekusi izin yang benar, jalankan perintah berikut,. chmod 644 <filepath> Untuk mengubah izin file di Windows, lihat Mengatur, Melihat, Mengubah, atau Menghapus Izin pada Objek dalam dokumentasi Microsoft Windows. +.. Jika Anda tidak memberikan izin AgentCore Runtime yang diperlukan untuk mengakses direktori dalam paket penerapan Anda, AgentCore Runtime menetapkan izin untuk direktori tersebut ke 755 (rwxr-xr-x).

Arsip ZIP yang berisi dependensi Linux arm64 perlu diunggah ke S3 sebagai prasyarat untuk Create Agent Runtime. Kode di bawah ini membutuhkan bucket S3 yang ditentukan untuk sudah ada. Silakan ikuti AWS dokumentasi di sini untuk membuat ember. TypeScript Kode berikut akan mengunggah arsip file.zip ke S3 dan membuat runtime 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}`);

Untuk mengaktifkan instrumentasi otomatis OTEL, sertakan node_modules/@aws/aws-distro-opentelemetry-node-autoinstrumentation/ dalam ZIP Anda dan gunakan opentelemetry-instrument awalan di titik masuk:


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

Untuk memanggil agen di Amazon Bedrock AgentCore runtime secara terprogram, lihat: Memanggil agen secara terprogram

Langkah 6: Hentikan sesi, perbarui, atau pembersihan

TypeScript Kode berikut akan memperbarui AgentCore Runtime. Unggah paket penerapan baru ke S3, lalu panggil: 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}`);

Untuk menghentikan sesi berjalan sebelum dapat dikonfigurasi IdleRuntimeSessionTimeout (default pada 15 menit) dan menghemat biaya pelarian potensial, gunakan kode berikut:


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 Kode berikut akan menghapus AgentCore runtime Amazon Bedrock dan file arsip.zip di 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 konsep untuk penyebaran kode langsung

Pelajari tentang Node.js-specific konsep saat menggunakan penerapan kode langsung dengan Amazon Bedrock AgentCore Runtime.

Topik

AgentCore Runtime Node.js hanya menerima .js titik masuk. TypeScript file (.ts) tidak diterima secara langsung — Anda harus mentranspilasinya JavaScript sebelum dikemas. Kami merekomendasikan penggunaan esbuild untuk mentranspile dan membundel dalam satu langkah. Tambahkan esbuild sebagai ketergantungan pengembangan dengan. npm install -D esbuild

Titik masuk bisa di subdirektori. Misalnya, src/app.js atau dist/index.js merupakan titik masuk yang valid. Node.js resolusi modul berjalan ke atas pohon direktori dari lokasi titik masuk, sehingga dependensi node_modules/ di root ZIP Anda ditemukan secara otomatis — tidak diperlukan NODE_PATH konfigurasi.

Saat Anda menentukan titik masuk subdirektori, pastikan jalur dalam entryPoint konfigurasi Anda cocok dengan jalur dalam file ZIP.

Ada dua pendekatan untuk dependensi pengemasan untuk Node.js agen:

Dependensi vendor (paling sederhana):

Sertakan node_modules/ langsung di ZIP Anda di samping titik masuk Anda:


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

Ini menghasilkan ZIP dengan struktur berikut:

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

Dibundel dengan esbuild (ZIP terkecil):

Gunakan esbuild untuk menggabungkan semua dependensi ke dalam satu file:


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

Ini menghasilkan ZIP minimal:

my-agent.zip
└── bundle.js

Kedua pendekatan tersebut bekerja. Penerapan yang dibundel biasanya di bawah 10 MB dan disebarkan lebih cepat. Penerapan vendored lebih sederhana dan tidak memerlukan langkah build tetapi bisa lebih besar.

AgentCore Runtime hanya mendukung arsitektur set instruksi arm64. Jika agen Anda menggunakan paket npm yang menyertakan modul asli (dikompilasi .node atau .so file), binari tersebut harus dikompilasi untuk Linux arm64.

AgentCore Runtime memvalidasi arsitektur semua .node dan .so file dalam paket penerapan Anda dengan membaca header ELF mereka. Jika ada biner yang dikompilasi untuk arsitektur yang berbeda (seperti x86_64 atau macOS), pembuatan agen Anda akan gagal dengan status. CREATE_FAILED

Untuk menginstal modul asli yang kompatibel dengan arm64:

Instal dependensi pada mesin arm64 (seperti instans Amazon EC2 AWS Graviton-based )

Gunakan npm --arch dan --platform flag:


npm install --arch=arm64 --platform=linux

Gunakan esbuild untuk menggabungkan kode Anda jika modul asli dapat dihindari saat runtime

Paket npm paling populer (Express, Axios, Fastify, Hono, ws) murni JavaScript dan tidak mengandung modul asli.

AgentCore Runtime tidak menjalankan TypeScript file secara langsung. Anda harus mengkompilasi kode TypeScript sumber Anda JavaScript sebelum menerapkan. Ini adalah pola yang sama yang digunakan oleh AWS Lambda.

Menggunakan TypeScript compiler (tsc):


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

Kemudian paket output yang dikompilasi:


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

Saat membuat agen, atur titik masuk ke .js file yang dikompilasi (misalnya, app.js atau dist/app.js tergantung pada struktur ZIP Anda).

Menggunakan esbuild (direkomendasikan untuk kemasan yang lebih sederhana):


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

esbuild mengkompilasi TypeScript dan membundel dependensi dalam satu langkah, menghasilkan file kecil yang mandiri. .js

Jika Anda package.json menyertakan engines.node bidang, AgentCore Runtime memvalidasi bahwa rentang yang ditentukan kompatibel dengan Node.js versi yang Anda pilih (misalnya, Node.js 22 saat menggunakan NODE_22 runtime). Jika rentang mengecualikan versi itu, pembuatan agen Anda akan gagal dengan statusCREATE_FAILED.

Misalnya, engines deklarasi berikut kompatibel dengan Node.js 22:


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

Deklarasi berikut tidak kompatibel dan akan menyebabkan pembuatan agen gagal:


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

AgentCore Runtime juga memeriksa engines.node bidang untuk dependensi umum di Anda. node_modules/ Jika salah satu dari ini mendeklarasikan rentang Node.js versi yang mengecualikan versi runtime target, pembuatan agen akan gagal.

Jika Anda mengalami engines.node ketidakcocokan, perbarui paket ke versi yang mendukung Node.js versi target Anda atau hapus engines bidang dari Andapackage.json. Untuk Node.js versi yang didukung, lihat Runtime bahasa yang didukung.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Penyebaran kode langsung untuk Python

Runtime dan penghentian yang didukung