CDX AGENT DOCK DEVELOPER API REFERENCE

CDX Agent Dock 개발자 기술 문서

LangChain, CrewAI, AutoGen 크로스 프레임워크 어댑터, slimmer / mcp_proxy / route 런타임 최적화 옵션, 고객사 표준 스토리지(JSON / SQLite3 BYOS) 기반 민감정보 마스킹(CDXCloak) & 도구 라우터(CDXArbiterEngine), Docker Sidecar v2.1 및 오픈 코어(Open-Core) 보안 아키텍처 명세를 안내합니다.

SDK & Sidecar 버전: v2.1.0 GA (Python SDK & Docker Sidecar) Stable

1. 패키지 설치 및 퀵스타트 (Python SDK v2.1.0 & Docker Sidecar)

cdx-dock v2.1.0은 파이썬 애플리케이션 내장형 SDK(pip)와 비(非) 파이썬 백엔드를 위한 리버스 프록시 컨테이너(Docker Sidecar) 두 가지 배포 옵션을 제공합니다.

1.1A PyPI 공식 패키지 설치 (Python 환경)

# [기본 설치] 4대 코어 엔진(다국어 Arbiter · CDX-Tab · Slimmer · 어댑터) + TokenPack-10K pip install cdx-dock # [VaultPack-2K 암호화 금고 포함 설치] AES-256-GCM + AAD 로컬 암호화(cryptography) 포함 pip install "cdx-dock[vault]" # [비상 원클릭 패스스루 환경변수] 문제 발생 시 코드 수정 없이 모든 최적화 즉시 우회 export CDX_BYPASS=1

1.1B Docker Hub 공식 컨테이너 설치 (Node.js / Go / Java / K8s 환경)

# Docker Sidecar v2.1.0 이미지 다운로드 (OpenAI 호환 프록시) docker pull cdxno1/cdx-a2a-sidecar:2.1.0

1.2 시스템 요구사항 및 호환성 규격

Python 3.10+ · numpy>=1.24.0 런타임 또는 표준 Docker 컨테이너 환경을 지원하며, 외부 데이터베이스 서버나 외부 네트워크 연결이 전혀 필요 없는 Zero Outbound Network Dependencies / 100% Offline Air-Gap 아키텍처로 동작합니다.

구분지원 사양비고
Python SDKPython 3.10+ (numpy>=1.24.0)Linux, macOS, Windows 지원 (Zero Outbound Network Dependencies · 100% Offline Air-Gap)
Docker Sidecarcdxno1/cdx-a2a-sidecar:2.1.0 (linux/amd64, arm64)Node.js, Go, Java, Rust, K8s 환경에서 OpenAI 호환 프록시로 연동
지원 프레임워크LangChain, CrewAI, AutoGen, Hermes Agentinvoke(), run(), GroupChat, SKILL.md (agentskills.io) 실행 규약 자동 감지
BYOS 스토리지.json / .db (.sqlite3)고객사 로컬 볼륨 및 Docker 마운트 볼륨에 표준 규격으로 저장
패키지 아키텍처Open-Core (.py + .pyd/.so)어댑터 계층 오픈소스 공개(사내 보안 점검 대응) + 코어 엔진 네이티브 컴파일

1.3 기본 연동 예제 (30초 퀵스타트)

from cdx_dock import as_crewai_tool from crewai import Agent # [1] 기존 LangChain 에이전트 준비 my_langchain_agent = ... # 기존 AgentExecutor 인스턴스 # [2] 1줄 함수 호출로 CrewAI 호환 도구 변환 (slimmer=True로 전달 페이로드 48.2% 경량화) sql_tool = as_crewai_tool(my_langchain_agent, name="db_searcher", slimmer=True) # [3] CrewAI 에이전트에 도구로 할당 analyst = Agent(role="수석 데이터 분석가", goal="분기 실적 데이터 조회", tools=[sql_tool])

1.4 라이선스 키(CDX_LICENSE_KEY) 설정 및 오프라인 정품 인증

별도의 회원가입이나 라이선스 키가 없더라도 Python SDK와 Docker Sidecar 모두 설치 즉시 30일 무료 오픈 트라이얼(30-Day Sandbox · 월 150,000 스텝, 7대 엔진 전체 개방)로 바로 작동합니다. 월간 쿼터 또는 30일 샌드박스 한도에 도달하더라도 프로덕션 파이프라인은 절대 중단되지 않고 무중단 원본 패스스루(Zero-Downtime Safe Pass-Through) 모드로 자동 전환되며 업그레이드 알림이 표시됩니다. 유료 플랜(Starter ~ Enterprise) 구독 시 자동 발급되는 Ed25519 서명 정품 오프라인 키(CDX2.<payload>.<sig>)는 아래 방식으로 등록하며, 미서명·변조된 키 입력 시에는 즉시 차단(CDXLicenseError / HTTP 401)됩니다.

# [무료 샌드박스] 키 설정 불필요 — 즉시 상태 확인 python -m cdx_dock --status # [유료 플랜 방법 A] OS / 컨테이너 환경변수로 정품 Ed25519 오프라인 키 설정 (외부 서버 통신 0회) export CDX_LICENSE_KEY="CDX2.<payload>.<ed25519_sig>" python -m cdx_dock --verify --key "$CDX_LICENSE_KEY" # [유료 플랜 방법 B] Python 애플리케이션 시작점(main.py)에서 코드로 직접 주입 및 상태 확인 import cdx_dock lic_info = cdx_dock.set_license_key("CDX2.<payload>.<ed25519_sig>") print(lic_info["tier"], lic_info["status"]) # -> 'GROWTH', 'ACTIVE' print(cdx_dock.get_license_info()["current_machine_id"]) # -> 사내 폐쇄망 바인딩용 하드웨어 노드 ID ('cdx_mach_...')

2. 크로스 프레임워크 어댑터 상세 명세

서로 다른 에이전트 프레임워크 간의 호출 시그니처와 입출력 포맷을 자동으로 정규화하는 어댑터 명세와 각 에이전트 구축 방식의 구조적 차이를 설명합니다.

2.0 에이전트 구축 방식 비교: 단순 프롬프트(개념)형 vs. 4대 엔터프라이즈 프레임워크

단순히 시스템 프롬프트에 역할 개념만 적어 만드는 단순 프롬프트형 에이전트는 대화는 가능하지만, 사내 DB 조회·코드 실행·작업 순서 강제·다중 에이전트 검수가 불가능합니다. 이를 해결하기 위해 기업들은 각기 다른 철학의 에이전트 프레임워크를 사용하며, cdx-dock은 이 모든 프레임워크의 약점을 보완하고 1줄로 상호 연결합니다.

구분 / 프레임워크핵심 작동 원리 (비유)주요 강점프레임워크 단독 운영 시 한계cdx-dock 결합 시 해결 효과
단순 프롬프트형
(Custom GPTs 등)
말로만 지시받은 상담원
시스템 프롬프트(페르소나)만 부여
코딩 없이 1분 만에 제작 가능 사내 시스템 제어 불가, 작업 절차·검수 강제 불가 엔터프라이즈 프레임워크로 전환 시 표준 어댑터 제공
LangChain / LangGraph 컨베이어 벨트 공장 (DAG)
A단계 → B단계 → 조건분기를 그래프/체인으로 엄격히 연결
대기업·금융권 백엔드 파이프라인의 정밀한 순서 통제 체인 단계마다 누적되는 JSON 컨텍스트로 인한 토큰 급증 as_langchain_tool / CDXLangChainDock으로 단계 간 페이로드 48.2% 경량화
CrewAI 회사 조직도 & 역할극 팀
직책(Role), 목표(Goal), 배경(Backstory)을 부여해 팀처럼 분업
직관적인 기획·리서치·보고서 작성 멀티 에이전트 구성 팀원 에이전트 간 보고서 전달 시 토큰 비대화 및 타 프레임워크 도구 호환 불가 as_crewai_tool / CDXCrewAIDock으로 타 프레임워크 도구를 1줄 이식 및 압축
Microsoft AutoGen 끝장 토론 회의실 (GroupChat)
작성자·검수자·실행자 에이전트가 채팅방에서 합의될 때까지 루프 대화
코드 작성·디버깅·복합 수리 추론에 강점 다자간 대화 루프가 길어질수록 토큰 비용이 기하급수적으로 폭발 as_autogen_agent / CDXAutoGenDock으로 대화 턴마다 메시지 자동 슬리밍
Nous Hermes Agent
(agentskills.io)
업무 수첩(SKILL.md)을 적는 터미널 실무자
도커/SSH/터미널에서 직접 일하며 작업 절차를 마크다운 스킬로 기록
오픈모델 기반 자율 서버 운영 및 절차적 스킬 축적 수십 개의 SKILL.md와 MCP 도구 전체 주입 시 문맥 한계 초과 및 기밀 노출 위험 CDXHermesDock으로 Top-K 스킬만 <10ms 선별 주입 + SKILL.md 압축 + 기밀 핀닝

2.1 as_crewai_tool()

LangChain 에이전트, AutoGen 에이전트 또는 일반 Python 호출 가능 객체를 CrewAI 호환 도구 객체로 변환합니다.

def as_crewai_tool( agent: Any, name: Optional[str] = None, description: Optional[str] = None, slimmer: bool = False, mcp_proxy: bool = False, route: bool = False ) -> CrewAIToolWrapper
파라미터타입기본값설명
agentAny필수변환할 원본 에이전트 인스턴스 또는 호출 가능 객체
namestrNoneCrewAI 도구 식별자 (생략 시 객체 메타데이터에서 자동 추출)
descriptionstrNone하위 도구 선택 시 에이전트가 참조할 기능 설명문
slimmerboolFalseTrue 설정 시 Mode B 구조적 압축을 적용하여 전달 페이로드 토큰 48.2% 절감
mcp_proxyboolFalseTrue 설정 시 도구 스키마 메타데이터 36% 경량화 및 프롬프트 캐시 정합성 유지
routeboolFalseTrue 설정 시 <10ms 인메모리 도구 라우터를 가동하여 불필요한 스키마 주입 90% 절감

