본문으로 건너뛰기
이 페이지는 기계 번역이며 충분한 검토를 거치지 않았습니다. 영어 원문이 기준입니다. 보안, 개인정보 보호, 데이터 처리, 규정 준수 및 라이선스에 관한 설명은 기술 검토가 끝날 때까지 영어로 유지됩니다. 영어 원문 보기

Python으로 개발 중인 AI 앱 통제하기

사용하는 적용 지점: Python SDK, 프레임워크 통합 (LangChain, CrewAI, LangGraph, OpenAI Agents, PydanticAI) 지원 모드: Local Hosted Hybrid 플랜: Free (기본) Solo Teams (Hosted 기능)

수행할 내용​

Python AI 앱에서 위험한 부분 -- 도구 호출, 외부 API 호출, 파일 쓰기 -- 을 guard() 검사 한 번으로 감쌉니다. 정책은 사용자가 관리하는 YAML 파일에 있으며, SDK는 사유와 함께 허용/거부를 반환하고 결정을 기록합니다.

이 방법이 적합한 경우​

  • LLM이나 도구를 호출하는 Python 앱을 직접 작성하고 코드를 소유하고 있다면, SDK로 가장 세밀하게 제어할 수 있습니다.
  • LangChain, CrewAI, LangGraph, OpenAI Agents 또는 PydanticAI를 사용한다면 통합에 기본 제공 헬퍼가 있습니다.
  • 코드를 변경할 수 없다면 게이트웨이를 사용하세요.
  • 앱이 Node라면 대신 Node SDK를 사용하세요.

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

주의

SDK는 각 결정 지점에서 guard()를 호출하거나 통합 래퍼를 사용해야 합니다. 모든 LLM 요청을 자동으로 가로채는 코드 변경 없는 방법을 원한다면 게이트웨이를 사용하세요.

5분 설정​

pip install controlzero

Local 모드 (계정 불필요, 정책은 디스크에 저장)​

from controlzero import Client

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

decision = cz.guard(
    tool="shell",
    args={"command": "rm -rf /"},
)

if not decision.allowed:
    raise RuntimeError(f"Blocked by policy: {decision.reason}")

최소한의 policy.yaml:

rules:
  - id: block-shell-execute
    deny: 'shell:execute'
    reason: 'Destructive shell commands are not allowed.'
  - id: allow-everything-else
    allow: '*'
    reason: 'Default-allow for everything else.'

규칙이 작동할 때의 예상 출력:

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

Hosted 모드 (정책은 대시보드에 저장)​

import os
from controlzero import Client

cz = Client(api_key=os.environ["CONTROLZERO_API_KEY"])

decision = cz.guard(tool="web_search", args={"query": "..."})

환경에 CONTROLZERO_API_KEY=cz_live_...를 설정하세요. 정책은 자동으로 가져오고 최신 상태로 유지됩니다.

작동 확인​

  1. 앱을 실행하고 감사 로그(Local 모드) 또는 대시보드 Audit 페이지(Hosted)를 확인합니다.
  2. 정책이 거부해야 하는 요청을 보냅니다. decision.allowed == False이고 이벤트가 표시되는지 확인합니다.
  3. 허용되는 요청을 보냅니다. decision.allowed == True이고 allow 감사 행이 있는지 확인합니다.

자주 이어지는 질문​

참고 자료​