04 AI Adapter

AI Run과 AI Runtime 연동

Server는 모델을 직접 실행하지 않습니다. HR 요청을 영속 AiRun으로 만들고 별도 fowoco/ai Runtime을 호출한 뒤, 응답을 다시 검증해 사람의 업무로 연결합니다.

Client
→ Server AiRun
→ AI Runtime PLAN
→ Server Slot Resolver
→ AI Runtime ANALYZE
→ Candidate 저장
→ HR 채택
→ Task·Case 생성

저장소 경계

Server	AI Runtime
JWT·Role·company 검사	Intent 모델·Agent Pipeline
AiRun·Attempt·Candidate 영속화	Prompt·Provider·모델 선택
허용된 DB Slot 조회	PLAN에서 필요한 canonical key 요청
응답·Workflow·Version 재검증	Structured Output 생성
HR 선택 후 Task·Case 생성	업무 후보·질문·생성 문서 계획 반환

AI Runtime은 운영 DB와 Task 상태를 직접 변경하지 않습니다. Server는 OpenAI·Gemini· Hugging Face SDK와 Prompt를 포함하지 않습니다.

1단계: PLAN

Client는 사용자가 작성한 발화문 원문만 Server에 보냅니다. 빠른 선택 태그는 UI 입력을 돕는 기능이며 intentHint나 EXPIRY_RENEWAL 코드를 문장 뒤에 붙이지 않습니다.

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

Runtime은 Intent와 대상 이름을 찾고, DB 정보가 필요하면 SQL이 아니라 requiredFieldKeys를 반환합니다.

{
  "outcome": "CONTEXT_REQUIRED",
  "contextRequirement": {
    "detectedIntent": "EXPIRY_RENEWAL",
    "targetDisplayName": "응웬반안",
    "requiredFieldKeys": ["worker_id", "stay_expiry_date"]
  }
}

2단계: Slot Resolver와 ANALYZE

Server는 현재 사업장 안에서 대상 근로자 한 명을 찾고, allow-list에 등록된 key만 고정 Repository로 조회합니다. AI가 SQL을 만들거나 DB에 직접 접근하지 않습니다.

{
  "requestId": "10000000-0000-0000-0000-000000000001",
  "phase": "ANALYZE",
  "analysisInput": {
    "instruction": "응웬반안 체류연장 준비해줘",
    "requestedFieldKeys": ["worker_id", "stay_expiry_date"],
    "workers": [
      {
        "workerRef": "30000000-0000-0000-0000-000000000001",
        "requestedFields": {
          "worker_id": "30000000-0000-0000-0000-000000000001",
          "stay_expiry_date": "2026-12-31"
        }
      }
    ]
  }
}

데모에서는 합성 근로자만 사용하며, Agent가 문서 업무에 요구한 허용 필드는 ***로 치환하지 않습니다. JWT·API Key·비밀번호·Worker Link Token 같은 인증정보는 항상 차단합니다. 실제 개인정보 Pilot 전에는 전송·암호화·보유 정책을 다시 확정해야 합니다.

결과를 어떻게 읽나요?

• CONTEXT_REQUIRED: Server DB에서 보충할 key가 있음
• NEEDS_INFO: DB에도 없어 HR에게 질문해야 함
• REVIEW_REQUIRED: HR이 검토할 Candidate가 준비됨
• FAILED: HTTP·Timeout·JSON·계약 검증 같은 기술 실패

detectedIntent=EXPIRY_RENEWAL은 업무 종류이고, workflowId=WF-STY-001은 Knowledge Catalog의 실행 설계 ID입니다. 둘은 같은 값이 아닙니다.

Candidate는 Task나 승인이 아닙니다. HR이 Candidate를 채택한 뒤 Server가 Task·Case를 만들고, 별도의 승인 Command를 통과해야 근로자에게 전달할 수 있습니다.

OCR과 Renewal

• OCR: Server가 선택된 파일만 내부 OCR API로 전송하고, 결과를 암호화해 HR 검토 상태로 저장
• Renewal: AI의 missingSlots, languageAssistant, generatedDocuments, caseSignals를 기존 Task·Document 흐름으로 연결
• HWPX/PDF: AI가 만든 파일을 Server FileStorage에 저장하고 stored_file과 worker_document에 연결

현재 Renewal Adapter와 생성 문서 연결은 Draft PR에서 마무리 중입니다. AI 결과가 자동으로 승인·발송·외부 제출되는 경로는 만들지 않습니다.

운영 설정

AI_RUNTIME_ENABLED=true
AI_RUNTIME_ENDPOINT=http://ai:8000/internal/v1/analyses
AI_RUNTIME_SERVICE_CREDENTIAL=<Secret>

정확한 요청·응답·Timeout·회로 차단·OCR 계약은 Server 저장소의 docs/ai-runtime-contract.md를 최종 기준으로 확인합니다.