2.2 as_langchain_tool()

CrewAI 에이전트 또는 AutoGen 에이전트를 LangChain BaseTool 호환 객체로 변환합니다.

from cdx_dock import as_langchain_tool lc_tool = as_langchain_tool( crew_researcher, name="market_researcher", description="시장 동향 및 경쟁사 지표를 조사하는 전문 에이전트 도구", slimmer=True )

2.3 as_autogen_agent()

LangChain 또는 CrewAI 에이전트를 AutoGen ConversableAgent 규격으로 변환하여 다자간 GroupChat 세션에 참여시킵니다.

from cdx_dock import as_autogen_agent from autogen import GroupChat, GroupChatManager autogen_member = as_autogen_agent(my_langchain_agent, name="financial_analyst", slimmer=True) groupchat = GroupChat(agents=[autogen_member, ...], messages=[]) manager = GroupChatManager(groupchat=groupchat)

2.4 bridge(source, target)

선행 에이전트(Source)의 출력을 후행 에이전트(Target)의 입력으로 직결하는 1:1 실행 파이프라인을 생성합니다.

from cdx_dock import bridge # Agent A (데이터 수집) ➔ Agent B (리포트 작성) 직통 파이프라인 pipeline = bridge(crewai_researcher, langchain_writer, slimmer=True) final_report = pipeline("2026년 3분기 클라우드 인프라 시장 분석")

2.5 adapt(agent, to='...')

타깃 프레임워크 식별자 문자열("crewai", "langchain", "autogen")을 지정하여 동적으로 어댑터를 반환하는 통합 인터페이스입니다.

from cdx_dock import adapt tool_for_crew = adapt(agent, to="crewai", slimmer=True) tool_for_lc = adapt(agent, to="langchain", slimmer=True, mcp_proxy=True) agent_for_ag = adapt(agent, to="autogen")

2.6 CDXHermesDock (Nous Hermes Agent & agentskills.io 어댑터)

Nous Research의 Hermes Agent 및 agentskills.io 표준(SKILL.md 마크다운 절차서)을 사용하는 에이전트에 ① SKILL.md 마크다운 가역 압축, ② <10ms 인메모리 Top-K 스킬·도구 선별 라우팅, ③ CDXCloak 명시적 기밀 핀닝, ④ LangChain/CrewAI/AutoGen 양방향 호환을 동시에 결합하는 전용 어댑터입니다.

from cdx_dock import CDXHermesDock # 1) Hermes 에이전트 인스턴스(또는 호출 함수)를 CDXHermesDock으로 래핑 hermes_dock = CDXHermesDock( hermes_agent, name="devops_hermes_operator", slimmer=True, # SKILL.md 및 입출력 페이로드 토큰 경량화 cloak=True, # 지정된 기밀 변수(pin_secrets) 로컬 가명화 및 자동 복원 route=True, # 수십 개 SKILL.md 중 현재 질의에 필요한 Top-K 스킬만 <10ms 선별 top_k_skills=2 ) # 2) SKILL.md 절차서 압축 + 기밀 핀닝 + Top-K 라우팅이 적용된 안전한 실행 result = hermes_dock.invoke( "프로덕션 DB 마이그레이션 점검 후 정산 계좌 상태를 확인해줘", skills=my_skills_catalog, skill_md=raw_skill_markdown, pin_secrets={"SETTLEMENT_ACC": "ACC-9981-7721-0042", "DB_HOST": "10.240.18.99"} ) print(result["output"]) # 사내 로컬 볼트에서 원래 기밀 값으로 복원된 최종 응답 print(result["selected_skills"]) # <10ms 내에 선별된 Top-K 스킬 목록 # 3) Hermes 에이전트를 CrewAI / LangChain / AutoGen 도구로 1줄 내보내기 crew_tool = hermes_dock.to_crewai_tool() lc_tool = hermes_dock.to_langchain_tool()

3. 런타임 컨텍스트 최적화 옵션 가이드

CDX Agent Dock의 모든 어댑터는 기본적으로 원본 데이터를 변경하지 않는 패스스루(Pass-through) 모드로 동작하며, 파라미터 플래그를 통해 3가지 런타임 최적화를 선택적으로 활성화할 수 있습니다.

3.1 slimmer=True — Mode A ↔ Mode B 양방향 코덱 (에이전트 간 전달 페이로드 48.2% 경량화)

DockSlimmer는 데이터를 누가 읽느냐(기계 DB/API vs 외부 LLM)에 따라 최적의 전달 포맷을 왕복 전환합니다. 외부 LLM 프롬프트 주입 시에는 구문 기호 거품을 제거한 Mode B(-48.2%)로 토큰 비용을 절감하고, 사내 DB 저장이나 REST API 응답 시에는 Mode A(표준 JSON)로 1:1 무손실 복원합니다.

구분Mode A (표준 JSON — DB·API용)Mode B (구조적 압축 — 외부 LLM용)
구조 특징 중괄호 { }, 대괄호 [ ], 쌍따옴표 " ", 쉼표 , 반복 기호 거품을 제거하고 들여쓰기와 콜론(:)만으로 계층 표현
토큰·지연 지표 142 Tokens (기준선) 74 Tokens (-48.2% 절감) · P50 약 0.18ms · 추론 정확도 동등 수준 유지(자체 실험)
주 용도 및 변환 사내 DB 저장, REST API 응답, slimmer.to_mode_a() 가역 복원 LangChain·CrewAI·AutoGen·Hermes 외부 LLM 호출 (slimmer.to_mode_b())
from cdx_dock import as_crewai_tool, DockSlimmer # 1) 어댑터에서 자동 Mode B 압축 활성화 sql_tool = as_crewai_tool(my_agent, slimmer=True) # 2) 직접 양방향 코덱 호출 (Mode A 표준 JSON ➔ Mode B 압축 ➔ Mode A 무손실 복원) slimmer = DockSlimmer() mode_b_text = slimmer.to_mode_b({"transaction_id": "TX_9942", "is_verified": True, "tags": ["finance", "kyc"]}) restored_json = slimmer.to_mode_a(mode_b_text) # 원본 Python dict/JSON 구조로 무손실 복원

3.2 mcp_proxy=True (도구 스키마 36% 경량화 및 프롬프트 캐시 정합성 유지)

도구 정의 JSON Schema의 비필수 메타데이터를 정리하고 정적 접두사 순서를 정규화하여 LLM 제공사(OpenAI, Anthropic, Google)의 KV-Cache 적중률을 높입니다.

# 도구 스키마 최적화 및 캐시 정합성 유지 sql_tool = as_crewai_tool(my_agent, mcp_proxy=True)

3.3 route=True (인메모리 Top-K 도구 라우팅, 지연 시간 < 10ms)

외부 LLM이나 별도 임베딩 API를 호출하지 않고 로컬 메모리에서 0.25ms~10ms 내에 질의 의도에 부합하는 상위 도구를 선별합니다.

# 1) 어댑터 파라미터로 활성화 sql_tool = as_crewai_tool(my_agent, route=True) # 2) 독립 함수로 도구 라우팅 단독 실행 from cdx_dock import route_tool decision = route_tool(my_tools, "이번 분기 법인세 정산 내역 조회") print(decision["tool_name"]) # 'query_corporate_tax' (0.3ms 소요)

3.4 통합 최적화 구성 (프로덕션 권장)

# 페이로드 압축 + 스키마 정규화 + 인메모리 도구 라우팅 동시 적용 sql_tool = as_crewai_tool(my_agent, slimmer=True, mcp_proxy=True, route=True)

3.5 CDX-CoT-Guard — 추론 모델(<think>) 무한 루프 차단 & KV-Cache 메모리 최적화

cot_middleware.py는 최신 추론형 LLM(GPT-6 Astra, Claude Sonnet 5.5 Thinking, Gemini 4 Carbon, DeepSeek-R1, QwQ 등)의 <think>...</think> 내부 추론 궤적에서 발생하는 동어반복 무한 루프를 실시간으로 절단(낭비 추론 토큰 40~60%+ 절감)하고, 적응형 추론 깊이 제어(Depth Control) 및 CDX 전용 KV-Cache 메모리 경량화 코어(메모리 약 75% 절감)를 제공합니다.

클래스 / 메서드적용 모델핵심 기능 명세
CDXCoTProxyMiddleware API 프록시 (OpenAI / vLLM / Ollama) prepare_request()로 조기 </think> 종료 방지(depth_control) 및 CDXCloak 기밀 핀닝 적용 · inspect_and_guard_stream()으로 스트리밍 추론 루프 조기 절단
CDXCoTMiddleware 온프레미스 로컬 추론 컨텍스트 매니저 with CDXCoTMiddleware(model): 구문으로 실시간 추론 정체 감지, 적응형 추론 깊이 제어, step_kv_cache() CDX 전용 KV-Cache 메모리 경량화 수행
from cdx_dock import CDXCoTProxyMiddleware, CDXCoTMiddleware # [모델 1] API 프록시 모드 (OpenAI / vLLM / Ollama 게이트웨이) cot_proxy = CDXCoTProxyMiddleware(min_think_steps=6, enable_slimmer=True, enable_cloak=True) req = cot_proxy.prepare_request( {"model": "deepseek-r1", "messages": [{"role": "user", "content": "3분기 정산 아키텍처 검증"}]}, step_idx=2, pinned_secrets={"SETTLEMENT_ACC": "ACC-9981-7721-0042"} ) guard_res = cot_proxy.inspect_and_guard_stream(reasoning_chunks, lang="ko") print(guard_res["loop_broken"], guard_res["token_savings_pct"]) # [모델 2] 온프레미스 추론 컨텍스트 매니저 & KV-Cache 메모리 최적화 with CDXCoTMiddleware(local_model, min_think_steps=6) as cot_guard: damped_kv, kv_meta = cot_guard.step_kv_cache(kv_tensor) print(kv_meta["memory_savings_pct"]) # ~74.8% KV-Cache 메모리 절감

