04 AI Adapter

AI Run과 AI Runtime 연동

파일명은 기존 링크 호환을 위해 04-AI-Adapter를 유지하지만, Server의 역할은 Provider Adapter가 아니라 AI Runtime Client와 영속 실행 관리입니다.

한 줄 구조

Client → Server(AiRun + AiRuntimeClient) → AI Runtime(Agent + Prompt + Provider) → LLM

LM Studio는 ai 저장소의 모델 후보 실험에만 사용합니다. Server와 최종 데모가 LM Studio에 직접 의존하지 않습니다.

책임 분리

Server	AI Runtime
사용자 인증·tenant·Role 검사	Prompt와 Context 조립
업무에 필요한 최소 context 조회	Intent·Slot·후보 생성
민감정보 제거의 최종 방어	Provider/model 선택과 호출
AiRun 상태·idempotency·내구성	Provider timeout·rate limit 대응
Internal response Schema 재검증	원 응답 parsing·Structured Output 1차 검증
핵심값 보존·Workflow 불변식 검증	배포에 pin된 model/prompt/knowledge version 사용·반환
후보 확정·Task 생성·승인·Audit	품질 evaluation과 model experiment

Server 내부 인터페이스

public interface AiRuntimeClient {
    AnalysisResult analyze(AnalysisCommand command);
}

MVP 구현체는 두 개입니다.

• FakeAiRuntimeClient: unit/integration test용 결정적 fixture. 실제 장애 fallback으로 사용하지 않습니다.
• RemoteAiRuntimeClient: 별도 AI Runtime의 Internal REST API를 호출합니다.

Provider별 Client를 Server에 추가하지 않습니다.

Server External API와 AI Internal API

Client는 Server의 비동기 API만 호출합니다.

POST /api/v1/ai-runs
GET  /api/v1/ai-runs/{aiRunId}
POST /api/v1/ai-runs/{aiRunId}/retry
POST /api/v1/ai-runs/{aiRunId}/candidate-decisions

/retry는 원본 Run을 지우거나 새 Run으로 바꾸지 않습니다. 같은 AiRun에 새 AiAttempt를 영속 생성하고 202 + aiRunId를 반환해 실패 이력을 한 resource에서 추적합니다.

Server background handler가 AI Runtime을 호출합니다.

POST /internal/v1/analyses
Authorization: Bearer <service-credential>
X-Request-Id: <request-id>
traceparent: <w3c-trace-context>

정확한 Internal API Schema 원본은 fowoco/ai가 소유합니다. 아래는 경계를 이해하기 위한 예시입니다.

Internal 요청 예시

{
  "requestId": "req_01",
  "companyContext": {
    "companyRef": "cmp_7f2a"
  },
  "actorContext": {
    "role": "HR"
  },
  "input": {
    "text": "응웬반A 체류연장 준비하고 여권 사본도 요청해줘",
    "locale": "ko-KR"
  },
  "workers": [
    {
      "workerId": "wrk_123",
      "displayName": "응웬반A",
      "language": "vi",
      "expiryDate": "2026-09-30",
      "documentStatuses": [
        {"type": "PASSPORT_COPY", "status": "MISSING"}
      ]
    }
  ],
  "expectedVersions": {
    "contextPackVersion": "context-2026.07.1",
    "workflowCatalogVersion": "workflow-2026.07.1"
  }
}

보내지 않는 값:

• 외국인등록번호, 여권번호, 전화번호, 계좌번호
• JWT, Worker Link token, Provider key
• 원본 신분증 이미지와 계약서 전문
• 요청과 무관한 주소·가족·건강정보

companyRef는 AI가 Server 데이터에 접근할 권한이 아니라 추적용 안전 reference입니다.

expectedVersions는 Server가 모델이나 Knowledge bundle을 선택하라는 명령이 아닙니다. 배포 조합이 기대한 contract와 맞는지 확인하는 compatibility 조건입니다. 실제 bundle 선택·로딩은 AI Runtime 배포가 소유하며, 불일치하면 후보를 만들지 않고 version contract 오류를 반환합니다.

