OFFICIAL DEVELOPER DOCUMENTATION & API REFERENCE

개발자 공식 기술 문서 & API 레퍼런스

CDX A2A Slimmer SDK 함수 명세, 200+ 에이전트 메타데이터 태깅 규격, 모달리티 자동 파싱, K8s 사이드카 배포 및 Prometheus 연동 가이드를 제공합니다.

문서 버전: v1.0.0-beta 최신 공식 릴리즈

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_keyOptional[str]None상용 라이선스 Ed25519 인증 키 (미지정 시 오픈 베타 무료 티어 자동 적용)
auto_canonicalizeboolTrue도구 정의를 결정론적 사전순으로 정렬하여 RFC 8259 JSON 무결성 및 호환성 보장
preserve_keysOptional[List[str]][]스키마 설명문 축약에서 100% 원본 보존할 기업 내부 필수 파라미터 키 목록
strip_docstring_redundancyboolTrueAST 수준에서 도구 설명문의 중복 구문을 정제하고 타입 명세만 무손실 보존

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_UPSTREAMhttps://api.openai.com필수최종 전달할 LLM 제공사(OpenAI, Anthropic, Gemini, 사내 vLLM) 원본 URL
CDX_LICENSE_KEYNone (Open Beta)선택엔터프라이즈 라이선스 인증 키 (미입력 시 오픈 베타 티어 자동 적용)
CDX_PORT8080선택사이드카 인바운드 수신 TCP 포트
ENABLE_PROMETHEUStrue선택/metrics 엔드포인트를 통한 Prometheus 시계열 메트릭 노출 활성화
LOG_LEVELinfo선택로그 출력 레벨 (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-4ov1.0.0-beta+100% 호환 (Thinking 및 Tool Calling 최적화)
Anthropic Claude 3.7 Sonnet / 3.5v1.0.0-beta+100% 호환 (하이브리드 추론 및 멀티 도구 최적화)
Google Gemini 2.0 / 3.0 Flash & Prov1.0.0-beta+100% 호환 (2M+ 멀티모달 도구 호출 최적화)
DeepSeek-V3 / DeepSeek-R1v1.0.0-beta+100% 호환 (사내 vLLM/SGLang GPU VRAM 절감)