3.6 CDX-TokenPack-10K — 벡터 DB 없는 로컬 폴더(pack_dir) 기반 8개 국어 10,000토큰 장기 기억 공유

token_pack.py는 별도의 외부 벡터 DB 서버 없이 사용자 지정 폴더(pack_dir) 내 단일 로컬 전용 메모리 팩 파일(cdx_token_pack_10k.db)을 통해 4대 프레임워크(CDXLangChainDock, CDXCrewAIDock, CDXAutoGenDock, CDXHermesDock) 간 최대 10,000토큰의 핵심 장기 기억을 실시간 동기화합니다. 10,000토큰 초과 시 저밀도 일상 로그는 자동 정리(Evict)하고 중요 수치·ID·핵심 규격은 장기 우선 보존하며, 글로벌 8개 국어(KO·EN·JA·ZH·ES·DE·FR·RU) 다국어 문맥 인덱싱 및 한·중·일(CJK) 다국어 토큰 인덱싱으로 <1.0ms 내에 Top-K 문맥을 회상합니다.

from cdx_dock import CDXTokenPack10K, CDXLangChainDock, CDXCrewAIDock # 1) 사용자 지정 로컬 폴더(pack_dir)에 10,000토큰 중요도 보존 메모리 팩 초기화 pack = CDXTokenPack10K(pack_dir="./shared_agent_memory") # 2) 글로벌 8개 국어(KO·EN·JA·ZH·ES·DE·FR·RU) 핵심 팩트 적재 (중요도 자동 산정) pack.ingest("[핵심 규격] 프로덕션 DB 커넥션 타임아웃은 1500ms, 최대 풀 사이즈는 64개로 고정한다.") pack.ingest("[CRITICAL SPEC] Global payment gateway retry limit=3, timeout=800ms.") # 3) <1.0ms 초고속 Top-K 문맥 리콜 및 프롬프트 자동 증강 recalled = pack.recall("프로덕션 DB 타임아웃 설정값 알려줘", top_k=2) augmented_prompt, stats = pack.augment_prompt("현재 DB 연결 타임아웃 기준과 맞는지 점검해줘", top_k=2) # 4) 이종 프레임워크 에이전트 간 동일한 pack_dir 지정으로 10K 장기 기억 실시간 공유 lc_dock = CDXLangChainDock(langchain_agent, pack_dir="./shared_agent_memory") crew_dock = CDXCrewAIDock(crewai_agent, pack_dir="./shared_agent_memory")

3.7 [v2.1.0] CDX-VaultPack-2K (10K ∥ 2K 병렬 암호화 금고) & CDX-Tab 무손실 표 압축

CDXDualTokenPack은 일상 대화 기억(10K ContextPack)과 민감정보 전용 암호화 금고(2K VaultPack)를 물리적으로 분리하여, 대화가 10,000토큰을 초과해도 주소·카드·계좌·API키가 밀려나지 않도록 영구 보존합니다. 모든 데이터와 마스터 키는 100% 고객사 로컬 호스트에만 저장(Zero-Knowledge)되며, AES-256-GCM + AAD 변조 감지 · PCI-DSS CVV/CVC 즉시 소각 · 1-Bit RBAC 최소 권한 격리를 제공합니다. (Sandbox 30일 체험 및 Growth $1,490+ 플랜 정식 제공 · Starter 플랜은 Safe Pass-Through 자동 우회 / 심층 방어 보조 가드레일로서 마스터 키 관리 및 최종 규제 준수 책임은 고객사에 귀속됩니다.)
또한 DockSlimmer.to_mode_b()는 4행 이상의 균일한 JSON 표 배열이 들어오면 자동으로 열 지향 무손실 사전 코덱(CDXTAB1:)을 적용해 토큰 크기를 54~66% 절감하고 to_mode_a()로 100% 원본 복원합니다.

from cdx_dock import ( CDXDualTokenPack, DockSlimmer, ROLE_CLOUD_PLANNER, ROLE_PAYMENT_EXECUTOR, ) # 1) 10K 일상 기억 || 2K 로컬 AES-256-GCM 암호화 금고 초기화 (Zero-Knowledge) dual = CDXDualTokenPack(pack_dir="./agent_dual_pack") turn = dual.ingest_turn("결제 카드 4532-1122-3344-5566 CVV=831, 이메일 ceo@acme.io") # -> turn["safe_text"]: 카드번호는 [[VPACK:CARD:...]]로 치환, CVV는 저장 없이 즉시 소각 # 2) 1-Bit RBAC 최소 권한 격리: 클라우드 LLM(0x00)은 차단, 동의된 결제 실행기만 로컬 복호화 card_handle = [h for h in turn["vault"]["handles"] if ":CARD:" in h][0] dual.resolve_for_tool(card_handle, role_mask=ROLE_CLOUD_PLANNER, user_consent=True) # authorized=False dual.resolve_for_tool(card_handle, role_mask=ROLE_PAYMENT_EXECUTOR, user_consent=True) # authorized=True # 3) 균일한 JSON 표 자동 CDX-Tab 열 지향 무손실 압축 (불규칙 JSON은 자동 Mode-B 우회) slimmer = DockSlimmer() encoded = slimmer.to_mode_b([{"id": i, "status": "COMPLETED", "region": "ap-northeast-2"} for i in range(25)]) restored = slimmer.to_mode_a(encoded) # 100% lossless roundtrip

4. BYOS 데이터 거버넌스: 명시적 데이터 마스킹(CDXCloak) & 도구 라우터 CRUD

민감정보 마스킹 사전과 도구 카탈로그는 당사 독자 포맷이 아닌 표준 UTF-8 JSON 및 SQLite3 관계형 테이블 규격으로 고객사 자체 스토리지(BYOS)에 저장·관리됩니다.

4.1 명시적 민감정보 마스킹 (CDXCloak) — 비지정 일반 텍스트 변조 방지 핀닝

기본값 strict_pin_mode=True를 통해 일반 날짜, 수량, 공개 코드 등이 단순 패턴 추측에 의해 오탐지되는 현상을 방지합니다. 개발자가 명시적으로 등록(Pin)한 기밀 항목만 결정론적 토큰으로 가명화하며, LLM 응답 수신 즉시 로컬에서 복원합니다.

from cdx_dock import CDXCloak # 1) 고객사 표준 SQLite3(.db) 또는 JSON(.json) 스토리지 연결 (strict_pin_mode=True 기본값) cloak = CDXCloak(storage_path="./enterprise_vault.db") # 2) [CREATE / UPDATE] 보호할 민감 항목 명시적 등록 (cdx_explicit_vault 테이블 동기화) token = cloak.pin_secret("ACC-9981-7721-0042", label="MAIN_SETTLEMENT_ACC") cloak.pin_secret("145,000,000원", label="EXEC_BUDGET") # 3) [READ] 등록된 보호 항목 목록 및 단건 조회 all_secrets = cloak.list_explicit_secrets() entry = cloak.get_explicit_secret("MAIN_SETTLEMENT_ACC") # 4) [MASK & UNMASK] 일반 날짜(2026-10-17)는 유지하고 등록된 기밀 항목만 정확히 가명화·복원 masked, session = cloak.mask_text("2026-10-17 기준 ACC-9981-7721-0042 계좌로 145,000,000원 집행 요청") restored = cloak.unmask_text(masked, session) # 5) [DELETE / CLEAR] 항목 삭제 또는 초기화 (스토리지 즉시 반영) cloak.remove_explicit_secret("EXEC_BUDGET")

4.1.1 아키텍처 원리: 왜 명시적 마스킹(pin_secret)은 모든 에이전트 프레임워크에서 일관되게 작동하는가?

기존 보안 솔루션처럼 단순 패턴 매칭이나 확률적 AI 추측으로 민감정보를 자동 탐색하면, 일반 날짜(2026-10-17)나 단순 수량까지 마스킹해 에이전트 추론을 망가뜨리거나 반대로 사내 고유 프로젝트명(타이탄 프로젝트)을 놓치는 오탐·미탐 사고가 발생합니다. CDXCloak이 기본값 strict_pin_mode=True 기반의 명시적 핀닝(pin_secret)으로 LangChain, CrewAI, AutoGen, Hermes 어디서나 일관되게 작동하는 이유는 다음 2가지 구조적 원리 때문입니다:

작동 원리기술적 메커니즘개발자 및 보안팀 이점
① 프레임워크 변수 템플릿(Prompt Template) 구조의 필연성 모든 엔터프라이즈 에이전트 프레임워크는 고정된 문장이 아니라 프롬프트 템플릿과 파이썬 변수 바인딩(예: "고객 {customer_name}님의 계좌 {account_num}에서 {amount}원을 조회해줘") 방식으로 설계됩니다. 개발자는 DB나 사내 API에서 조회한 어떤 변수(customer_name, account_num, db_key)가 기밀인지 코드 작성 시점에 이미 명확히 알고 있으므로, 단순 패턴 추측 없이 cloak.pin_secret(account_num, label="ACCOUNT") 1줄로 오탐 없는 명시적 핀닝이 가능합니다.
② 최종 출입구(Final Outbound Gateway) 텍스트 직렬화 법칙 각 프레임워크가 내부에서 체인(LangChain), 역할극(CrewAI), 토론(AutoGen), 터미널 스킬(Hermes) 중 어떤 방식으로 작동하든, 외부 LLM API로 출발하는 마지막 순간(invoke / run)에는 반드시 하나의 평문 문자열(String/JSON)로 직렬화됩니다. cdx-dock 어댑터는 이 최종 출입구를 가로채어 출발 직전 텍스트에서 등록된 기밀 변수값만 가명 토큰([[VAULT_PIN_ACCOUNT_124F]])으로 치환해 내보내고, LLM 응답이 돌아오면 로컬 메모리에서 즉시 원본 값으로 복원(unmask_text)합니다.
# [프레임워크 공통 패턴] 템플릿 변수 바인딩 + CDXCloak 명시적 핀닝 결합 예시 customer_name = db.get_vip_customer(user_id) # 예: "김철수 부사장" settlement_acc = db.get_account_number(user_id) # 예: "ACC-9981-7721-0042" # 개발자가 이미 보유한 기밀 변수를 1줄로 직접 핀닝 (일반 수치 오탐지 최소화) cloak.pin_secret(customer_name, label="VIP_CUSTOMER") cloak.pin_secret(settlement_acc, label="SETTLEMENT_ACC") # 어떤 프레임워크(LangChain / CrewAI / AutoGen / Hermes)의 프롬프트 템플릿이든 최종 출입구에서 안전하게 가명화·복원 prompt = f"{customer_name} 고객님의 정산 계좌({settlement_acc})로 2026-10-17 기준 내역을 요약해줘." masked_prompt, session = cloak.mask_text(prompt) # ➔ 외부 LLM 전송 본문: "[[VAULT_PIN_VIP_CUSTOMER_F07F]] 고객님의 정산 계좌([[VAULT_PIN_SETTLEMENT_ACC_124F]])로 2026-10-17 기준 내역을 요약해줘."