Internal 응답 예시

{
  "requestId": "req_01",
  "outcome": "REVIEW_REQUIRED",
  "candidates": [
    {
      "candidateId": "cand_1",
      "taskType": "EXPIRY_RENEWAL",
      "workerId": "wrk_123",
      "title": "체류기간 연장 준비",
      "dueDate": "2026-08-31",
      "missingFields": [],
      "confidence": 0.93
    },
    {
      "candidateId": "cand_2",
      "taskType": "DOCUMENT_REQUEST",
      "workerId": "wrk_123",
      "title": "여권 사본 요청",
      "documentTypes": ["PASSPORT_COPY"],
      "missingFields": [],
      "confidence": 0.96
    }
  ],
  "versions": {
    "agentVersion": "agent-0.4.0",
    "modelProvider": "external-provider",
    "modelName": "model-name",
    "modelVersion": "2026-07",
    "promptVersion": "prompt-14",
    "contextPackVersion": "context-2026.07.1",
    "workflowCatalogVersion": "workflow-2026.07.1"
  },
  "latencyMs": 1840
}

Server는 이 응답을 신뢰만 하지 않고 다시 검증합니다.

Server의 최종 검증

1. HTTP status, content type, body 크기를 확인합니다.
2. requestId가 현재 요청과 일치하는지 확인합니다.
3. JSON Schema, enum, required field를 검증합니다.
4. workerId가 요청 context에 있던 근로자인지 확인합니다.
5. 날짜·금액·문서명·대상자가 원문과 context에서 사라지거나 바뀌지 않았는지 확인합니다.
6. 금지된 개인정보와 token이 응답에 포함되지 않았는지 확인합니다.
7. version metadata가 비어 있거나 지원하지 않는 조합인지 확인합니다.
8. 후보를 저장하되 HR 승인·전달은 자동으로 수행하지 않습니다.

검증 실패를 임의의 성공 후보로 바꾸지 않습니다. 기술 실패는 AiRun=FAILED, 정보 부족은 AiRun=SUCCEEDED + outcome=NEEDS_INFO, 사람이 확인해야 하면 REVIEW_REQUIRED로 구분합니다.

오류와 재시도 경계

상황	AI Runtime 내부	Server
Provider 429/5xx	짧은 호출 retry/fallback 정책	전체 분석 요청의 제한적 retry 여부 결정
Internal API timeout/503	원인·retry hint 반환	AiRun RETRYING, backoff, circuit breaker
malformed JSON/Schema 위반	계약 오류 기록	자동 retry 금지, FAILED와 안전한 error code
핵심값 손실·PII 탐지	quality/security 결과 반환	후보 차단, 검토·보안 Audit
Server 재시작	관여하지 않음	Durable Event에서 미완료 Run 복구

두 계층이 같은 요청을 각각 여러 번 retry해 호출 폭주가 나지 않도록 총 retry budget을 정합니다.

Service-to-Service 보안

• AI Runtime endpoint는 Public Internet에 무인증으로 노출하지 않습니다.
• 최소한 짧은 수명의 service credential 또는 배포 환경의 workload identity를 사용합니다.
• Server 사용자 JWT를 AI Runtime에 그대로 전달하지 않습니다.
• audience·issuer·만료·scope를 검사하고 key를 Git에 저장하지 않습니다.
• request/response 전문과 Authorization header를 log·trace에 남기지 않습니다.

꼭 필요한 테스트

• Fake client로 정상 후보, NEEDS_INFO, 계약 오류를 재현
• Remote client의 timeout·429·503·잘린 JSON·과대 body
• request ID 불일치와 미지원 version 차단
• 핵심 날짜·금액·대상·문서 손실 차단
• 민감정보 fixture가 AI 요청에 포함되지 않음
• Server 재시작 뒤 Run 재실행과 중복 후보 방지
• AI 성공 뒤에도 HR 승인 전 Worker Link 발급 차단

관련 구현 범위는 #8, 영속 실행은 #24, 재시작 복구는 #25를 기준으로 합니다.