[AI 연동] AI Runtime HTTP 연결과 장애 격리 구현

[hywznn]

연결

• Refs [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8
• 후속: [AI Run][P0] Agent 요청 Slot 조회·재호출 오케스트레이션 구현 #74 → [AI Run][P0] 발화문 입력과 누락 Slot 답변 API 구현 #77 → [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24
• Agent 계약: [Agent Contract][P0] PLAN·ANALYZE와 Slot 요청 계약 ai#6

목표

Server가 fowoco/ai Runtime을 REST로 한 번 호출하고, 인증·timeout·응답 검증·장애 격리를 담당합니다.

최종 최소 요청 계약

Endpoint: POST /internal/v1/analyses

PLAN

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

ANALYZE 핵심

{
  "requestId": "10000000-0000-0000-0000-000000000001",
  "phase": "ANALYZE",
  "analysisInput": {
    "instruction": "응웬반안 체류연장 준비해줘, EXPIRY_RENEWAL",
    "requestedFieldKeys": ["worker_id", "stay_expiry_date", "due_at"],
    "workers": [{
      "workerRef": "worker-uuid",
      "requestedFields": {
        "worker_id": "worker-uuid",
        "stay_expiry_date": "2026-09-30"
      }
    }]
  }
}

• Runtime에 보내는 공통 식별자는 requestId 하나입니다.
• attemptId, contract/knowledge version, deadline은 Server 내부에서 관리합니다.
• PLAN의 빈 context field는 전송하지 않습니다.
• 선택 태그는 별도 필드가 아니라 발화문, INTENT_TAG로 instruction에 포함합니다.

Server 내부 관리

• attemptId: PLAN·ANALYZE·retry 호출을 구분해 [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24 AiAttempt에 저장
• contract/knowledge version: Server 설정과 Runtime 응답 version을 비교
• deadline: RemoteAiRuntimeClient가 Server timeout으로 적용
• Runtime 응답의 requestId, version, Worker·Workflow·Slot 핵심값을 다시 검증

구현 범위

• Bearer service 인증, X-Request-Id, 선택적 traceparent
• strict camelCase JSON과 응답 크기 제한
• 전체 timeout, bulkhead, circuit breaker
• HTTP·timeout·parsing·contract 오류 분류
• 투명 HTTP retry 금지: #24가 새 AiAttempt를 기록한 뒤에만 재호출
• 기본 비활성화: AI_RUNTIME_ENABLED=false

데이터 경계

• [AI Integration] 데모 Agent 요청에 원본 업무데이터 전달 #61·fix: 데모 Agent 요청에 원본 업무데이터 전달 #63 기준으로 가상 데모 원본 업무값은 requestedFields에 전달합니다.
• API Key, JWT, 비밀번호, Service Secret, Worker Link 원본 token은 차단합니다.
• 실제 개인정보 Pilot 전에는 [Worker] 근로자 민감정보(WorkerSensitiveData) 분리 저장·접근 제어 구현 #48 정책을 다시 확정합니다.

검증

• AI 연동 단위·WireMock 테스트
• 전체 ./gradlew clean test
• Server CI
• 최소 요청 JSON 직렬화가 위 계약과 정확히 일치
• fowoco/ai#6에서 최소 계약 확인
• staging smoke test

범위 밖

• Prompt·Agent Pipeline·Provider 구현
• [AI Run][P0] Agent 요청 Slot 조회·재호출 오케스트레이션 구현 #74 DB Slot 조회·재호출
• [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24 AiRun/AiAttempt 영속화
• Task 자동 생성·승인·발송

[krestar]

408 타임아웃이 INVALID_REQUEST_CONTRACT로 처리되는걸로 보이는데, 문제 없을 것 같으면 나머지 리뷰 포인트 2~4번은 적절해보여서 PR 내용 괜찮아 보입니다

[hywznn]

참고용 형식 joson

{
  "analysisInput": {
    "instruction": "응웬반안 체류연장 준비해줘",
    "workers": [
      {
        "workerRef": "...",
        "displayName": "응웬반안",
        "requestedFields": {
          "legal_name": "NGUYEN VAN AN",
          "passport_number": "M12345678"
        }
      }
    ]
  }
}

[hywznn]

헤더 인증 관련 형식

            HttpRequest.Builder requestBuilder = HttpRequest.newBuilder(endpoint)
                    .timeout(Duration.ofMillis(remainingMillis))
                    .header("Content-Type", "application/json")
                    .header("Accept", "application/json")
                    .header(AUTHORIZATION, authorizationHeader)
                    .header(REQUEST_ID, request.requestId().toString())
                    .POST(HttpRequest.BodyPublishers.ofByteArray(requestBody));
            if (context.traceParent() != null) {
                requestBuilder.header(TRACEPARENT, context.traceParent());
            }

[krestar]

기존에 커멘트했던 408 응답이 DEADLINE_EXCEEDED로 분리된 것 확인했습니다.
analysisInput.workers[].requestedFields 구조와 camelCase 전송은 현재 Server 문서, fixture 기준으로 적절해 보입니다.
AiRuntimeFailureCode도 #24 진단에 필요한 주요 유형 포함하고 있는 것 같네요.
15초 timeout, 동시 호출 8개, 5회 실패, 30초 차단은 데모 기본값으로 무난하며, 기본 비활성화와 Secret 주입 방식도 적절해 보입니다.

[hywznn]

PLAN/ANALYZE 통신 계약을 최신 요구사항에 맞춰 추가했습니다.

• 최초 PLAN: instruction + optional intentHint, Worker DB context 없음
• CONTEXT_REQUIRED: contextRequirement.detectedIntent/targetDisplayName/requiredFieldKeys
• 후속 ANALYZE: Server가 허용된 requestedFields를 넣어 새 attempt로 재호출
• NEEDS_INFO: HR 질문, REVIEW_REQUIRED: 검토 후보
• Agent의 직접 DB/SQL 접근 없음, MVP Worker 1명

커밋: 6af9bb6
검증: 로컬 ./gradlew clean test 및 GitHub Test and build 성공

AI팀에는 fowoco/ai#6 에서 contextRequirement 구조와 contractVersion: 1.0.0 확인을 요청했습니다. 해당 계약 확인 후 Draft를 해제하겠습니다.

[hywznn]

후속 #74 오케스트레이션 검토 결과, ANALYZE 재호출에 필요한 문맥 보존 필드를 추가했습니다.

• extractedSlots: PLAN 추출값 보존
• requestedFieldKeys: DB 누락 여부와 관계없이 Agent가 요청한 전체 key 보존
• requestedFields: Server가 실제로 해결한 값만 포함
• timeout 테스트가 서버 기동 속도에 따라 HTTP 요청 전 실패하지 않도록 시간 여유를 조정

커밋: 35ee1b7
검증: AI 연동 테스트 및 전체 clean test 성공

[hywznn]

입력 계약을 단순화했습니다 (adc486c).

• 별도 analysisInput.intentHint 제거
• 선택 태그는 "발화문, INTENT_TAG" 형태로 instruction에 포함
• PLAN과 ANALYZE에서 같은 단일 instruction 유지
• JSON에 intentHint가 생성되지 않는 계약 테스트 추가

로컬 전체 테스트: ./gradlew clean test 성공

[krestar]

확인했습니다
직접 접근 논의 있던걸로 기억하는데, AI 모델이 DB 직접 접근 안하는걸로 반확정 났나보네요

[hywznn]

확인했습니다 직접 접근 논의 있던걸로 기억하는데, AI 모델이 DB 직접 접근 안하는걸로 반확정 났나보네요

어쩔수없죠 .. 원래는 그게 맞으니까