[AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현

[hywznn]

한 줄 목표

Server가 Prompt나 Provider를 직접 소유하지 않고, 검증한 요청을 별도 AI Runtime에 정확히 한 번 전달한 뒤 응답을 불신 경계에서 다시 검증합니다.

현재 데모는 #61·#63 결정에 따라 실제 근로자가 아닌 가상 데이터의 원본 업무정보를 사용합니다.

호출 경계

AiRunWorker (#24)
  → ValidatingAiRuntimeClient
    → RemoteAiRuntimeClient
      → POST /internal/v1/analyses (fowoco/ai)
        → Agent Pipeline → pinned Knowledge Bundle → LLM Provider

Server는 요청 계약, 서비스 인증, deadline과 장애 격리, 응답의 최종 방어 검증을 소유합니다. Prompt·모델·Provider 연동은 fowoco/ai 책임입니다.

PLAN/ANALYZE 계약

PLAN

• 빠른 선택 태그가 있으면 발화문, INTENT_TAG로 합친 instruction 하나만 전송
• 별도 intentHint 필드 없음
• Worker UUID와 DB 조회값 없음
• 값이 없는 extractedSlots, requestedFieldKeys, workers, workflowConstraints는 JSON에서 생략
• Runtime은 CONTEXT_REQUIRED와 detectedIntent, targetDisplayName, requiredFieldKeys 반환 가능

ANALYZE

• #74가 현재 사업장 안에서 허용된 DB Slot만 조회
• PLAN과 같은 requestId, 같은 instruction, 새로운 attemptId 사용
• extractedSlots, 전체 requestedFieldKeys, 조회에 성공한 requestedFields 전달
• Runtime은 CONTEXT_REQUIRED, NEEDS_INFO, REVIEW_REQUIRED를 정상 분석 결과로 반환

Agent는 SQL을 만들거나 Server DB에 직접 접근하지 않습니다.

내부 HTTP 계약

• Header: Authorization: Bearer <service-credential>, X-Request-Id, 선택적 traceparent
• Body: requestId, attemptId, phase, contractVersion, requiredKnowledgeVersion, deadlineMs, analysisInput
• Response: requestId, outcome, context/question/candidate, validation errors, version 묶음, provider 호출 수, latency
• Endpoint: POST /internal/v1/analyses

데이터 경계

• 가상 데모에서는 HR 원문과 Agent가 요청한 업무 값을 ***, OOO로 바꾸지 않습니다.
• API Key, JWT, Bearer Token, 비밀번호, Service Secret, Worker Link 원본 token은 계속 차단합니다.
• 실제 근로자 개인정보를 외부 LLM에 보내기 전에는 #48의 보안·암호화·보유 정책을 다시 확정합니다.

Server 구현 현황

• AiRuntimeClient Port와 Provider-neutral DTO
• FakeAiRuntimeClient — Server 단위·통합 테스트 전용
• RemoteAiRuntimeClient — Bearer 인증, request/trace 전달
• PLAN/ANALYZE phase와 단일 instruction 계약
• CONTEXT_REQUIRED, NEEDS_INFO, REVIEW_REQUIRED 응답 구조
• 전체 deadline, connect timeout, circuit breaker, concurrency bulkhead
• strict JSON, 응답 크기 제한, requestId·version 상관관계 재검증
• 대상 workerRef, Workflow, 허용 Slot, Server 기준 핵심값 보존 검증
• Runtime 오류를 안정적인 AiRuntimeFailureCode로 분류
• WireMock과 전체 Server 테스트
• fowoco/ai가 같은 contractVersion: 1.0.0 fixture를 확정
• staging smoke test

구현 PR:

• feat: AI Runtime 연동 계약과 안전한 검증 기반 구현 #42 — Provider-neutral 계약과 검증 기반
• [AI 연동] AI Runtime HTTP 연결과 장애 격리 구현 #56 — HTTP Adapter와 PLAN/ANALYZE 계약

Retry 소유권

• Server: 영속 AiRun attempt 생성, 재시작 복구, 사용자 retry, 전체 deadline/budget
• AI Runtime: 한 attempt 안에서만 제한된 Provider retry
• RemoteAiRuntimeClient는 투명 HTTP retry를 하지 않습니다. 다시 호출하려면 #24가 새 AiAttempt를 먼저 기록해야 합니다.

이 이슈에서 하지 않는 것

• Prompt/Context 조립, Agent Router, Intent 모델 구현
• OpenAI/Gemini/Anthropic/LM Studio Provider Client
• Knowledge YAML/Schema 원본 소유
• Task 생성·승인·발송
• Client 진행 상태 SSE

위 항목은 fowoco/ai, fowoco/knowledge, Server #24/#11/#75가 각각 소유합니다.

완료 조건

• Fake와 Remote를 바꿔도 Server application 계약이 같습니다.
• PLAN에는 단일 instruction만, ANALYZE에는 Server가 허용한 context만 전달합니다.
• 잘못된 JSON, 다른 requestId, 핵심값 변경, 미지원 version을 거부합니다.
• Runtime timeout/429/5xx에서 호출 수와 대기 시간을 제한합니다.
• 서버 저장소에 Provider SDK/API Key/Prompt 전문이 없습니다.
• fowoco/ai의 versioned internal contract와 staging smoke test가 통과합니다.

관계

• 완료 기반: [Architecture] 저장소 경계·모듈·API·이벤트 계약 ADR 작성 #23, [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25
• Agent 계약 확인: [Agent Contract][P0] PLAN·ANALYZE와 Slot 요청 계약 ai#6
• 다음 순서: [AI 연동] AI Runtime HTTP 연결과 장애 격리 구현 #56 → [AI Run][P0] Agent 요청 Slot 조회·재호출 오케스트레이션 구현 #74 → [AI Run][P0] 발화문 입력과 누락 Slot 답변 API 구현 #77 → [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24
• 선택적 Client SSE: [AI Run][P1] Client용 AiRun 진행 상태 SSE 구독 추가 #75
• Parent: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2