AI 엔지니어를 위한 설정

적용 지점: SDK (Python / Node) 지원 모드: Hosted Hybrid Local 플랜: Free Solo Teams

대상 독자

에이전트와 AI 기능을 만드는 분입니다. 코드를 소유하고 모델을 직접 호출하며, 아키텍처를 뜯어고치지 않고도 에이전트가 할 수 있는 일에 프로그래밍 방식의 가드레일을 두고 싶은 분을 위한 문서입니다.

일반적으로 통제하려는 대상

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

• Model allow-list. Only the models you have vetted and budgeted for can be called.

• 도구 접근. 에이전트는 검색하고 읽을 수는 있지만, 허용하지 않는 한 코드를 실행하거나 삭제할 수 없습니다.
• 데이터 경계. 승인된 저장소에서만 읽고, 내부 컬렉션에는 쓰지 않습니다.

설치할 적용 지점

SDK입니다. 각 도구를 호출하기 전에 guard() 호출 하나를 추가합니다. 직접 만든 루프, LangChain, 그 밖의 어떤 프레임워크에서도 똑같이 동작합니다.

pip install controlzero

시작용 정책

모델 허용 목록과 읽기 전용 도구 상태를 합친 정책입니다. 실제 트래픽과 맞는지 확인하는 동안에는 허용 상태(default_action: allow)로 시작하고, 적용하려면 deny로 바꾸세요. 이 내용을 controlzero.yaml에 넣으세요.

version: '1'
settings:
  # Start in observe; switch to "deny" once the audit log looks right.
  default_action: allow
  default_on_missing: deny
  default_on_tamper: warn
rules:
  - id: allow-vetted-models
    allow: 'llm:generate'
    reason: 'LLM generation is permitted (scope further with conditions per model).'
  - id: allow-tool-reads
    allow: 'data:read'
    reason: 'Agents may read from data sources.'
  - id: block-code-exec
    deny: 'tool:call'
    reason: 'No arbitrary code/tool execution from this agent.'

아키텍처 변경 없이 연결하세요.

from controlzero import Client

cz = Client(policy_file="./controlzero.yaml")

# Check before you call the model.
decision = cz.guard("llm", method="generate", context={"resource": "model/claude-sonnet-4-6"})
print(decision.decision)  # "allow"

# Check before a tool runs.
decision = cz.guard("data", method="read", context={"resource": "vectorstore/public-docs"})
print(decision.decision)  # "allow"

cz.close()

특정 모델을 고정하려면 전체 거부(catch-all deny)를 추가하고 검증한 모델만 허용하세요. LLM 모델 허용 목록을 참고하세요.

확인할 수 있는 내용

• 모든 guard() 결정(허용 또는 거부)이 감사 로그(Hosted) 또는 로컬 감사 파일(Local 모드)에 모델 또는 도구, 결정, 사유와 함께 기록됩니다. 이벤트별 적용 범위 정보를 통해 “실행되지 않음”과 “실행되었지만 아무것도 찾지 못함”이 구분됩니다.
• 개발하는 동안 CZ_DEBUG=1을 설정하면 각 정책 평가가 stderr에 출력됩니다.

다음 단계

• LLM 모델 허용 목록 -- 모델을 정밀하게 검증하세요.
• Python으로 AI 앱 통제하기 / Node.js -- SDK 전체 안내.
• 정책 -- 와일드카드, 조건, 평가 순서.
• 관찰 전용 설정 -- 적용하기 전에 먼저 관찰하세요.