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

[hywznn]

목표

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

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

현재 요청 계약

PLAN은 사용자가 작성한 원문만 전달합니다. Client의 빠른 선택 태그나 Intent 코드를 발화문에 덧붙이지 않습니다.

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

• requestId: PLAN과 ANALYZE를 같은 실행으로 연결
• phase: PLAN 또는 ANALYZE
• analysisInput: 실제 분석 데이터
• Intent는 Runtime 응답의 detectedIntent를 사용
• Workflow는 WF-STY-001 같은 canonical workflowId를 사용
• ANALYZE에서는 같은 requestId와 #74가 해결한 Slot 정보만 추가

Server 책임

• Bearer service 인증과 request/trace 전달
• HTTP/1.1, timeout, bulkhead, circuit breaker, 응답 크기 제한
• strict JSON parsing과 requestId·핵심값 검증
• Runtime 호출 1회당 Server 내부 AiAttempt 1개
• Agent·OCR의 Server DB 직접 접근 금지
• API Key, JWT, 비밀번호, Worker Link 원본 token 차단

구현 현황

• Provider-neutral AiRuntimeClient
• Fake·Remote Adapter
• PLAN/ANALYZE와 정상 outcome 처리
• 인증·timeout·장애 격리·strict response 검증
• WireMock과 Server 테스트
• 원문-only 요청 계약
• HTTP/1.1 고정 — PR fix: AI Runtime 통신을 HTTP/1.1로 고정 #93
• AI PLAN/ANALYZE 계약 — fowoco/ai PR [Document] 통합 문서함·파일 업로드·문서 준비도 구현 #13
• Intent와 Workflow ID 분리 — fowoco/ai PR [Q&A] 로컬 실행·환경설정·API 연동 질문 모음 #19
• 실행 중인 AI Runtime과 실제 성공 JSON 왕복 smoke test

완료 기준

실제 Runtime을 호출해 다음을 확인하면 이 이슈를 완료합니다.

1. PLAN 요청이 원문 그대로 전달됨
2. detectedIntent=EXPIRY_RENEWAL, workflowId=WF-STY-001 형태로 수신
3. 필요한 Slot이 있으면 ANALYZE 재호출까지 성공
4. timeout·계약 오류가 Server 공통 오류로 안전하게 변환됨

관계

• Server 구현 PR: feat: AI Runtime 연동 계약과 안전한 검증 기반 구현 #42, [AI 연동] AI Runtime HTTP 연결과 장애 격리 구현 #56, fix: AI Runtime 통신을 HTTP/1.1로 고정 #93
• 실행 이력·Candidate: [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24
• Slot Resolver: [AI Run][P0] Agent 요청 Slot 조회·재호출 오케스트레이션 구현 #74
• Agent 계약: fowoco/ai PR #13, PR #19
• OCR 후속: [OCR][P0] Server 소유 문서 OCR 실행·결과 저장 구현 #95, fowoco/ai#20
• Parent: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2