Python SDK & API Reference
cdx-a2a-slimmer 패키지의 설치, 동기·비동기 파이프라인, 코어 클래스 설정, 실시간 텔레메트리, Pydantic 연동 및 무중단 예외 처리 레퍼런스입니다.
1. 패키지 설치 및 환경 요구사항
Python 3.9 이상의 환경을 지원하며, 외부 런타임 종속성(Zero-dependency) 없는 순수 C/Python AST 엔진으로 구동됩니다.
# PyPI 공식 패키지 설치
pip install cdx-a2a-slimmer
2. API 키 인증 및 환경변수 설정 (Authentication & API Keys)
CDX 사이드카 프록시 및 엔터프라이즈 SDK는 발급된 Secret API Key(cdx_live_sk_...)를 기반으로 제로 트러스트(Zero-Trust) 인증을 수행합니다.
•
API 키 발급처: 개발자 콘솔 > 5. 프록시 및 API 키 관리에서 즉시 발급 및 무중단 롤링 지원.
•
HTTP 인증 헤더: Authorization: Bearer cdx_live_sk_... 표준 RFC 6750 Bearer 규격 준수.
•
보안 보관 원칙: API 키를 프론트엔드 코드나 공개 저장소에 절대 노출하지 마시고,
.env 또는
Enterprise Secret Vault(AWS Secrets Manager, HashiCorp Vault, Azure Key Vault)에 보관하십시오.
# [1] 터미널 / 환경변수 등록 (.env)
export CDX_API_KEY="cdx_live_sk_여기에_발급받은_키_입력" # 👈 콘솔에서 발급받은 실제 Secret Key 입력
export CDX_PROXY_URL="http://127.0.0.1:8090/v1" # 👈 로컬 사이드카 또는 VPC 사설 엔드포인트
# [2] Python SDK 초기화 시 환경변수 주입 (하드코딩 방지)
import os
from cdx_a2a_slimmer import CDXA2ATokenSlimmer
slimmer = CDXA2ATokenSlimmer(
license_key=os.getenv("CDX_API_KEY")
)
3. 동기식 기본 호출: slim(payload: dict) -> dict
기존 에이전트 요청 페이로드를 slim()으로 감싸 호출하면 0.08ms 내에 무손실 정제되어 전송됩니다.
from cdx_a2a_slimmer import slim
from openai import OpenAI
client = OpenAI()
# [1] 기존 멀티 에이전트 요청 딕셔너리
payload = {
"model": "gpt-5-preview",
"messages": [
{"role": "system", "content": "사내 코드 리뷰 전문 에이전트입니다."},
{"role": "user", "content": "Pull Request 변경점을 분석해줘."}
],
"tools": my_enterprise_tools # 사내 API/DB 도구 스키마 목록
}
# [2] slim() 래핑 후 호출 (0.08ms 초저지연 처리, 토큰 20~30% 절감)
slimmed_payload = slim(payload)
response = client.chat.completions.create(**slimmed_payload)
print(response.choices[0].message.content)
4. 비동기식 고성능 파이프라인: async_slim(payload: dict) -> dict
FastAPI, Asyncio, LangGraph 비동기 에이전트 워크플로우에서 논블로킹(Non-blocking)으로 대규모 동시성 요청을 처리합니다.
import asyncio
from cdx_a2a_slimmer import async_slim
from openai import AsyncOpenAI
client = AsyncOpenAI()
async def run_agent_workflow(payload: dict):
# [1] 논블로킹 비동기 AST 슬리밍
slimmed = await async_slim(payload)
# [2] 실시간 스트리밍 LLM 호출
stream = await client.chat.completions.create(**slimmed, stream=True)
async for chunk in stream:
content = chunk.choices[0].delta.content or ""
print(content, end="", flush=True)
# 실행
asyncio.run(run_agent_workflow(payload))
5. 엔터프라이즈 코어 클래스: CDXA2ATokenSlimmer
대규모 동시성 인메모리 파서 인스턴스를 초기화하고, 라이선스 키 인증 및 사내 전용 스키마 화이트리스트를 설정합니다.
from cdx_a2a_slimmer import CDXA2ATokenSlimmer
# [1] 전용 인메모리 슬리머 인스턴스 생성
slimmer = CDXA2ATokenSlimmer(
license_key="cdx_live_enterprise_sk_...", # Open Beta / Free 사용 시 None
auto_canonicalize=True, # RFC 8259 표준 사전순 정렬
preserve_keys=["company_auth_id"], # 설명문 정제에서 100% 예외 처리할 특수 키
strip_docstring_redundancy=True # 중복 설명문 결정론적 AST 정제
)
# [2] 인스턴스 메서드로 슬리밍 수행
slimmed_payload = slimmer.slim(payload)
| 생성자 파라미터 | 타입 | 기본값 | 설명 |
| license_key | Optional[str] | None | 상용 라이선스 Ed25519 인증 키 (미지정 시 오픈 베타 무료 티어 자동 적용) |
| auto_canonicalize | bool | True | 도구 정의를 결정론적 사전순으로 정렬하여 RFC 8259 JSON 무결성 및 호환성 보장 |
| preserve_keys | Optional[List[str]] | [] | 스키마 설명문 축약에서 100% 원본 보존할 기업 내부 필수 파라미터 키 목록 |
| strip_docstring_redundancy | bool | True | AST 수준에서 도구 설명문의 중복 구문을 정제하고 타입 명세만 무손실 보존 |
6. 실시간 텔레메트리 메트릭 수집: slimmer.slim_payload()
정제된 페이로드와 함께 원본/정제 바이트 수, 실측 절감률, 처리 지연시간(ms)이 포함된 메트릭 딕셔너리를 반환합니다.
# [1] 슬리밍 페이로드와 실시간 텔레메트리 동시 추출
slimmed_payload, telemetry = slimmer.slim_payload(raw_payload)
# [2] 실측 모니터링 로그 출력
print(f"• 처리 지연시간 : {telemetry['latency_ms']} ms")
print(f"• 페이로드 크기 : {telemetry['raw_bytes']}B ➔ {telemetry['slim_bytes']}B")
print(f"• 실측 토큰 절감 : {telemetry['reduction_percent']}%")
7. 복합 도구 호출(Multi-Tool Calling) & Pydantic v2 연동
사내 50개 이상의 복합 DB/API 도구 호출 시 Pydantic v2 모델을 결합하여 사용하는 실전 예제입니다.
from pydantic import BaseModel, Field
from cdx_a2a_slimmer import slim
# [1] Pydantic v2 도구 인자 모델 정의
class SQLQueryArgs(BaseModel):
query: str = Field(description="실행할 ANSI SQL 쿼리문")
timeout_sec: int = Field(default=30, description="최대 타임아웃(초)")
# [2] OpenAI 표준 Function Tool 등록
sql_tool = {
"type": "function",
"function": {
"name": "execute_sql",
"description": "사내 분석 데이터베이스 쿼리를 실행합니다.",
"parameters": SQLQueryArgs.model_json_schema()
}
}
# [3] 요청 페이로드 슬리밍 (Pydantic 타입과 제약조건 완벽 보존)
payload = {
"model": "deepseek-r1",
"messages": [{"role": "user", "content": "3분기 매출 지표 조회"}],
"tools": [sql_tool]
}
safe_slimmed = slim(payload)
8. 예외 처리 및 무중단 페일오픈(Fail-Open) 안전 가이드
비정형 JSON이나 파싱 오류 발생 시에도 요청이 중단되지 않고 원본을 안전하게 전송하는 엔터프라이즈 페일오픈(Fail-Open) 패턴입니다.
import logging
from cdx_a2a_slimmer import slim, CDXException
# [Fail-Open 패턴] 예외 발생 시에도 서비스 중단 없이 원본으로 즉시 전송
try:
ready_payload = slim(raw_payload)
except CDXException as err:
logging.warning(f"CDX 파싱 예외 발생, 원본 페이로드로 즉시 폴백: {err}")
ready_payload = raw_payload
response = client.chat.completions.create(**ready_payload)
200+ 에이전트 메타데이터 태깅 및 모달리티 규격
CDX 프록시가 멀티 에이전트 트래픽을 관제 콘솔에서 【노드 ID / 에이전트명 / 소속 스웜 / 타겟 모델 / 데이터 모달리티】로 정밀 식별 및 분류하는 기술 메커니즘과 태깅 표준 규격서입니다.
1. 5대 관제 필드 수집 및 자동 판별 메커니즘
| 관제 필드 | 수집 경로 | 자동 판별 여부 | 기술 메커니즘 설명 |
| 타겟 모델 (Model) |
HTTP Body JSON |
100% 자동 |
표준 요청의 {"model": "gpt-5-preview"} 키를 0.01ms 내에 실측 추출 |
| 데이터 형식 (Modality) |
CDX AST Engine |
100% 자동 |
페이로드 구조를 분석하여 CoT 추론, Tool JSON, Multi-Turn, Raw Text 4단계 자동 분류 |
| 노드 ID & 에이전트명 |
Header / User 필드 |
헤더 or 자동 폴백 |
X-Agent-ID 헤더 또는 user 필드로 지정. 미지정 시 세션 IP 기반 가상 태깅 |
| 소속 스웜 (Swarm Group) |
Header / User 필드 |
헤더 or 자동 폴백 |
X-Swarm-Group (engineering, research, sre, crm) 분류. 미지정 시 자동 클러스터링 |
2. 데이터 형식(Modality) 4종 자동 분류 규칙
• [CoT Reasoning Traces] 장기 사유 추론 로그 (평균 44.5% 감축): reasoning_content 필드 또는 <thought> 태그가 감지될 때 자동 태깅.
• [Tool Call & JSON AST] 도구 호출 스키마 (평균 32.1% 감축): tools, tool_calls, function_call 정의 스키마가 포함될 때 자동 태깅.
• [Multi-Turn Context] 다중 대화 맥락 (평균 28.4% 감축): messages 배열 길이가 6 이상인 멀티턴 대화 시 자동 태깅.
• [Raw Text & Markdown] 원문 텍스트 (평균 21.2% 감축): 단일 텍스트 및 마크다운 질의응답 시 기본 태깅.
3. 에이전트 메타데이터 전송 실전 코드 예시
[Python SDK / OpenAI Client] 커스텀 헤더 또는 user 필드 주입:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8080/v1",
api_key="cdx_live_enterprise_..."
)
# 방법 1: extra_headers를 통한 정밀 스웜 태깅 (권장)
response = client.chat.completions.create(
model="gpt-5-preview",
messages=[{"role": "user", "content": "AST 구문 분석"}],
extra_headers={
"X-Agent-ID": "node-042",
"X-Agent-Name": "Code-Reviewer",
"X-Swarm-Group": "engineering" # engineering, research, sre, crm
}
)
# 방법 2: OpenAI 표준 user 필드 활용 (콜론 구분)
response = client.chat.completions.create(
model="claude-3.7-sonnet",
messages=[{"role": "user", "content": "SRE 인프라 점검"}],
user="sre:node-014:LeadSRE"
)
[HTTP / cURL 직접 호출] HTTP 헤더 추가:
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer cdx_live_enterprise_..." \
-H "X-Agent-ID: node-089" \
-H "X-Agent-Name: SQL-Synthesizer" \
-H "X-Swarm-Group: engineering" \
-d '{
"model": "deepseek-r1",
"messages": [{"role": "user", "content": "SELECT * FROM telemetry"}]
}'
멀티 에이전트 프레임워크 연동 레시피
LangGraph, CrewAI, AutoGen, LlamaIndex 및 사내 vLLM 서버 환경에서 단 1~2줄 설정으로 토큰을 최대 31.55% 절감하는 실전 연동 코드 모음입니다.
1. LangGraph (LangChain) 엔터프라이즈 그래프 연동
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, END
llm = ChatOpenAI(
model="gpt-5-preview",
base_url="http://localhost:8080/v1",
api_key="sk-...",
default_headers={"X-Agent-ID": "node-001", "X-Swarm-Group": "engineering"}
)
2. CrewAI 멀티 에이전트 스웜 연동
from crewai import Agent, Crew
from langchain_openai import ChatOpenAI
slimmer_llm = ChatOpenAI(
model="claude-3.7-sonnet",
base_url="http://localhost:8080/v1",
default_headers={"X-Agent-ID": "node-002", "X-Swarm-Group": "research"}
)
researcher = Agent(role="Senior Market Analyst", goal="Analyze trends", llm=slimmer_llm)
3. Microsoft AutoGen 대화형 에이전트 연동
import autogen
llm_config = {
"config_list": [{
"model": "deepseek-r1",
"base_url": "http://localhost:8080/v1",
"api_key": "sk-...",
"extra_headers": {"X-Agent-ID": "node-003", "X-Swarm-Group": "sre"}
}]
}
쿠버네티스(K8s) 사이드카 및 도커 배포 가이드
기존 애플리케이션 코드를 수정하지 않고 네트워크 레벨에서 투명(Transparent)하게 작동하는 50MB 초경량 도커 컨테이너, 쿠버네티스 파드(Pod) 사이드카 및 클러스터 데몬셋(DaemonSet) 공식 배포 명세서입니다.
1. Docker 단일 컨테이너 실행 (개발 및 테스트용)
단 1줄의 Docker 실행 명령어로 로컬 또는 독립 VM 인스턴스에서 CDX 사이드카 프록시를 즉시 구동합니다.
docker run -d \
--name cdx-slimmer \
-p 8080:8080 \
-e TARGET_UPSTREAM="https://api.openai.com" \
-e CDX_LICENSE_KEY="cdx_live_sk_여기에_발급받은_키_입력" \
-e LOG_LEVEL="info" \
--restart unless-stopped \
cantorlabs/cdx-a2a-sidecar:v1.0.0-beta
2. Kubernetes 파드(Pod) 사이드카 배포 명세서 (deployment.yaml)
동일한 Pod 내에서 메인 AI 에이전트 컨테이너와 CDX 사이드카가 localhost:8080 네트워크를 공유하여 지연시간 0.05ms 미만으로 초고속 슬리밍 통신을 수행합니다.
apiVersion: apps/v1
kind: Deployment
metadata:
name: enterprise-agent-fleet
labels:
app: agent-worker
spec:
replicas: 3
selector:
matchLabels:
app: agent-worker
template:
metadata:
labels:
app: agent-worker
spec:
containers:
# [1] 메인 AI 에이전트 애플리케이션 컨테이너
- name: ai-agent-app
image: mycorp/agent-service:v2.4.0
env:
- name: OPENAI_BASE_URL
value: "http://127.0.0.1:8080/v1" # 👈 로컬 루프백 사이드카로 투명 라우팅
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: cdx-credentials
key: api-key
resources:
requests:
cpu: "500m"
memory: "512Mi"
# [2] CDX 초경량 토큰 슬리머 사이드카 컨테이너 (50MB)
- name: cdx-sidecar
image: cantorlabs/cdx-a2a-sidecar:v1.0.0-beta
imagePullPolicy: IfNotPresent
ports:
- containerPort: 8080
name: proxy-http
env:
- name: TARGET_UPSTREAM
value: "https://api.openai.com"
- name: CDX_LICENSE_KEY
valueFrom:
secretKeyRef:
name: cdx-credentials
key: license-key
- name: ENABLE_PROMETHEUS
value: "true"
resources:
requests:
cpu: "50m"
memory: "32Mi"
limits:
cpu: "200m"
memory: "64Mi"
livenessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 3
periodSeconds: 10
readinessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 2
periodSeconds: 5
3. Docker Compose 로컬 멀티 컨테이너 구성 (docker-compose.yml)
개발 환경에서 에이전트 애플리케이션과 CDX 사이드카, 모니터링 수집기를 원클릭으로 오케스트레이션합니다.
version: '3.8'
services:
# CDX 사이드카 프록시
cdx-proxy:
image: cantorlabs/cdx-a2a-sidecar:v1.0.0-beta
container_name: cdx-slimmer-proxy
ports:
- "8080:8080"
environment:
- TARGET_UPSTREAM=https://api.openai.com
- CDX_LICENSE_KEY=${CDX_API_KEY}
- LOG_LEVEL=info
restart: always
# 사내 AI 에이전트 서비스
agent-service:
build: .
depends_on:
- cdx-proxy
environment:
- OPENAI_BASE_URL=http://cdx-proxy:8080/v1
- OPENAI_API_KEY=${CDX_API_KEY}
4. 사이드카 환경변수 및 리소스 설정 명세표
컨테이너 기동 시 주입할 수 있는 표준 환경변수 및 권장 리소스 제한 사양입니다.
| 환경변수 키 | 기본값 | 필수 여부 | 상세 설명 |
| TARGET_UPSTREAM | https://api.openai.com | 필수 | 최종 전달할 LLM 제공사(OpenAI, Anthropic, Gemini, 사내 vLLM) 원본 URL |
| CDX_LICENSE_KEY | None (Open Beta) | 선택 | 엔터프라이즈 라이선스 인증 키 (미입력 시 오픈 베타 티어 자동 적용) |
| CDX_PORT | 8080 | 선택 | 사이드카 인바운드 수신 TCP 포트 |
| ENABLE_PROMETHEUS | true | 선택 | /metrics 엔드포인트를 통한 Prometheus 시계열 메트릭 노출 활성화 |
| LOG_LEVEL | info | 선택 | 로그 출력 레벨 (debug, info, warn, error) |
5. Cloudflare Pages & Supabase 프로덕션 클라우드 아키텍처 배포
CDX 포털 및 글로벌 API는 Cloudflare Anycast 엣지 네트워크와 Supabase 멀티테넌트 PostgreSQL (RLS)을 기반으로 고가용성·무마찰 서빙됩니다.
• 엣지 레이어 (Edge CDN & WAF): Cloudflare Pages 및 330+ Anycast PoPs를 통해 전 세계 < 15ms TTFB 보장 및 L3/L4/L7 DDoS·봇 침투(Bot Fight Mode) 원천 차폐.
• 인증 & 원장 레이어 (IAM & Database): Supabase Auth (FIDO2/Passkey, GitHub/Google OAuth, SAML SSO) 및 Strict Row Level Security(RLS)로 조직 간 데이터 100% 암호 격리.
• 무흔적 소각 원칙 (Zero Data Retention): 고객사의 프롬프트 전문은 DB에 저장되지 않으며, 오직 수학적 절감 토큰 수치와 HMAC 영수증만 암호화 기록됩니다.
# [Step 1] Supabase PostgreSQL 스키마 및 RLS 정책 적용
supabase db push --file supabase_schema.sql
# [Step 2] Cloudflare Pages 프로덕션 원클릭 글로벌 엣지 배포 (cdxengine.com)
npx wrangler pages deploy . --project-name=cdx-engine-portal --branch=main
Prometheus, Grafana & OpenTelemetry 모니터링
CDX 사이드카의 GET /metrics 엔드포인트를 통해 실시간 토큰 절감액, P99 인메모리 지연시간, 동시성 세션 및 스웜별 상태 지표를 Grafana, Datadog, OpenTelemetry와 연동하는 공식 엔터프라이즈 모니터링 가이드입니다.
1. Prometheus 스크랩 설정 (prometheus.yml)
사이드카 프록시의 8080 포트에서 10s 주기로 텔레메트리 메트릭을 수집하도록 설정합니다.
scrape_configs:
- job_name: 'cantor-cdx-200-fleet'
scrape_interval: 10s
metrics_path: '/metrics'
static_configs:
- targets: ['localhost:8080']
labels:
environment: 'production'
region: 'ap-northeast-2'
2. 핵심 익스포트 메트릭 명세 (Core Metrics Reference)
CDX 엔진이 실시간으로 노출하는 5대 핵심 시계열 메트릭 명세서입니다.
| 메트릭 이름 | 타입 | 주요 레이블 (Labels) | 설명 및 단위 |
| cdx_tokens_pruned_total |
Counter |
swarm, model, modality |
누적 정제·절감된 토큰 총량 (Tokens) |
| cdx_reduction_ratio |
Gauge |
swarm, agent_id |
실시간 토큰 감축률 (0.00 ~ 1.00, 실측 0.20 ~ 0.3155) |
| cdx_proxy_latency_seconds |
Histogram |
le, endpoint |
CDX 인메모리 슬리밍 처리 지연시간 (P50, P90, P99 초 단위) |
| cdx_active_sessions |
Gauge |
swarm |
현재 활성 상태의 동시 에이전트 세션 수 |
| cdx_requests_total |
Counter |
status, model |
수신된 HTTP 프록시 요청 건수 및 HTTP 응답 코드 (200, 4xx, 5xx) |
3. Grafana PromQL 대시보드 쿼리 예시
Grafana 대시보드 구축 및 차트 시각화에 즉시 복사하여 사용할 수 있는 PromQL 쿼리 모음입니다.
# 1) 초당 토큰 절감 속도 (Tokens/sec)
sum(rate(cdx_tokens_pruned_total[5m])) by (swarm)
# 2) P99 인메모리 프록시 지연시간 (ms 단위 변환)
histogram_quantile(0.99, sum(rate(cdx_proxy_latency_seconds_bucket[5m])) by (le)) * 1000
# 3) 스웜 클러스터별 평균 토큰 절감율 (%)
avg(cdx_reduction_ratio) by (swarm) * 100
# 4) 플릿 총 요청 성공률 (Success Rate %)
sum(rate(cdx_requests_total{status="200"}[5m])) / sum(rate(cdx_requests_total[5m])) * 100
4. OpenTelemetry (OTel) Collector & Datadog 연동
사내 OTel Collector를 통해 Datadog 또는 Dynatrace로 CDX 메트릭을 안전하게 포워딩합니다.
receivers:
prometheus:
config:
scrape_configs:
- job_name: 'cdx-slimmer'
scrape_interval: 10s
static_configs:
- targets: ['cdx-slimmer.production:8080']
exporters:
datadog:
api:
key: "${DATADOG_API_KEY}"
site: "datadoghq.com"
service:
pipelines:
metrics:
receivers: [prometheus]
exporters: [datadog]
5. 프로메테우스 이상 징후 알람 룰 (alerting_rules.yml)
P99 지연시간 급증(1ms 초과) 또는 사이드카 장애 발생 시 Slack 및 PagerDuty로 즉각 통보합니다.
groups:
- name: cdx_alert_rules
rules:
- alert: CDXProxyHighLatency
expr: histogram_quantile(0.99, sum(rate(cdx_proxy_latency_seconds_bucket[5m])) by (le)) > 0.001
for: 1m
labels:
severity: warning
annotations:
summary: "CDX Sidecar P99 latency exceeded 1.0ms (Threshold: 0.08ms)"
- alert: CDXSidecarDown
expr: up{job="cantor-cdx-200-fleet"} == 0
for: 30s
labels:
severity: critical
annotations:
summary: "CDX Sidecar container is unreachable on port 8080"
버전 관리 체계 및 모델 호환성 매트릭스
Cantor Labs의 시맨틱 버저닝(Semantic Versioning v2.0.0) 표준, RFC 8259 무손실 보증 및 글로벌 LLM 호환성 공식 검증표입니다.
1. LLM 공식 호환성 매트릭스
| 모델 / 프레임워크 | 호환 버전 | 검증 결과 및 보증 항목 |
| OpenAI GPT-5 / GPT-4.5 / o3 / o1 / GPT-4o | v1.0.0-beta+ | 100% 호환 (Thinking 및 Tool Calling 최적화) |
| Anthropic Claude 3.7 Sonnet / 3.5 | v1.0.0-beta+ | 100% 호환 (하이브리드 추론 및 멀티 도구 최적화) |
| Google Gemini 2.0 / 3.0 Flash & Pro | v1.0.0-beta+ | 100% 호환 (2M+ 멀티모달 도구 호출 최적화) |
| DeepSeek-V3 / DeepSeek-R1 | v1.0.0-beta+ | 100% 호환 (사내 vLLM/SGLang GPU VRAM 절감) |