Node.js로 개발 중인 AI 앱 통제하기

사용하는 적용 지점: Node.js SDK, Vercel AI SDK 미들웨어, 프레임워크 통합 지원 모드: Local Hosted Hybrid 플랜: Free (기본) Solo Teams (Hosted 기능)

수행할 내용

Node.js 앱의 모든 LLM 호출과 도구 호출 앞에 guard() 검사를 추가합니다. 단독으로 사용하거나 Vercel AI SDK 미들웨어로 사용할 수 있으며, 정책을 적용하고 감사 추적을 기록합니다.

이 방법이 적합한 경우

• LLM을 호출하는 Node.js 또는 Next.js 앱을 직접 작성하고 코드를 소유하고 있다면, SDK로 세밀하게 제어할 수 있습니다.
• Vercel AI SDK를 사용한다면 generateText / streamText를 투명하게 감싸는 미들웨어를 제공합니다.
• 코드를 변경할 수 없다면 게이트웨이를 사용하세요.
• 앱이 Python이라면 Python으로 AI 앱 통제하기를 참고하세요.

이 방법을 사용하지 말아야 할 경우

주의

SDK는 각 결정 지점마다 코드 변경이 필요합니다. 모든 LLM 요청을 코드 변경 없이 가로채려면 기본 URL을 게이트웨이로 바꾸세요.

5분 설정

Control Zero 레지스트리를 한 번 설정합니다. .npmrc에 @controlzero:registry=https://npm.controlzero.ai를 추가하거나 npm config set @controlzero:registry https://npm.controlzero.ai를 실행하세요. 이 설정은 @controlzero 스코프 전체의 npm install과 npx에 적용됩니다.

npm install @controlzero/sdk

단독 guard

import { Client } from '@controlzero/sdk';

const cz = await Client.create({ apiKey: process.env.CONTROLZERO_API_KEY });

const decision = cz.guard('shell', {
  args: { command: 'rm -rf /' },
});

if (!decision.allowed) {
  throw new Error(`Blocked by policy: ${decision.reason}`);
}

차단된 호출의 예상 출력:

Error: Blocked by policy: Destructive shell commands are not allowed.

Vercel AI SDK 미들웨어

영어 원문 -- 번역은 기술 검토 대기 중입니다

The Node SDK ships a vercelAiMiddleware factory that plugs into the AI SDK's wrapLanguageModel API, so every generateText / streamText call is policy-checked before it reaches the provider and audited after.

import { Client } from '@controlzero/sdk';
import { vercelAiMiddleware } from '@controlzero/sdk/integrations';
import { generateText, wrapLanguageModel } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

const cz = await Client.create({ apiKey: process.env.CONTROLZERO_API_KEY });

const model = wrapLanguageModel({
  model: anthropic('claude-sonnet-4-6'),
  middleware: vercelAiMiddleware(cz, { agentId: 'my-bot' }),
});

const { text } = await generateText({
  model,
  prompt: 'What is in my .env file?',
});

거부되면 미들웨어는 공급자를 호출하기 전에 예외를 발생시킵니다. 개별 도구 호출을 보호하려면 같은 @controlzero/sdk/integrations 진입점의 governedTool(cz, name, tool)로 각 AI SDK 도구를 감싸세요. 자세한 내용은 Vercel AI SDK 통합 페이지를 참고하세요.

Local 모드 (계정 불필요)

const cz = new Client({ policyFile: './policy.yaml' });

YAML 형식은 Python SDK와 동일합니다.

작동 확인

1. 거부되어야 하는 요청을 보냅니다. decision.allowed === false와 사유가 반환되어야 합니다.
2. 통과해야 하는 요청을 보냅니다. decision.allowed === true와 allow 감사 이벤트가 있어야 합니다.
3. Hosted 모드에서는 대시보드 -> Audit을 열고 이벤트가 스트리밍되는 것을 확인합니다.

자주 이어지는 질문

• "Vercel AI SDK를 사용해요" -> Vercel AI SDK 통합
• "프롬프트의 PII를 보호하고 싶어요" -> DLP 적용 범위
• "팀 전체로 확장하고 싶어요" -> 디바이스 등록
• "완전한 오프라인으로 실행하고 싶어요" -> 완전한 오프라인 실행

참고 자료

• 적용 지점 페이지: Node.js SDK
• 개념: 정책, 프로젝트
• API: API 레퍼런스