한 줄 목표
Server가 Prompt나 Provider를 직접 소유하지 않고, 비식별 요청을 별도 AI Runtime에 전달한 뒤 응답을 불신 경계에서 다시 검증하도록 AiRuntimeClient를 구현합니다.
호출 경계
AiRunWorker (#24)
→ AiRuntimeClient (Server port)
→ RemoteAiRuntimeClient
→ POST /internal/v1/analyses (fowoco/ai)
→ Agent Pipeline → pinned Knowledge Bundle → LLM Provider
Server가 구현하는 것은 첫 두 계층과 응답의 최종 방어 검증입니다.
내부 요청 계약
최소 필드:
- Header:
Service-Authorization, X-Request-Id, traceparent
- Body:
requestId, attemptId, contractVersion, requiredKnowledgeVersion, deadlineMs, maskedInput
- Worker 정보: 원문 식별번호가 아닌
workerRef, language, expiryDate, employmentStatus 등 최소 context
실제 외국인등록번호, 여권번호, 전화번호, 계좌번호, JWT, Worker Link token은 AI 경계로 보내지 않습니다.
내부 응답 계약
requestId, outcome, candidates, validationErrorsagentVersion, modelProvider, modelName, modelVersionpromptVersion, contextPackVersion, workflowCatalogVersion, contractVersionproviderAttemptCount, latencyMs
낮은 신뢰도와 누락정보는 200의 정상 NEEDS_INFO/REVIEW_REQUIRED 결과입니다. Schema/버전 불일치는 422, AI 생성 파싱 실패는 502, 일시 장애는 503, deadline 초과는 504로 매핑합니다.
Server 구현 범위
Retry 소유권
- Server: 영속 AiRun attempt 생성, 재시작 복구, 사용자 수동 retry, 전체 deadline/budget
- AI Runtime: 한 attempt 안에서만 제한된 Provider retry
RemoteAiRuntimeClient는 투명한 다중 retry를 하지 않습니다. 두 계층의 retry가 곱해지지 않게 합니다.
이 이슈에서 하지 않는 것
- Prompt/Context 조립, Agent Router, Intent 추출
- OpenAI/Gemini/Anthropic/LM Studio client
- 모델 선택·fallback·fine-tuning·evaluation runner
- Knowledge YAML/Schema의 원본 소유
- Task 생성·승인·발송
위 항목은 각각 fowoco/ai, fowoco/knowledge, Server #24/#11의 책임입니다.
완료 조건
관계
한 줄 목표
Server가 Prompt나 Provider를 직접 소유하지 않고, 비식별 요청을 별도 AI Runtime에 전달한 뒤 응답을 불신 경계에서 다시 검증하도록
AiRuntimeClient를 구현합니다.호출 경계
Server가 구현하는 것은 첫 두 계층과 응답의 최종 방어 검증입니다.
내부 요청 계약
최소 필드:
Service-Authorization,X-Request-Id,traceparentrequestId,attemptId,contractVersion,requiredKnowledgeVersion,deadlineMs,maskedInputworkerRef, language, expiryDate, employmentStatus 등 최소 context실제 외국인등록번호, 여권번호, 전화번호, 계좌번호, JWT, Worker Link token은 AI 경계로 보내지 않습니다.
내부 응답 계약
requestId,outcome,candidates,validationErrorsagentVersion,modelProvider,modelName,modelVersionpromptVersion,contextPackVersion,workflowCatalogVersion,contractVersionproviderAttemptCount,latencyMs낮은 신뢰도와 누락정보는
200의 정상NEEDS_INFO/REVIEW_REQUIRED결과입니다. Schema/버전 불일치는422, AI 생성 파싱 실패는502, 일시 장애는503, deadline 초과는504로 매핑합니다.Server 구현 범위
AiRuntimeClientport와 Provider-neutral DTOFakeAiRuntimeClient— Server 단위·통합 테스트 전용RemoteAiRuntimeClient— service auth, request/trace propagationrequestId상관관계 재검증workerRef핵심값 보존 검증Retry 소유권
RemoteAiRuntimeClient는 투명한 다중 retry를 하지 않습니다. 두 계층의 retry가 곱해지지 않게 합니다.이 이슈에서 하지 않는 것
위 항목은 각각
fowoco/ai,fowoco/knowledge, Server #24/#11의 책임입니다.완료 조건
관계
fowoco/aiinternal contract, Knowledge release