5분 안에 AI 에이전트에 킬 스위치를 추가하는 방법
Source: Dev.to
번역을 진행하려면 번역하고자 하는 전체 텍스트를 제공해 주시겠어요?
코드 블록, URL 및 마크다운 형식은 그대로 유지하면서 본문만 한국어로 번역해 드리겠습니다.
소개
귀하의 AI 에이전트는 프로덕션 환경에서 실행되며 API를 호출하고, 의사결정을 내리며, 비용을 지출합니다. 만약 에이전트가 문제가 생겨—루프에 갇히거나 툴 호출을 환각하고, API 예산을 소진한다면—유일한 방법은 수동으로 프로세스를 종료하는 것입니다. 이 튜토리얼은 에이전트의 핵심 코드를 변경하지 않고도 5분 안에 실제 킬 스위치를 추가합니다.
리버스‑프록시가 에이전트와 LLM 제공자 사이에 위치합니다. 모든 요청은 이를 통해 흐르고, 정책은 YAML로 정의되며, 정책이 트리거되면 모델에 도달하기 전에 요청이 차단됩니다.
사전 요구 사항
- Docker 및 Docker Compose가 설치됨
- OpenAI API 키(또는 OpenAI와 호환되는 제공자)
- OpenAI API 형식을 사용하는 AI 에이전트
Setup
git clone https://github.com/airblackbox/air-platform.git
cd air-platform
cp .env.example .env.env 파일을 편집하고 API 키를 추가하세요:
OPENAI_API_KEY=sk-your-key-here플랫폼을 시작합니다:
make up여섯 개의 서비스가 약 8 초 안에 시작됩니다. 중요한 서비스는 http://localhost:8080 에서 실행되는 Gateway 입니다.
에이전트를 Gateway에 연결하기
Python (OpenAI SDK)
from openai import OpenAI
# 이전 — OpenAI에 직접 호출
# client = OpenAI()
# 이후 — AIR Blackbox Gateway를 통해 호출
client = OpenAI(base_url="http://localhost:8080/v1")LangChain
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
openai_api_base="http://localhost:8080/v1",
model="gpt-4o"
)CrewAI
import os
os.environ["OPENAI_API_BASE"] = "http://localhost:8080/v1"
# CrewAI가 자동으로 인식합니다cURL
curl http://localhost:8080/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello"}]
}'에이전트는 정확히 동일하게 동작하지만, 이제 모든 호출이 Gateway를 통해 흐르게 됩니다.
킬‑스위치 정책 정의
config/policies.yaml를 편집합니다. 아래는 일반적인 실패 모드를 다루는 시작 정책입니다:
policies:
# Kill switch: stop runaway loops
- name: loop-detector
description: "Kill agent if it makes more than 50 requests in 60 seconds"
trigger:
type: rate-limit
max_requests: 50
window_seconds: 60
action: block
alert: true
# Kill switch: budget cap
- name: budget-cap
description: "Kill agent if it exceeds $5 in token spend"
trigger:
type: cost-limit
max_cost_usd: 5.00
action: block
alert: true
# Kill switch: restrict dangerous tools
- name: tool-restriction
description: "Block agent from executing shell commands"
trigger:
type: tool-call
blocked_tools:
- "execute_command"
- "run_shell"
- "delete_file"
action: block
alert: true
# Risk tiers: require human approval for high‑risk actions
- name: high-risk-gate
description: "Flag requests that involve payments or external APIs"
trigger:
type: content-match
patterns:
- "payment"
- "transfer"
- "external_api"
action: flag
risk_tier: critical파일을 저장합니다. 정책 엔진은 자동으로 변경 사항을 감지합니다—재시작이 필요하지 않습니다.
루프 감지기 테스트
from openai import OpenAI
import time
client = OpenAI(base_url="http://localhost:8080/v1")
# Simulate a runaway agent — rapid repeated calls
for i in range(60):
try:
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": f"Request {i}"}]
)
print(f"Request {i}: OK")
except Exception as e:
print(f"Request {i}: BLOCKED — {e}")
break
time.sleep(0.5)속도 제한이 트리거될 때까지 정상적인 응답을 확인할 수 있으며, 그 이후에는 요청이 차단되고 에이전트가 중지됩니다.
관측성
- Jaeger trace viewer – 모든 요청의 전체 추적.
- Prometheus metrics – 비용 및 요청 통계.
- Episode Store API – 컨텍스트, 지연 시간 및 비용과 함께 전체 시퀀스를 재생.
5분 만에 얻은 것
- 루프 감지 – 통제 불능 에이전트가 자동으로 종료됩니다.
- 예산 상한 – 예상치 못한 API 비용이 없습니다.
- 도구 제한 – 위험한 기능이 차단됩니다.
- 위험 등급 – 고위험 행동은 인간 검토를 위해 표시됩니다.
- 전체 감사 로그 – 모든 결정이 기록되고 재생 가능합니다.
에이전트 핵심 로직을 한 줄도 수정하지 않고; 킬 스위치는 인프라 계층에 존재합니다.
맞춤 정책
- 특정 모델을 차단합니다.
- 요청당 토큰 수를 제한합니다.
- 특정 도구 호출에 대해 인간 승인을 요구합니다.
- 필요한 모든 패턴을 정의합니다.
프레임워크 플러그인
보다 깊은 통합을 위해, 다음에 대한 신뢰 플러그인이 제공됩니다:
- CrewAI
- LangChain
- AutoGen
- OpenAI Agents SDK
이 플러그인들은 프레임워크 수준에서 신뢰 점수 매기기와 정책 시행을 추가합니다.
MCP Security (Optional)
**Model Context Protocol (MCP)**을 사용하는 경우, MCP Security Scanner는 MCP 서버 구성을 감사하고, MCP Policy Gateway는 MCP 도구 호출에 대한 정책을 적용합니다.
Source: …
라이선스 및 출처
전체 플랫폼은 Apache 2.0 라이선스 하에 오픈 소스입니다.
AIR Blackbox는 AI 에이전트를 위한 플라이트 레코더입니다—모든 결정을 기록하고, 모든 사건을 재생하며, 모든 정책을 시행합니다. 에이전트가 프로덕션 환경에서 결정을 내리고 있다면, 블랙박스가 필요합니다.