4.2 인메모리 도구 라우터 (CDXArbiterEngine) — 표준 카탈로그 CRUD

디스크에는 바이너리 임베딩 파일 없이 표준 텍스트 메타데이터(name, description, required_params, tags)만 저장하므로 DBeaver나 SQLite CLI로 직접 관리할 수 있습니다.

from cdx_dock import create_arbiter # 1) 고객사 표준 SQLite3(.db) 또는 JSON(.json) 카탈로그 연결 arbiter = create_arbiter(storage_path="./enterprise_tools.db") # 2) [CREATE / UPDATE] 도구 메타데이터 등록 (cdx_arbiter_tools 테이블 동기화) arbiter.add_tool( name="execute_sql_warehouse", description="사내 매출 데이터 웨어하우스에서 읽기 전용 SQL 분석 쿼리를 실행합니다.", required_params=["query"], tags=["sql", "warehouse", "analytics"] ) # 3) [READ] 등록된 도구 목록 및 상세 조회 print(arbiter.list_tools()) print(arbiter.get_tool("execute_sql_warehouse")) # 4) [ROUTE] 0.25ms~10ms 인메모리 최적 도구 선별 decision = arbiter.route("3분기 반도체 사업부 매출 SQL 쿼리 분석") print(decision.selected_tool, decision.latency_ms) # 5) [DELETE] 등록 도구 삭제 arbiter.remove_tool("execute_sql_warehouse")

5. Docker Sidecar v2.1 멀티 언어 배포 및 API 제어

Node.js, Go, Java, Rust, Kubernetes 등 비(非) 파이썬 백엔드 환경에서도 cdxno1/cdx-a2a-sidecar:2.1.0 컨테이너를 통해 코드 수정 없이 동일한 기능을 사용할 수 있습니다.

5.1 3-Way 컨테이너 제어 인터페이스 (환경변수 · HTTP 헤더 · REST API)

# [방식 1] 컨테이너 기동 시 라이선스 키(CDX_LICENSE_KEY) 및 BYOS 볼륨 마운트로 전역 기본값 설정 docker run -d --name cdx-sidecar -p 8080:8080 \ -v $(pwd)/cdx_data:/data \ -e CDX_LICENSE_KEY="CDX2.YOUR_SIGNED_LICENSE_KEY" \ -e UPSTREAM_LLM_URL="https://api.openai.com" \ -e CDX_BYOS_SQLITE="/data/enterprise_vault.db" \ -e CDX_PINS="PROJECT_CODE=PRJ-TITAN,SETTLEMENT_ACC=110-384-918273" \ -e CDX_TOP_K="2" \ -e CDX_SLIMMER="true" \ cdxno1/cdx-a2a-sidecar:2.1.0 # [방식 2] 요청별 HTTP 헤더를 통한 동적 오버라이드 (언어 무관) curl -X POST http://localhost:8080/v1/chat/completions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "X-CDX-License-Key: $CDX_LICENSE_KEY" \ -H "Content-Type: application/json" \ -H "X-CDX-Pins: CONTRACT_ID=CT-2026-9981" \ -H "X-CDX-Top-K: 2" \ -H "X-CDX-Slimmer: true" \ -d '{"model":"gpt-6-astra","messages":[{"role":"user","content":"계약번호 CT-2026-9981 검토 보고"}]}' # [방식 3] 런타임 REST API를 통한 민감정보 핀(Pin) 실시간 관리 curl -X POST http://localhost:8080/v2/cloak/pin -H "X-CDX-License-Key: $CDX_LICENSE_KEY" -d '{"key":"PARTNER_ID","secret":"ACME-9981"}' curl -X GET http://localhost:8080/v2/cloak/pins -H "X-CDX-License-Key: $CDX_LICENSE_KEY" curl -X DELETE "http://localhost:8080/v2/cloak/pin?key=PARTNER_ID" -H "X-CDX-License-Key: $CDX_LICENSE_KEY"

5.2 프로덕션 배포 매니페스트 템플릿 (docker-compose.yml & Kubernetes Sidecar Pod)

실제 상용 환경에서는 단발성 docker run 대신 아래 docker-compose.yml 또는 Kubernetes Deployment 매니페스트를 그대로 복사하여 애플리케이션 컨테이너 옆에 cdx-sidecar를 함께 배포합니다. 동일한 Pod 내부의 localhost:8080 루프백 인터페이스로 통신하므로 네트워크 지연이 사실상 0ms에 수렴합니다.

# ══════════════════════════════════════════════════════════════════════════════ # [템플릿 A] docker-compose.yml — 백엔드 서버 + CDX Sidecar + 사내 BYOS 볼륨 공유 # ══════════════════════════════════════════════════════════════════════════════ version: "3.9" services: cdx-sidecar: image: cdxno1/cdx-a2a-sidecar:2.1.0 container_name: cdx-sidecar restart: unless-stopped ports: - "8080:8080" volumes: - ./cdx_byos_data:/data environment: - CDX_LICENSE_KEY=${CDX_LICENSE_KEY} - UPSTREAM_LLM_URL=https://api.openai.com - CDX_BYOS_SQLITE=/data/enterprise_vault.db - CDX_TOP_K=2 - CDX_SLIMMER=true healthcheck: test: ["CMD", "wget", "-qO-", "--header=X-CDX-License-Key: ${CDX_LICENSE_KEY}", "http://localhost:8080/health"] interval: 15s timeout: 3s retries: 3 app-backend: build: . depends_on: - cdx-sidecar environment: - OPENAI_BASE_URL=http://cdx-sidecar:8080/v1 - OPENAI_API_KEY=${OPENAI_API_KEY} # ══════════════════════════════════════════════════════════════════════════════ # [템플릿 B] k8s-deployment.yaml — Kubernetes Pod 내 Sidecar 컨테이너 패턴 # ══════════════════════════════════════════════════════════════════════════════ apiVersion: apps/v1 kind: Deployment metadata: name: enterprise-ai-agent spec: replicas: 3 selector: matchLabels: app: enterprise-ai-agent template: metadata: labels: app: enterprise-ai-agent spec: containers: - name: main-agent-service image: mycorp/agent-service:latest env: - name: OPENAI_BASE_URL value: "http://localhost:8080/v1" - name: cdx-sidecar image: cdxno1/cdx-a2a-sidecar:2.1.0 ports: - containerPort: 8080 env: - name: CDX_LICENSE_KEY valueFrom: secretKeyRef: name: cdx-enterprise-secret key: license_key - name: UPSTREAM_LLM_URL value: "https://api.openai.com" - name: CDX_BYOS_SQLITE value: "/data/enterprise_vault.db" - name: CDX_TOP_K value: "2" volumeMounts: - name: cdx-byos-storage mountPath: /data volumes: - name: cdx-byos-storage persistentVolumeClaim: claimName: cdx-byos-pvc

6. 엔터프라이즈 오픈 코어(Open-Core) 아키텍처 & 보안 감사 규격

기업 정보보안팀의 사내 보안성 검토(정적 소스코드 점검) 요구사항과 프로덕션 환경의 초저지연 실행 무결성을 동시에 충족하기 위해, cdx-dock v2.1.0은 오픈 어댑터 계층(.py)과 프리컴파일 네이티브 코어 계층(.pyd / .so)을 분리하여 패키징합니다.

6.1 패키지 계층 구조 및 보안 감사 포인트

