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

[hywznn]

목표

Server가 Prompt·Provider를 직접 소유하지 않고, 검증한 최소 요청을 AI Runtime에 전달한 뒤 응답을 다시 검증합니다.

AiRunWorker (#24)
→ AiRuntimeClient (#8/#56)
→ POST /internal/v1/analyses (fowoco/ai)

최소 전송 계약

{
  "requestId": "10000000-0000-0000-0000-000000000001",
  "phase": "PLAN",
  "analysisInput": {
    "instruction": "응웬반안 체류연장 준비해줘, EXPIRY_RENEWAL"
  }
}

• requestId: PLAN과 ANALYZE 응답을 같은 실행으로 연결
• phase: PLAN 또는 ANALYZE
• analysisInput: 실제 분석 데이터만 포함
• attemptId, version, deadline: AI JSON에 넣지 않고 Server 내부에서 관리
• PLAN의 빈 context field와 별도 intentHint는 전송하지 않음

ANALYZE에는 같은 requestId·instruction과 #74가 실제로 해결한 requestedFields만 추가합니다.

Server 책임

• Bearer service 인증과 request/trace 전달
• timeout·bulkhead·circuit breaker·응답 크기 제한
• strict JSON parsing과 requestId·version·핵심값 재검증
• Runtime 호출 1회당 Server 내부 AiAttempt 1개
• 자동 HTTP retry 금지

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

데이터 경계

• [AI Integration] 데모 Agent 요청에 원본 업무데이터 전달 #61·#63의 가상 데모 데이터는 마스킹 없이 전달할 수 있습니다.
• API Key, JWT, 비밀번호, Service Secret, Worker Link 원본 token은 차단합니다.
• 실제 개인정보 사용 전 [Worker] 근로자 민감정보(WorkerSensitiveData) 분리 저장·접근 제어 구현 #48 정책을 확정합니다.

현황

• Provider-neutral AiRuntimeClient
• Fake·Remote Adapter
• PLAN/ANALYZE와 세 가지 정상 outcome
• 인증·timeout·장애 격리·strict response 검증
• WireMock과 전체 Server 테스트
• #56의 실제 outbound JSON을 최소 계약과 일치시킴
• [Agent Contract][P0] PLAN·ANALYZE와 Slot 요청 계약 ai#6 versioned fixture 확인
• staging smoke test

관계

• 구현 PR: feat: AI Runtime 연동 계약과 안전한 검증 기반 구현 #42, [AI 연동] AI Runtime HTTP 연결과 장애 격리 구현 #56
• 다음 순서: [AI 연동] AI Runtime HTTP 연결과 장애 격리 구현 #56 → [AI Run][P0] Agent 요청 Slot 조회·재호출 오케스트레이션 구현 #74 → [AI Run][P0] 발화문 입력과 누락 Slot 답변 API 구현 #77 → [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24
• Agent 계약: [Agent Contract][P0] PLAN·ANALYZE와 Slot 요청 계약 ai#6
• 선택적 Client SSE: [AI Run][P1] Client용 AiRun 진행 상태 SSE 구독 추가 #75
• Parent: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2