Node.js에 대한 직접 코드 배포

직접 코드 배포를 사용하면 에이전트 코드와 해당 종속성을 .zip 파일 아카이브에 패키징하여 간단히 Node.js 기반 에이전트를 Amazon Bedrock AgentCore 런타임으로 가져올 수 있습니다. 에이전트는 여전히 AgentCore 런타임 요구 사항을 따라야 합니다. /invocations POST 및 /ping GET 서버 엔드포인트를 구현하는 진입점 .js 파일이 있어야 합니다.

종속성을 ZIPnode_modules/에 공급업체로 제공되거나 esbuild 번들 단일 .js 파일로 포함할 수 있습니다.

사전 조건

시작하기 전에 다음을 갖추었는지 확인하세요.

1단계: 프로젝트 설정 및 종속성 설치

다음 명령을 사용하여 프로젝트를 초기화합니다.

mkdir agentcore_runtime_node_deploy
cd agentcore_runtime_node_deploy
npm init -y

선택적으로를 실행npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation하여 Amazon Bedrock AgentCore 관찰성 추적을 활성화합니다.

2단계: 에이전트 코드 생성

에이전트 진입점을 생성합니다. 에이전트는 /ping GET 상태 엔드포인트 및 /invocations POST 핸들러와 함께 AgentCore 런타임 HTTP 계약을 구현해야 합니다.

3단계: 로컬에서 테스트

시작하기 전에 포트 8080이 사용 가능한지 확인합니다. 일반적인 문제 및 솔루션의 사용 중인 포트 8080(로컬 전용)을 참조하세요.

터미널 창을 열고 에이전트를 시작합니다.

4단계: 에이전트에 대한 관찰성 활성화

Amazon Bedrock AgentCore 관찰성을 사용하면 AgentCore 런타임에서 호스팅하는 에이전트를 추적, 디버깅 및 모니터링할 수 있습니다. 먼저 Amazon Bedrock AgentCore 런타임 관찰성 활성화의 지침에 따라 CloudWatch 트랜잭션 검색을 활성화합니다. 에이전트를 관찰하려면 Amazon Bedrock AgentCore 에이전트의 관찰성 데이터 보기를 참조하세요.

Node.js 에이전트에 대해 자동 계측을 활성화하려면 ADOT 패키지를 추가합니다.

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

배포할 때 ZIPnode_modules/에를 포함하고 진입점에 opentelemetry-instrument 접두사를 사용합니다(5단계 참조).

5단계: AgentCore 런타임에 배포 및 호출

에이전트 코드 및 종속성을 사용하여 .zip 파일을 생성합니다. AgentCore 런타임은 arm64 명령 세트 아키텍처만 지원합니다. 네이티브 모듈(.node 파일)이 arm64용으로 컴파일되었는지 확인합니다.

에이전트 런타임 생성을 위한 사전 조건으로 Linux arm64 종속성이 포함된 ZIP 아카이브를 S3에 업로드해야 합니다. 아래 코드를 사용하려면 지정된 S3 버킷이 이미 있어야 합니다. 여기의 AWS 설명서에 따라 버킷을 생성하십시오. 다음 TypeScript 코드는 .zip 파일 아카이브를 S3에 업로드하고 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}`);

OTEL 자동 계측을 활성화하려면 ZIPnode_modules/@aws/aws-distro-opentelemetry-node-autoinstrumentation/에를 포함하고 진입점에 opentelemetry-instrument 접두사를 사용합니다.

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

Amazon Bedrock AgentCore 런타임에서 프로그래밍 방식으로 에이전트를 호출하려면 다음을 참조하세요. 에이전트를 프로그래밍 방식으로 호출

6단계: 세션 중지, 업데이트 또는 정리

다음 TypeScript 코드는 AgentCore 런타임을 업데이트합니다. 새 배포 패키지를 S3에 업로드한 다음 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}`);

구성 가능한 IdleRuntimeSessionTimeout (기본값은 15분) 이전에 실행 중인 세션을 중지하고 잠재적 런어웨이 비용을 절감하려면 다음 코드를 사용합니다.

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 코드는 S3에서 Amazon Bedrock AgentCore 런타임과 .zip 아카이브 파일을 삭제합니다.

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별 개념

Amazon Bedrock AgentCore 런타임에서 직접 코드 배포를 사용할 때 Node.js 관련 개념에 대해 알아봅니다.

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" } }