아키텍처 계층포함 모듈배포 포맷기업 보안 감사 및 운영 이점
Open Adapter 계층 universal_adapter.py, adapters/*, config.py 오픈소스 평문 Python (.py) 고객사 에이전트와 직접 결합되는 인터페이스 코드를 투명하게 공개하여 외부 네트워크 데이터 유출이 없음을 정적 분석으로 즉시 검증 가능
Native Core 엔진 계층 slimmer_engine, arbiter_engine, shield_engine 외 코어 모듈 프리컴파일 C-확장 바이너리 (.pyd / .so) < 1ms 네이티브 연산 성능 제공 및 배포 바이너리 변조 방지(Runtime Integrity) 보장
On-Premise 라이선스 가드 license_guard, fingerprint 네이티브 바이너리 & 노드 식별자 사내 폐쇄망(Air-Gapped VPC) 환경에서 외부 라이선스 서버 통신 없이 하드웨어 노드 식별자(cdx_mach_...) 기반으로 오프라인 정품 인증 수행

6.2 패키지 구성 확인 및 하드웨어 노드 ID 조회 예제

import cdx_dock.universal_adapter as adapter_layer import cdx_dock.slimmer_engine as native_engine from cdx_dock.fingerprint import MachineFingerprint # 1) 오픈 어댑터 계층 경로 확인 (정적 보안 감사용 .py 파일) print(adapter_layer.__file__) # -> .../site-packages/cdx_dock/universal_adapter.py # 2) 네이티브 코어 엔진 경로 확인 (프리컴파일 .pyd / .so 바이너리) print(native_engine.__file__) # -> .../site-packages/cdx_dock/slimmer_engine.cp313-win_amd64.pyd # 3) 온프레미스 폐쇄망 라이선스 발급용 서버 노드 식별자 확인 print(MachineFingerprint.get_machine_id()) # -> 'cdx_mach_...'

7. 실측 텔레메트리 조회 · 사내 자체 보고서 빌더 & BYOS 원본 데이터 1:1 반출

당사(Cantor Labs)는 고객사의 프롬프트, 토큰 수, 도구 카탈로그, 기밀 마스킹 내역을 외부 서버로 일절 수집하지 않습니다(Zero Data Custody · 외부 전송 0 Byte). 고객사는 로컬 런타임의 dock_telemetry와 CDXInternalReportBuilder를 통해 ① 실시간 로컬 가동 지표를 조회하고, ② 가상 샘플이나 단가 추측 없는 사내 보고서를 생성하며, ③ 고객사 BYOS 저장소에 담긴 원본 레코드를 1:1 그대로 반출할 수 있습니다.

7.1 로컬 실측 텔레메트리 조회 및 BYOS 영속 원장 API (dock_telemetry)

어댑터(slimmer=True), 도구 라우터(CDXArbiter), 추론 가드(CDX-CoT-Guard), 기밀 볼트(CDXCloak), 기억팩(TokenPack-10K)이 실행될 때마다 로컬 프로세스 메모리에 실측 카운터가 자동 기록됩니다. bind_byos_storage()를 연결하면 고객사 SQLite3(cdx_telemetry_ledger 테이블) 또는 JSON 파일에 영속 저장되어 서버 재시작 후에도 월간 집계가 그대로 유지됩니다.

from cdx_dock import dock_telemetry # 1) [선택] 고객사 로컬 SQLite3(.db) 또는 JSON(.json) 파일에 카운터 영속 바인딩 (서버 재시작 보존) dock_telemetry.bind_byos_storage("./enterprise_vault.db", load_existing=True) # 2) 실시간 로컬 실측 지표 스냅샷 조회 (호출 이력이 0건이면 모든 항목이 정확히 0으로 반환됨) summary = dock_telemetry.get_summary() print(summary["total_agent_calls"]) # 총 실행 호출 수 (예외 폴백 발생 건 포함) print(summary["completion_rate_pct"]) # 정상 처리율(%) 및 summary["fallback_calls"] 폴백 건수 print(summary["net_tokens_delta"]) # 순 증감 토큰량 (역압축 발생 시에도 음수 부호 그대로 표기) print(summary["average_latency_ms"]) # perf_counter() 기반 실제 측정 평균 지연시간(ms) print(summary["module_token_savings"]) # Arbiter / Slimmer / CoT-Guard / TokenPack 모듈별 실측치 print(summary["cloak_byos"]) # 가명화 송출·복원 호출 수 및 실제 치환/복원된 식별자 개수

7.2 사내 자체 보고서 빌더 및 커스텀 양식 슬롯 매핑 (CDXInternalReportBuilder)

고객사 내부 결재나 점검 시 벤더에게 유리한 추정치나 임의 단가($)가 섞여 오해를 유발하지 않도록, 실측 모드(use_live_telemetry=True, 기본값)에서는 오직 사내에서 실제 발생한 카운터와 로컬 설치된 오픈 어댑터(.py)의 실시간 AST 정적 스캔 결과만 기입합니다. 기본 제공되는 3종 양식(비용·토큰 정산 / 기술 운영 / 보안 점검) 외에 register_template()으로 등록한 고객사 고유 결재 양식의 모든 {변수명} 슬롯에도 실측치가 1:1 자동 주입됩니다.

📥 보고서 양식 레이아웃 예시 PDF 미리보기 (양식 구조 확인용 샘플이며, 실제 SDK 실행 시에는 고객사 BYOS 실측치만 출력됩니다): 📘 양식 통합본 샘플 PDF (4p) ① 비용·토큰 정산 양식 예시 PDF ② 기술·런타임 운영 양식 예시 PDF ③ 정보보안 점검 양식 예시 PDF
보고서 구분실측 집계 항목 (추정치·단가 추측 배제)사내 로컬 데이터 출처템플릿 자동 바인딩 슬롯 ({변수명})
공통 헤더
(org_info)
보고 부서명 / 작성자 / 집계 기간 / 운용 환경 / 고객사 계약 단가 메모 고객사 직접 입력 (org_info={...}) {company_name}, {author_name}, {reporting_period}, {deployment_mode}, {customer_llm_contract_note}
① 비용·절감량 정산
(cfo_roi_settlement_report)
실측 호출 수 · 원본 vs 전송 토큰 · 순 증감 토큰(+/- 투명 표기) · 모듈별 실측 절감 토큰 · 고객사 자체 단가 산식 summary['total_agent_calls']
summary['net_tokens_delta']
summary['module_token_savings']
{monthly_agent_calls}, {raw_tokens_total}, {slimmed_tokens_total}, {saved_tokens_total}, {stage1_arbiter_saved_tokens}, {stage2_slimmer_saved_tokens}, {stage3_cot_guard_saved_tokens}, {stage4_5_memory_saved_tokens}, {customer_cost_formula}
② 기술·런타임 운영
(cto_agent_runtime_report)
실측 실행 건수·정상 처리율(%) · 실측 평균 지연(ms) · <think> 루프 절단 건수 · 기억팩 회상 속도 · 예외 폴백 건수 summary['completion_rate_pct']
summary['average_latency_ms']
summary['fallback_calls']
{connected_frameworks}, {total_pipeline_runs}, {avg_dock_overhead_ms}, {cot_guard_loops_detected}, {cot_timeouts_prevented}, {cot_wasted_tokens_saved}, {tokenpack_recall_latency}, {fallback_activations}
③ 정보보안 점검
(ciso_security_audit_report)
사내 BYOS 볼트 경로 · 외부 전송량(0 Byte) · 등록 기밀 카테고리 · 실측 가명화/복원 건수 · 오픈 어댑터 실시간 AST 스캔 결과 reporter.cloak.vault_db_file
summary['cloak_byos']
verify_open_adapter_static_imports()
{byos_storage_location}, {vendor_data_transmission}, {cloak_pinned_categories}, {total_masked_outbound_calls}, {local_unmask_restorations}, {false_positive_mutations}, {static_code_audit_result}
from cdx_dock import CDXInternalReportBuilder reporter = CDXInternalReportBuilder( storage_path="./enterprise_vault.db", arbiter_storage_path="./enterprise_tools.db", token_pack_dir="./my_agent_10k_pack", persist_telemetry=True, lang="ko", # 기본값 "ko" (글로벌 본사 제출용 영문 양식·결재란이 필요하면 lang="en" 지정) ) # 1) 기본 3종 사내 보고서를 원하는 포맷(.md / .html A4 인쇄용 / .csv 엑셀용 / .json)으로 저장 reporter.save_report( template_id="cfo_roi_settlement_report", output_path="./reports/token_settlement_report.md", org_info={"company_name": "AI 플랫폼실", "author_name": "김민수 수석", "reporting_period": "2026-10"}, use_live_telemetry=True, ) reporter.save_report("cto_agent_runtime_report", "./reports/runtime_ops_report.csv", use_live_telemetry=True) reporter.save_report("ciso_security_audit_report", "./reports/security_audit_report.html", use_live_telemetry=True) # 2) 고객사 고유 결재 양식 등록 — 원하는 {변수명} 슬롯만 기재하면 사내 실측치가 자동 주입됨 reporter.register_template( template_id="weekly_team_summary", title="주간 AI 에이전트 실측 요약", template_markdown=( "부서: {company_name} | 호출: {monthly_agent_calls} | 순절감: {saved_tokens_total}\n" "평균 지연: {avg_dock_overhead_ms} | 가명화 송출: {total_masked_outbound_calls}" ), sample_org_info={"company_name": "AI 플랫폼실"}, ) weekly_md = reporter.render_report("weekly_team_summary")

7.3 BYOS 원본 데이터 1:1 반출 (export_byos_raw_data) & 라이선스 쿼터 조회 API

요약 리포트 외에도 고객사가 자체 BI 대시보드나 사내 감사 시스템에 직접 적재할 수 있도록, 고객사 BYOS 파일들(cdx_explicit_vault, cdx_arbiter_tools, pack_entries, cdx_telemetry_ledger)에 기록된 원본 레코드를 어떠한 가공 없이 .json 또는 .csv로 그대로 반출합니다. 상용 플랜별 상세 요금 및 애드온 구성은 제품 요금제 안내(dock.html#pricing)에서 확인하실 수 있습니다.

import cdx_dock from cdx_dock import get_tier_spec # 1) 고객사 BYOS 4대 저장소 원본 레코드 1:1 무가공 반출 (.json 또는 엑셀 호환 .csv) raw_bundle = reporter.export_byos_raw_data( output_path="./reports/byos_raw_passthrough.csv", include_secret_values=False, # 기본값 False(평문 기밀값 제외, 메타·토큰만 포함) / True 시 평문 포함 반출 ) # 2) 현재 적용된 라이선스 상태 및 플랜별 스텝 쿼터 규격 코드 조회 lic_status = cdx_dock.get_license_info() scale_quota = get_tier_spec("SCALE") print(lic_status["tier"], scale_quota["monthly_dock_calls"])

8. 프로덕션 실전 적용 레시피 (FastAPI · Next.js · Spring Boot · 멀티유저 격리)

단위 기능(Unit) 테스트를 넘어, 실제 운영 중인 웹 백엔드(Python FastAPI, Node.js / Next.js, Java Spring Boot)와 상용 LLM SDK(OpenAI / Anthropic)에 cdx-dock을 결합하는 프로덕션 표준 통합 코드입니다.

8.1 LangChain SQL 에이전트 ➔ CrewAI 분석 팀 통합

from langchain_community.agent_toolkits import create_sql_agent from crewai import Agent, Crew, Task from cdx_dock import as_crewai_tool # [1] LangChain SQL 에이전트 생성 sql_agent = create_sql_agent(llm=..., db=..., verbose=False) # [2] CDX Dock으로 1줄 도구 변환 (페이로드 압축 활성화) db_tool = as_crewai_tool(sql_agent, name="enterprise_db", slimmer=True) # [3] CrewAI 에이전트에 도구 할당 및 태스크 실행 analyst = Agent( role="수석 재무 분석가", goal="기업 매출 데이터를 조회하여 분기별 이상 징후 리포트 작성", tools=[db_tool], verbose=True ) task = Task(description="2026년 3분기 주요 거래 내역 분석", agent=analyst) crew = Crew(agents=[analyst], tasks=[task]) result = crew.kickoff()

8.2 [Python 백엔드 표준] FastAPI + OpenAI SDK End-to-End 통합 서버 (요청별 멀티유저 세션 격리)

실제 멀티유저 웹 서비스에서 가장 많이 묻는 질문인 ① 상용 OpenAI 클라이언트와 결합하는 순서와 ② 동시 접속 유저 간 기밀 변수(session)가 섞이지 않게 격리하는 방법을 모두 포함한 완결형 FastAPI 엔드포인트 템플릿입니다. mask_text()가 반환하는 session 딕셔너리는 해당 HTTP 요청의 로컬 스택에만 존재하므로 수천 명이 동시에 호출해도 유저 A와 유저 B의 민감정보가 절대 섞이지 않습니다(100% Request-Scoped Isolation).

from fastapi import FastAPI from pydantic import BaseModel from openai import OpenAI import cdx_dock from cdx_dock import CDXCloak, create_arbiter, DockSlimmer, CDXCoTProxyMiddleware app = FastAPI(title="Enterprise AI Agent API with CDX-Dock") openai_client = OpenAI() # 표준 OpenAI / Azure OpenAI / vLLM 클라이언트 그대로 사용 # [서버 기동 시 1회 초기화] 라이선스 등록 및 사내 로컬 BYOS 스토리지 연결 (Thread-Safe) cdx_dock.set_license_key("CDX2.YOUR_SIGNED_LICENSE_KEY") cloak = CDXCloak(storage_path="./byos_data/enterprise_vault.db") arbiter = create_arbiter(storage_path="./byos_data/enterprise_tools.db") slimmer = DockSlimmer() cot_guard = CDXCoTProxyMiddleware(min_think_steps=4, enable_slimmer=True) class ChatRequest(BaseModel): user_id: str customer_name: str settlement_acc: str query: str erp_context_json: dict @app.post("/api/v1/agent/execute") def execute_enterprise_agent(req: ChatRequest): # 1) [보안 핀닝 & 요청별 격리 가명화] 현재 요청 유저의 기밀 변수 핀닝 후 가명화 # -> 반환된 `session` 맵은 현재 요청 함수 스코프에만 격리되어 타 유저 요청과 절대 충돌하지 않음! cloak.pin_secret(req.customer_name, label="VIP_CUSTOMER") cloak.pin_secret(req.settlement_acc, label="SETTLEMENT_ACC") # 2) [페이로드 압축] 사내 ERP에서 조회한 무거운 JSON 데이터를 Mode B(-48.2%)로 경량화 slim_context = slimmer.to_mode_b(req.erp_context_json) full_prompt = f"[고객: {req.customer_name} / 계좌: {req.settlement_acc}]\n질문: {req.query}\n원장데이터:\n{slim_context}" masked_prompt, session = cloak.mask_text(full_prompt) # 3) [Top-K 도구 선별] 30개 전체 사내 도구 중 현재 질문에 필요한 Top-2 도구만 0.39ms 선별 route_decision = arbiter.route(req.query, top_k=2) selected_tool_names = [c["name"] for c in route_decision.get("candidates", [])] # 4) [외부 LLM 호출] 외부 OpenAI 서버에는 가명화된 프롬프트([[VAULT_PIN_...]])만 전송됨 response = openai_client.chat.completions.create( model="gpt-6-astra", messages=[{"role": "user", "content": masked_prompt}], ) raw_llm_answer = response.choices[0].message.content or "" # 5) [로컬 0.04ms 복원] 외부 LLM 응답이 도착하는 즉시 현재 요청의 `session`으로 실명·계좌 원상복구 final_answer = cloak.unmask_text(raw_llm_answer, session) return { "answer": final_answer, "routed_tools": selected_tool_names, "router_latency_ms": route_decision.latency_ms, }

8.3 [Node.js / TypeScript 표준] Next.js · Express 백엔드에서 공식 openai NPM 패키지로 1줄 연동

Node.js / TypeScript 백엔드 개발자는 별도의 패키지를 설치할 필요 없이, 기존에 사용하던 공식 openai SDK의 baseURL만 로컬 사이드카(http://localhost:8080/v1)로 지정하고 요청별 headers에 X-CDX-Pins와 X-CDX-Top-K를 넘기면 됩니다.

// 파일명: app/api/agent/route.ts (Next.js App Router / Express / NestJS 공통) import OpenAI from "openai"; // 1) 기존 공식 OpenAI SDK에서 baseURL만 로컬 CDX Docker Sidecar 주소로 지정! const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, baseURL: process.env.CDX_SIDECAR_URL || "http://localhost:8080/v1", defaultHeaders: { "X-CDX-License-Key": process.env.CDX_LICENSE_KEY!, "X-CDX-Slimmer": "true", "X-CDX-Top-K": "2", // 30개 도구 중 상위 2개만 자동 선별하여 LLM에 전송 (-93% 스키마 토큰 절감) }, }); export async function POST(req: Request) { const { customerName, accountNumber, userQuery, allErpTools } = await req.json(); // 2) 요청별 HTTP 헤더(X-CDX-Pins)로 현재 유저의 기밀 변수를 전달하면 // 사이드카가 외부 LLM 송출 전 가명화하고, 응답 수신 시 원래 값으로 자동 복원하여 반환합니다! const completion = await openai.chat.completions.create( { model: "gpt-6-astra", tools: allErpTools, // 30개 전체 도구를 그대로 넘겨도 사이드카가 Top-2만 선별 전송 messages: [ { role: "user", content: `${customerName} 고객님의 정산 계좌(${accountNumber}) 내역을 조회해줘: ${userQuery}`, }, ], }, { headers: { "X-CDX-Pins": `VIP_CUSTOMER=${customerName},SETTLEMENT_ACC=${accountNumber}`, }, } ); // completion.choices[0].message.content 에는 이미 사내 로컬 볼트에서 복원된 실명과 계좌가 들어 있습니다. return Response.json({ result: completion.choices[0].message.content }); }

8.4 [Java Spring Boot 표준] 금융·대기업 차세대 시스템 RestClient / Spring AI 사이드카 연동

금융권 및 대기업 표준 프레임워크인 Java Spring Boot 3.x 환경에서도 비즈니스 로직 변경 없이 HTTP 헤더 추가만으로 기밀 가명화(BYOS)와 도구 스키마 경량화를 즉시 적용할 수 있습니다.

// 파일명: CdxAgentGatewayService.java (Spring Boot 3.2+ RestClient 표준 예제) package com.enterprise.ai.service; import org.springframework.beans.factory.annotation.Value; import org.springframework.http.MediaType; import org.springframework.stereotype.Service; import org.springframework.web.client.RestClient; import java.util.Map; import java.util.List; @Service public class CdxAgentGatewayService { private final RestClient restClient; private final String openAiApiKey; private final String cdxLicenseKey; public CdxAgentGatewayService( @Value("${cdx.sidecar.url:http://localhost:8080}") String sidecarBaseUrl, @Value("${openai.api.key}") String openAiApiKey, @Value("${cdx.license.key}") String cdxLicenseKey) { this.openAiApiKey = openAiApiKey; this.cdxLicenseKey = cdxLicenseKey; this.restClient = RestClient.builder().baseUrl(sidecarBaseUrl).build(); } public String invokeSecuredAgent(String customerName, String settlementAcc, String prompt, List<Map<String, Object>> tools) { // 요청별 기밀 핀 헤더 구성 (외부 LLM 전송 전 가명화 & 응답 수신 시 로컬 자동 복원) String dynamicPins = String.format("VIP_CUSTOMER=%s,SETTLEMENT_ACC=%s", customerName, settlementAcc); Map<String, Object> requestBody = Map.of( "model", "gpt-6-astra", "tools", tools, "messages", List.of(Map.of("role", "user", "content", prompt)) ); return restClient.post() .uri("/v1/chat/completions") .contentType(MediaType.APPLICATION_JSON) .header("Authorization", "Bearer " + this.openAiApiKey) .header("X-CDX-License-Key", this.cdxLicenseKey) .header("X-CDX-Slimmer", "true") .header("X-CDX-Top-K", "2") .header("X-CDX-Pins", dynamicPins) .body(requestBody) .retrieve() .body(String.class); } }

9. 무중단 복구 및 비상 바이패스 가드 (Zero-Downtime Resilience)

상위 프레임워크의 버전 업데이트나 예기치 않은 런타임 예외 발생 시에도 프로덕션 서비스가 중단되지 않도록 보장하는 방어 설계 명세입니다.

9.1 3단계 다형성 폴백 체인 (Polymorphic Fallback Chain)

특정 실행 메서드 호출이 실패할 경우 예외를 발생시켜 중단하는 대신 차순위 표준 인터페이스로 자동 전환합니다:

invoke() ➔ [폴백] ➔ run() ➔ [폴백] ➔ __call__() ➔ [폴백] ➔ str() 원본 응답 반환

9.2 단일 변수 비상 바이패스 스위치

외부 라이브러리 변경으로 인해 래퍼 계층을 일시적으로 우회해야 할 경우, 애플리케이션 코드 수정 없이 플래그 1개로 즉시 원본 패스스루 모드로 전환합니다:

import cdx_dock.universal_adapter as cdx_guard # 모든 어댑터 래핑 및 압축을 우회하고 원본 에이전트 호출로 즉시 전환 cdx_guard._cdx_adapter_bypass = True

10. 사용자별 도입 아키텍처 & 엔터프라이즈 2주 PoC 체크리스트

도입 조직의 규모(초기 스타트업, 중견 SaaS 플랫폼, 금융·의료·공공 등 고규제 산업군, 대기업 폐쇄망·글로벌 OEM)에 따라 가장 빠르게 실측 ROI와 사내 보안 검토를 통과하는 표준 아키텍처 패턴과 PoC 검증 절차입니다.

10.1 4대 사용자 유형별 권장 도킹 아키텍처 매트릭스

사용자 그룹권장 배포 형태필수 장착 모듈 조합핵심 검증 지표 (KPI)
1. 초기 스타트업 / AI 에이전시 In-Process Python SDK (pip install cdx-dock) as_crewai_tool + DockSlimmer (Mode B) 이종 에이전트 연동 코드 1줄 단축 · 전달 토큰 40~55% 무손실 가역 절감(자체 실험)
2. 중견 B2B SaaS / 플랫폼 팀 Python SDK 또는 Docker Sidecar v2.1.0 CDXArbiter + CDX-CoT-Guard + TokenPack-10K 도구 스키마 토큰 85~93% 절감 · 추론 장기 작업 타임아웃 방지(자체 실험)
3. 금융·의료·공공 등 보안·규제 준수 조직 사내 프라이빗 VPC / 폐쇄망 Sidecar + SQLite3 BYOS CDXCloak (strict_pin_mode=True) + 사내 로컬 BYOS 볼트 외부 네트워크 모듈 import 0건 확인 · 지정 기밀 사내 격리 보관
4. 사내 폐쇄망(On-Premise Air-Gap) & 자체 서버 구축 팀 오프라인 하드웨어 노드 인증(MachineFingerprint) + 화이트라벨 바이너리 7대 전체 모듈 무제한 언락 + 사내 SIEM 감사 해시 연동 외부 통신 0건 오프라인 정품 인증 · 전사 에이전트 통합 비용/보안 거버넌스

10.2 엔터프라이즈 2주 무마찰 PoC 수행 순서 (30-Day Sandbox 활용)

# [Day 1~2] 1단계: 기존 코드 수정 없이 1줄 도킹 및 사내 정적 보안 점검 # - cdx_dock 오픈 어댑터(.py) 내 외부 통신 모듈(requests/urllib/httpx) import 0건 확인 # - CDXCloak 명시적 핀닝으로 실명·계좌 가명화 및 사내 SQLite3(.db) 로컬 저장 검증 # [Day 3~7] 2단계: 프로덕션 미러 트래픽에서 슬리밍·라우팅·CoT-Guard 실측 # - DockSlimmer Mode B 압축 및 CDXArbiter Top-K 도구 라우팅 지연시간(< 1.0ms) 측정 # [Day 8~14] 3단계: PoC 실측 데이터 기반 사내 결재 보고서 & BYOS 원본 데이터 그대로 추출 from cdx_dock import CDXInternalReportBuilder reporter = CDXInternalReportBuilder(storage_path="./enterprise_vault.db", persist_telemetry=True) reporter.save_report("cfo_roi_settlement_report", "./reports/poc_measured_tokens.md", use_live_telemetry=True) reporter.export_byos_raw_data("./reports/poc_byos_raw_records.csv") # 가감 없는 BYOS 원본 레코드 CSV 반출

11. AI 코딩 에이전트 & 멀티 서브에이전트 토큰 절감 실전 가이드

AI 코딩 에이전트(Claude Code, Cursor, Cline, Windsurf 등)나 자체 멀티 서브에이전트(Planner ➔ Coder ➔ Reviewer)를 운영할 때 발생하는 도구 스키마 반복 주입·컨텍스트 중복 복사(O(N²))·추론 루프 토큰 소모를 코드 재작성 없이 줄이는 3가지 실전 연동 예시입니다.

11.1 왜 멀티·코딩 에이전트는 일반 채팅보다 10~15배 많은 토큰을 소모하는가? (Before vs After)

아래 표는 40개 MCP 도구 + 4단 서브에이전트 협업 작업 1건을 수행할 때 각 구간에서 낭비되는 토큰과 cdx-dock v2.1.0 장착 후 경량화 구조를 비교한 아키텍처 시뮬레이션 예시입니다. (실제 운영 환경에서의 호출당 절감 토큰은 로컬 DockTelemetry 원장에 100% 실측치로 기록됩니다.)

토큰 누수 구간 미적용 시 (Before) CDX-Dock 적용 후 (After) 적용 엔진 및 절감 원리
① 40개 MCP 도구 스키마 매 턴·서브에이전트마다 전체 스키마 반복 전송 (~18,000 tok) ~1,400 tok
(약 88~92% 절감)
CDXArbiter가 현재 지시에 필요한 Top-2 도구만 < 1ms 선별 + MCPOptimizer가 중첩 $defs 설명 압축
② 서브에이전트 간 코드·로그 전달 앞단 에이전트의 대화·파일 원문을 다음 에이전트에 통복사 (~42,000 tok) ~14,500 tok
(약 45~65% 절감)
CDXTokenPack10K 로컬 공유 팩에서 핵심 스펙만 인출(top_k=2) + JSON 응답 DockSlimmer Mode B 경량화
③ <think> 추론 무한 공회전 컴파일 오류·모호한 조건에서 동일 추론 반복 후 타임아웃 (~22,000 tok) ~3,900 tok
(헛도는 루프 조기 절단)
CDX-CoT-Guard가 <think> 동어반복 징후 감지 즉시 추론 블록을 안전 종료하고 본 답변 유도
④ .env · API Key · DB 계정 노출 에이전트가 설정 파일을 읽는 순간 외부 LLM 서버로 평문 전송 외부 유출 0 Byte
(로컬 0.04ms 자동 복원)
CDXCloak이 송출 전 [[VAULT_PIN_...]] 토큰으로 가명화하고 응답 수신 즉시 원본 값으로 복원

11.2 패턴 A [코드 수정 0줄] — AI 코딩 에이전트(Cursor · Claude Code · Cline) 로컬 사이드카 연결

기존 코딩 에이전트나 CLI 도구의 소스코드를 수정할 필요 없이, 개발자 PC 또는 사내 게이트웨이에 Docker Sidecar v2.1.0 컨테이너를 띄우고 API Base URL 환경변수 1줄만 지정하면 도구 스키마 다이어트·페이로드 압축·시크릿 가명화가 즉시 작동합니다.

# [1] 로컬 PC 또는 팀 개발 서버에 CDX Sidecar v2.1.0 기동 (30일 무료 샌드박스 자동 활성) docker run -d --name cdx-coding-proxy -p 8080:8080 \ -v $(pwd)/cdx_byos:/data \ -e UPSTREAM_LLM_BASE_URL="https://api.openai.com/v1" \ cdxno1/cdx-a2a-sidecar:2.1.0 # [2] 코딩 에이전트(CLI / IDE 터미널) 실행 전 Base URL만 로컬 사이드카로 지정! export OPENAI_BASE_URL="http://localhost:8080/v1" # (선택) 요청 헤더를 지원하는 에이전트 설정 파일에서는 Top-K 도구 수와 보호할 시크릿을 직접 지정 가능 # X-CDX-Slimmer: true # X-CDX-Top-K: 3 # X-CDX-Pins: PROD_DB_PASS=my_super_secret_pw,STRIPE_LIVE_KEY=sk_live_xxx

11.3 패턴 B [MCP 도구 다이어트] — 40개 MCP 서버 스키마를 Top-K만 선별해 90% 줄이기

코딩 에이전트에 Git, DB, Kubernetes, Jira, Slack 등 수십 개 MCP 도구를 한꺼번에 연결하면 아무 질문도 하기 전에 매 턴 15,000+ 토큰이 도구 설명으로 소진됩니다. create_arbiter와 MCPOptimizer, wrap_anthropic을 결합하면 현재 작업에 꼭 필요한 도구만 압축 주입합니다.

from anthropic import Anthropic from cdx_dock import create_arbiter, MCPOptimizer, wrap_anthropic # [1] 사내 MCP 도구 카탈로그 등록 (최초 1회 로컬 SQLite/JSON 저장) arbiter = create_arbiter(storage_path="./dev_mcp_tools.db") mcp_opt = MCPOptimizer() # [2] Anthropic 클라이언트를 1줄로 래핑 (자동 스키마 경량화 + 스트리밍 가명화 복원 활성화) client = wrap_anthropic(Anthropic(), mcp_opt=mcp_opt, slim_prompts=True) def run_coding_turn(task_prompt: str, all_mcp_schemas: list[dict]): # 40개 전체 MCP 도구를 등록하고 현재 코딩 지시에 필요한 상위 2개만 ~0.4ms 만에 선별! if not arbiter.tools: arbiter.register_tools(all_mcp_schemas) decision = arbiter.route(task_prompt, top_k=2) keep_names = {c["name"] for c in decision.get("candidates", [])} active_tools = [t for t in all_mcp_schemas if t.get("name") in keep_names] or all_mcp_schemas[:2] # 선별된 2개 스키마도 wrap_anthropic 내부 MCPOptimizer가 불필요한 설명·중첩 $defs를 추가 압축하여 전송 resp = client.messages.create( model="claude-mythos-5-2", max_tokens=2048, tools=active_tools, messages=[{"role": "user", "content": task_prompt}], ) return resp

11.4 패턴 C [서브에이전트 협업 다이어트] — Planner ➔ Coder ➔ Reviewer 대화 통복사 제거

멀티 서브에이전트 파이프라인에서 토큰이 제곱(O(N²))으로 불어나는 가장 큰 원인은 앞단 에이전트가 읽은 수만 자의 파일·로그를 뒷단 서브에이전트 프롬프트에 그대로 복사해 넣기 때문입니다. CDXTokenPack10K 로컬 공유 폴더에 핵심 설계 스펙만 적재하고, 하위 에이전트는 필요한 조각만 < 1ms로 꺼내 쓰면 토큰 소모가 선형 이하로 줄어듭니다.

from openai import OpenAI from cdx_dock import wrap_openai, CDXCloak, CDXTokenPack10K, DockSlimmer, dock_telemetry # [1] 팀 서브에이전트가 함께 참조할 로컬 10K 공유 메모리 팩 & 기밀 볼트 초기화 shared_pack = CDXTokenPack10K(pack_dir="./subagent_shared_pack") cloak = CDXCloak(storage_path="./subagent_vault.db") slimmer = DockSlimmer() # 실수로 코드/환경변수 내 시크릿이 외부 LLM에 나가지 않도록 핀 등록 후 OpenAI 클라이언트 1줄 래핑 cloak.pin_secret("rk_prod_9988776655", label="INTERNAL_API_KEY") llm = wrap_openai(OpenAI(), cloak=cloak, slimmer=slimmer, slim_prompts=True) # [2] Planner 에이전트: 전체 파일 원문을 넘기는 대신 핵심 변경 규격만 공유 팩에 저장 shared_pack.ingest( "CRITICAL SPEC: auth_middleware.py JWT 만료 시간을 900s로 단축하고 refresh_token 회전 검증 추가", metadata={"stage": "planner", "target": "auth_middleware.py"}, ) # [3] Coder / Reviewer 서브에이전트: 수만 자 앞단 로그 복사 없이 필요한 핵심 스펙 Top-2만 <1ms 인출! recalled = shared_pack.recall("auth_middleware JWT refresh_token 수정 규격", top_k=2) compact_context = "\n".join(item["text"] for item in recalled["items"]) slim_ast_json = slimmer.to_mode_b({"file": "auth_middleware.py", "exports": ["verify_jwt", "rotate_refresh"]}) coder_resp = llm.chat.completions.create( model="gpt-6-astra", messages=[ {"role": "system", "content": f"핵심 설계 규격:\n{compact_context}\nAST 요약:{slim_ast_json}"}, {"role": "user", "content": "위 규격에 맞춰 verify_jwt와 rotate_refresh 패치 코드만 간결히 작성해줘."}, ], ) # [4] 방금 실행으로 실제 몇 토큰이 절감되었는지 로컬 실측 원장에서 즉시 확인 print("절감 요약:", dock_telemetry.get_summary()["net_tokens_delta"])

12. [AI-Ready] 전체 엔진 · 옵션 · API 마스터 레퍼런스 (v2.1.0)

개발자 또는 AI 코딩 에이전트(Cursor · Claude Code · Antigravity)가 이 문서만으로 어떤 엔진이 기본 포함이고 어떤 기능이 상위 플랜/옵션인지 0% 혼동 없이 파악하고, 단 한 번에 프로덕션 코드에 적용할 수 있도록 전 공개 API와 옵션을 집대성한 레퍼런스입니다.

12.1 플랜별 기본 엔진 vs 선택형 모듈·옵션 전체 매핑표

엔진 / 클래스구분 (기본 vs 옵션)지원 플랜핵심 역할 및 실측 효과
as_crewai_tool / as_langchain_tool / as_autogen_agent / bridge / adapt / @dock기본 코어 (Engine 01)전 티어 (Sandbox~Enterprise)이종 프레임워크 1줄 연결 + CDXHermesDock SKILL.md Top-K 선별
DockSlimmer (to_mode_b / to_mode_a / CDXTAB1:)기본 코어 (Engine 02)전 티어일반 JSON Mode B 압축 + 4행 이상 균일 JSON 표 CDX-Tab 54.7~66% 무손실 압축 (4중 안전장치)
CDXArbiterEngine (다국어 v2.1)기본 코어 (Engine 03)전 티어EN·KO·JA·ES·DE·FR 질의 → 영문 SaaS API <1.3ms 0-LLM 라우팅 (BYOS SQLite/JSON CRUD)
MCPOptimizer · AgentDock · wrap_openai / wrap_anthropic / wrap_gemini기본 코어 / 래퍼전 티어MCP 스키마 다이어트, 로컬 멀티에이전트 버스, 공식 LLM SDK 1줄 자동 래핑
CDXCloak · CDXDockShield보안 볼트 (Engine 05)Sandbox 체험 / 애드온 / Growth+ 바우처명시적 기밀 핀닝(pin_secret) 및 정규식 기반 로컬 마스킹/복원 (외부 전송 0B)
CDXCoTMiddleware (CDX-CoT-Guard)추론 가드 (Engine 06)Sandbox 체험 / 애드온<think> 무한 루프 조기 절단 및 사내 vLLM KV-Cache 메모리 급증 억제
CDXTokenPack10K (10K 단일)공유 기억 (Engine 07A)Sandbox 체험 / Starter~Enterprise외부 Vector DB 없는 pack_dir 로컬 10,000토큰 8개 국어 장기 기억 공유
CDXVaultPack2K · CDXDualTokenPack (10K ∥ 2K)병렬 암호화 금고 (Engine 07B)Sandbox 체험 · Growth ($1,490)+ 정식 포함
(Starter: Safe Pass-Through)
100% 고객 로컬 Zero-Knowledge AES-256-GCM + AAD, PCI CVV 즉시 소각, 1-Bit RBAC

12.2 CDXVaultPack2K 역할별 금고 출입 권한(1-Bit RBAC) & 주요 설정 옵션

왜 필요한가요? AI 서비스 안에는 외부 클라우드 AI(두뇌)와 사내 배송·환불·결제 툴이 함께 움직입니다. 1-Bit RBAC은 각 프로그램에 직책별 디지털 출입증(1비트 스위치)을 발급해 자기 업무에 꼭 필요한 금고 서랍만 열게 하는 장치입니다.
실제 동작 흐름 예: 고객이 채팅창에 집 주소 + 카드번호를 함께 입력하면 → 외부 클라우드 AI(ROLE_CLOUD_PLANNER)는 가짜 번호표만 보고 → 배송 툴(ROLE_ADDRESS_TOOL)은 주소만 꺼내며(카드 접근 시 자동 차단) → 결제 툴(ROLE_PAYMENT_EXECUTOR)은 고객 승인(user_consent=True)이 있을 때만 카드번호를 고객사 로컬에서 찰나에 복호화합니다.

권한 상수 (비트 마스크)허용 카테고리user_consent=True 필수권장 호출 주체
ROLE_CLOUD_PLANNER (0x00)없음 (항상 차단)항상 거부외부 클라우드 LLM 플래너 (원본 평문 0% 노출)
ROLE_ADDRESS_TOOL (0x01)ADDRESS, PHONE, EMAIL선택배송 조회 · 알림 발송 로컬 툴
ROLE_BILLING_TOOL (0x02)BANK선택환불 계좌 · 정산 조회 로컬 툴
ROLE_PAYMENT_EXECUTOR (0x04)CARD, RRN필수결제 실행 로컬 툴 (사용자 승인 시 찰나 복호화)
ROLE_AUTH_EXECUTOR (0x08)API_KEY, LICENSE필수외부 API 인증 실행 로컬 툴

주요 생성자 옵션: CDXVaultPack2K(vault_dir="./vault", master_key=kms_32bytes, strict_tier=True) — 고객사 KMS에서 32바이트 master_key를 직접 주입할 수 있으며, Starter 플랜에서 호출 시 앱 중단 없이 기본 마스킹으로 통과하면서 반환 메타데이터에 vault_tier_upgrade_required=True를 표시합니다.

12.3 [AI 에이전트 복사용] 프로덕션 풀스택 통합 템플릿 (다국어 아비터 + CDX-Tab + VaultPack-2K)

import os from cdx_dock import ( CDXArbiterEngine, DockSlimmer, CDXVaultPack2K, CDXDualTokenPack, ROLE_CLOUD_PLANNER, ROLE_ADDRESS_TOOL, ROLE_BILLING_TOOL, ROLE_PAYMENT_EXECUTOR, ROLE_AUTH_EXECUTOR, ) # 1) 다국어 0-LLM SaaS 도구 라우터 (EN/KO/JA/ES/DE/FR -> 영문 API) arbiter = CDXArbiterEngine(strict_license=False) arbiter.register_tools([ {"name": "stripe_create_refund", "description": "Refund a customer payment charge on Stripe."}, {"name": "google_calendar_book", "description": "Schedule a meeting event on Google Calendar."}, ]) route_ko = arbiter.route("구글 캘린더에 내일 회의 일정 잡아줘", top_k=2) # -> route_ko["tool_name"] == "google_calendar_book" # 2) 균일한 JSON 표 자동 CDX-Tab 무손실 압축 (불규칙 JSON은 자동 Mode-B 안전 우회) slimmer = DockSlimmer() sample_rows = [{"order_id": i, "status": "COMPLETED", "region": "ap-northeast-2"} for i in range(10)] slim_payload = slimmer.to_mode_b(sample_rows) # "CDXTAB1:..." exact_rows = slimmer.to_mode_a(slim_payload) # 100% exact roundtrip # 3) 고객사 KMS 32B 키 주입형 로컬 VaultPack-2K 단독 & DualTokenPack(10K || 2K) 통합 kms_key = os.urandom(32) # 프로덕션에서는 AWS KMS / HashiCorp Vault에서 32바이트 키 로드 vault = CDXVaultPack2K(vault_dir="./local_vault", master_key=kms_key, strict_tier=True) masked_txt, v_meta = vault.mask_and_vault_text("카드 4532-1122-3344-5566 CVV=831 이메일 ops@acme.io") if v_meta.get("vault_tier_upgrade_required"): print("Starter 티어 Safe Pass-Through 동작 — Growth 이상에서 영구 AES-256-GCM 금고 활성화") else: card_h = [h for h in v_meta["handles"] if ":CARD:" in h][0] email_h = [h for h in v_meta["handles"] if ":EMAIL:" in h][0] assert not vault.resolve_handle(card_h, ROLE_CLOUD_PLANNER, True)["authorized"] assert not vault.resolve_handle(card_h, ROLE_ADDRESS_TOOL, True)["authorized"] assert vault.resolve_handle(email_h, ROLE_ADDRESS_TOOL, False)["authorized"] assert vault.resolve_handle(card_h, ROLE_PAYMENT_EXECUTOR, True)["authorized"]