fix(intent): Knowledge A.X 프롬프트와 PLAN 재사용 계약 통합 by hywznn · Pull Request #33 · fowoco/ai

hywznn · 2026-08-11T10:20:32Z

한 줄 요약

Knowledge 담당자의 A.X Intent 프롬프트를 실제 추론 경로에 연결하고, PLAN에서 한 번 결정한 대표 Intent/Workflow를 ANALYZE에서 재분류 없이 재사용하도록 계약을 정리했습니다.

리뷰 중 확인된 다음 문제도 함께 보완했습니다.

같은 Intent에 여러 Workflow가 있을 때 첫 번째 Workflow로 오선택
OUT_OF_SCOPE가 빈 workflowId를 가진 CONTEXT_REQUIRED로 반환됨
첫 PLAN 요청에서 BERT/A.X를 cold start함
Renewal 실행 중 Server가 선택한 task.workflowId를 AI가 다시 분류해 덮어쓸 수 있음

쉽게 말하면 PLAN은 “어떤 업무를 할지” 한 번 결정하고, ANALYZE는 그 결정을 바꾸지 않은 채 필요한 Slot만 검사합니다. 이미 Server Task가 만들어진 Renewal 실행에서는 그 Task의 Workflow를 다시 선택하지 않고 그대로 실행합니다.

용어와 책임

값	의미	결정·보관 주체
`detectedIntent`	사용자가 요청한 대표 업무 종류	AI Intent Agent
`workflowId`	실행할 Knowledge canonical Workflow	AI PLAN 또는 이미 생성된 Server Task
`requiredFieldKeys`	Server가 DB 등에서 보충할 필드	선택된 Workflow의 Slot 계약
`plannedIntent`, `plannedWorkflowId`	PLAN 결정을 ANALYZE에서 재사용하기 위한 값	Server가 PLAN 결과를 보관 후 전달

현재 catalog에서는 대표 Intent 하나에 여러 세부 Workflow가 있을 수 있습니다.

EXPIRY_RENEWAL
├─ WF-STY-001  체류기간 연장
└─ WF-CON-001  근로계약·취업활동기간 연장

최종 호출 흐름

PLAN
→ Intent 모델 1회 호출
→ 대표 Intent + canonical Workflow 결정
→ requiredFieldKeys 반환

Server
→ PLAN 결정과 confidence 이력 보관
→ DB context 조회
→ plannedIntent/plannedWorkflowId와 DB 값을 ANALYZE에 전달

ANALYZE
→ Intent 모델 호출 없음
→ PLAN의 Intent/Workflow 재사용
→ Slot만 검사
→ NEEDS_INFO 또는 REVIEW_REQUIRED

Renewal 실행 API는 PLAN을 새로 수행하는 경로가 아니라, 이미 생성된 Task를 실행하는 경로입니다.

POST /internal/v1/workflows/renewal/run
→ Server task.workflowId 로드
→ AI가 해당 Workflow를 constraint로 사용
→ 정상 업무에서는 task.workflowId 보존
→ OUT_OF_SCOPE일 때만 workflowId를 비움

주요 변경 사항

1. Knowledge A.X 프롬프트 연결

원본 프롬프트를 app/agents/intent/prompts/ax_intent_v1.txt 리소스로 적용
실제 A.X 호출부가 같은 리소스를 사용
Prompt version: knowledge-25e778ad
프롬프트 SHA-256을 테스트로 고정

적용 규칙:

7개 Intent 정의
DOCUMENT_REQUEST 경계 규칙
OUT_OF_SCOPE 단독 규칙
복합 Intent 원문 순서 및 대표 Intent 정책
evidence exact substring
JSON-only 출력 계약

2. A.X 출력 검증과 fallback

다음 결과는 A.X 검증 실패로 처리하고 BERT로 fallback합니다.

미정의 Intent 또는 동일 Intent 중복
evidence 누락 또는 원문에 없는 evidence
OUT_OF_SCOPE와 다른 Intent의 동시 반환
JSON 파싱, A.X 로딩 또는 추론 실패

Fallback 결과는 modelVersion=BERT_FALLBACK으로 구분합니다.

3. PLAN 응답과 confidence 계약

MVP에서는 대표 Intent/Workflow 한 건을 반환합니다.

{
  "detectedIntent": "EXPIRY_RENEWAL",
  "workflowId": "WF-STY-001",
  "evidence": "체류연장 준비해줘",
  "confidence": null,
  "confidenceSource": "UNAVAILABLE",
  "bertRoutingScore": 0.3088,
  "requiredFieldKeys": ["worker_id", "stay_expiry_date", "passport_status", "arc_status"]
}

최종 분류기	`confidence`	`confidenceSource`	`bertRoutingScore`
BERT	BERT 확률	`BERT`	동일 BERT routing score
A.X	`null`	`UNAVAILABLE`	A.X 호출 전 BERT routing score
고정 규칙	규칙 confidence	`MODEL`	`null`

A.X는 확률을 반환하지 않으므로 BERT 점수를 A.X confidence로 사용하지 않습니다.

4. ANALYZE에서 PLAN 결정 재사용

ANALYZE는 다음 값을 받습니다.

{
  "plannedIntent": "EXPIRY_RENEWAL",
  "plannedWorkflowId": "WF-STY-001"
}

해당 값이 있으면:

Intent 모델을 다시 호출하지 않음
Candidate workflowId=plannedWorkflowId
Candidate confidence=null
providerAttemptCount=0
evidence를 evidence:EXPIRY_RENEWAL 같은 가짜 Slot으로 만들지 않음

5. Workflow 선택 및 Renewal Task 보존

PLAN에서는 발화/evidence의 업무 신호를 사용해 같은 Intent 안의 canonical Workflow를 선택합니다.

발화 예시	Workflow
체류기간 연장 준비해줘	`WF-STY-001`
재계약 준비해줘	`WF-CON-001`
취업활동기간을 연장해줘	`WF-CON-001`
고용허가기간을 연장해줘	`WF-CON-001`

Renewal 실행에서는 Server #131의 task.workflowId를 우선합니다.

Stub Language Node가 task.workflowId를 classifier constraint로 전달
외부 Language Node가 다른 Workflow를 반환해도 정상 업무에서는 Task Workflow 복원
OUT_OF_SCOPE일 때는 Task Workflow를 유지하지 않고 빈 값으로 정규화

6. OUT_OF_SCOPE terminal outcome

OUT_OF_SCOPE에는 실행할 Workflow와 context가 없습니다.

{
  "outcome": "OUT_OF_SCOPE",
  "contextRequirement": null,
  "questions": [],
  "candidates": [],
  "validationErrors": [],
  "providerAttemptCount": 1
}

Server는 이를 정상 business outcome으로 처리하고 Workflow 검증, DB 조회, ANALYZE 호출을 생략합니다. 이 변경에 따라 Analyses contractVersion은 1.1.0입니다.

7. Startup warmup과 readiness

모델 기능이 활성화되면 FastAPI lifespan에서 BERT/A.X 로딩과 첫 추론을 완료한 뒤 readiness를 활성화합니다. 동시 첫 요청의 중복 로딩을 막는 load lock도 포함합니다.

GET /internal/v1/intent/status
GET /internal/v1/intent/readiness

/intent/readiness는 warmup 완료, BERT 사용 가능, A.X 활성화 시 A.X 사용 가능, degraded 상태 아님을 모두 만족해야 200을 반환합니다.

Server 연동 상태

Server #138 — PLAN/ANALYZE 및 OUT_OF_SCOPE

Server PR #138, head 1347e87에서 계약 반영과 CI 통과를 확인했습니다.

Server #131 — Renewal Task Workflow 재사용

Server PR #131, head 16e2afb의 Task/Workflow canonical pair와 맞췄습니다.

RECONTRACT → WF-CON-001
EMPLOYMENT_PERIOD_EXTENSION → WF-CON-001
STAY_PERIOD_EXTENSION → WF-STY-001
Renewal 실행 시 task.workflowId를 classifier constraint로 전달
정상 업무에서 외부/Stub Language 결과가 Task Workflow를 덮어쓰지 못하도록 보장
OUT_OF_SCOPE 예외에서는 빈 Workflow 허용
취업활동기간·고용허가기간 연장 신호를 WF-CON-001로 라우팅
단위·계약 테스트와 문서 반영

운영 설정

FOWOCO_INTENT_MODEL_ENABLED=true
FOWOCO_INTENT_ENABLE_AX=true
FOWOCO_INTENT_WARMUP_ON_START=true
FOWOCO_INTENT_WARMUP_REQUIRED=true

FOWOCO_INTENT_DEVICE는 실제 배포 장치에 맞춰 설정
Kubernetes readiness probe는 /internal/v1/intent/readiness 확인
private 모델용 신규 read-only Hugging Face Token을 Kubernetes Secret으로 주입
Docker는 intent-ax extra dependency를 설치
Base/BERT/Adapter revision은 immutable commit SHA로 고정 권장

검증 결과

검증	결과
Workflow/Intent 관련 테스트	51개 통과
전체 테스트	PowerShell OCR smoke 제외 615개 통과
수정 범위 Ruff	통과
Diff whitespace 검사	통과
실제 로컬 BERT/A.X offline smoke	통과

실제 모델 smoke 결과:

입력	선택 모델	결과
체류연장 준비해줘	A.X	`EXPIRY_RENEWAL / WF-STY-001`
근로계약 종료 전에 재계약 준비해줘	BERT	`EXPIRY_RENEWAL / WF-CON-001`
오늘 날씨 어때?	BERT	`OUT_OF_SCOPE`, context 없음

추가 회귀 테스트로 다음을 확인했습니다.

Server Task가 WF-CON-001이면 발화가 체류연장처럼 보여도 Renewal 결과는 WF-CON-001
외부 Language Node가 WF-STY-001을 반환해도 Task의 WF-CON-001 보존
최종 Intent가 OUT_OF_SCOPE이면 Task Workflow를 비움

macOS에 powershell/pwsh가 없어 Windows 전용 OCR smoke는 전체 실행에서 제외했습니다. 이번 변경과 무관한 환경 의존 테스트입니다.

병합 체크리스트

Refs #32

krestar

1.1.0인거랑 OUT_OF_SCOPE 가 AI쪽에서만 준비된거 #138에서도 수정하신거 확인했습니다.

hywznn · 2026-08-11T11:49:06Z

Server #131 연동 후속 보완

AI #33을 Server #131의 Renewal Task 계약과 다시 비교하면서, 체크리스트 갱신 외에 실제 보완이 필요한 지점을 확인해 반영했습니다.

확인된 문제

POST /internal/v1/workflows/renewal/run은 이미 Server가 생성한 Task를 실행하는 API입니다. 따라서 task.workflowId가 실행 기준이어야 하지만, 기존 경로에서는 Language Node가 instruction을 다시 분류한 결과로 이를 덮어쓸 수 있었습니다.

예를 들어 Server Task가 RECONTRACT / WF-CON-001이어도 모호한 instruction이 WF-STY-001로 재분류되면, Task와 다른 Workflow가 실행될 가능성이 있었습니다.

반영 내용

Stub Language Node가 Server의 task.workflowId를 Intent classifier의 workflow_constraints로 전달합니다.
Workflow Graph에서도 정상 업무라면 Language Node 결과와 무관하게 Server Task Workflow를 복원합니다.
외부 Language Node 구현을 사용해도 Task Workflow를 덮어쓸 수 없도록 Graph 경계에서 한 번 더 보장합니다.
최종 Intent가 OUT_OF_SCOPE이면 실행 Workflow가 없어야 하므로 workflowId=""로 정규화합니다.
취업활동기간 연장, 고용허가기간 연장 표현을 WF-CON-001 신호에 추가했습니다.
analyses/workflows 계약 문서와 회귀 테스트를 갱신했습니다.

Server canonical pair

Task type	Workflow
`RECONTRACT`	`WF-CON-001`
`EMPLOYMENT_PERIOD_EXTENSION`	`WF-CON-001`
`STAY_PERIOD_EXTENSION`	`WF-STY-001`

검증

Workflow/Intent 관련 테스트: 51개 통과
전체 테스트: Windows PowerShell OCR smoke 제외 615개 통과
수정 범위 Ruff: 통과
git diff --check: 통과

추가 테스트에서는 다음을 직접 검증했습니다.

Task가 WF-CON-001이면 instruction이 체류연장처럼 보여도 최종 Workflow는 WF-CON-001
외부 Language Node가 WF-STY-001을 반환해도 Task의 WF-CON-001 보존
최종 Intent가 OUT_OF_SCOPE이면 Task Workflow 제거

반영 커밋: 35d92fa

아직 남은 통합 확인

코드와 단위·계약 테스트는 완료됐습니다. 병합 전 또는 배포 환경에서는 다음 두 요청을 Server #131과 실제로 연결해 smoke test하면 됩니다.

RECONTRACT / WF-CON-001
STAY_PERIOD_EXTENSION / WF-STY-001

이번 보완의 기준은 간단합니다. PLAN은 새 업무를 선택하지만, Renewal run은 이미 선택된 Server Task를 실행하므로 Workflow를 다시 선택하지 않습니다.

hywznn · 2026-08-11T11:53:05Z

저장소 관리 후속

PR #33의 로컬 검증은 완료됐지만 GitHub statusCheckRollup이 비어 있는 이유를 확인했습니다.

현재 AI 저장소에는 main push용 deploy workflow만 있고, develop 대상 PR에서 pytest/Ruff를 실행하는 CI가 없습니다. #33 기능 범위와 분리해 후속 이슈 #34로 등록하고 hywznn에게 할당했습니다.

추적 이슈: chore(ci): develop PR pytest·Ruff 자동 검증 추가 #34
일반 PR CI: 외부 Secret 없이 pytest + Ruff
BERT/A.X 실모델 smoke: 모델·장치가 필요한 별도 protected workflow 또는 수동 검증
전체 Ruff의 기존 E501 7건도 #34에서 정리

따라서 현재 “checks 없음”은 #33의 CI 실패가 아니라 PR CI 자체가 아직 없는 상태입니다.

PR #33 dev ->main

hywznn added 3 commits August 11, 2026 18:20

fix(intent): integrate Knowledge A.X contract (#32)

d1d5b7d

fix(intent): reuse PLAN decision in ANALYZE (#32)

d2a325c

docs(intent): record ANALYZE confidence policy (#32)

8d776e8

hywznn marked this pull request as ready for review August 11, 2026 10:33

hywznn requested review from BcKmini and krestar August 11, 2026 10:38

fix(intent): harden workflow routing and readiness (#32)

ec3772c

krestar approved these changes Aug 11, 2026

View reviewed changes

hywznn mentioned this pull request Aug 11, 2026

AI PLAN 결정을 ANALYZE에 재사용 fowoco/server#138

Merged

13 tasks

fix(workflow): preserve renewal task workflow (#32)

35d92fa

This was referenced Aug 11, 2026

fix(intent): Knowledge A.X 프롬프트와 PLAN 결정 계약 통합 #32

Closed

chore(ci): develop PR pytest·Ruff 자동 검증 추가 #34

Open

hywznn mentioned this pull request Aug 11, 2026

Renewal 실행 결과를 기존 업무·안내 초안·생성 문서에 연결 fowoco/server#131

Merged

16 tasks

krestar merged commit ae91af2 into develop Aug 11, 2026

krestar mentioned this pull request Aug 11, 2026

PR #33 dev ->main #35

Merged

hywznn mentioned this pull request Aug 11, 2026

[Observability][P1] Server·AI Runtime 추적과 운영 지표 고도화 fowoco/server#26

Closed

27 tasks

hywznn added a commit that referenced this pull request Aug 13, 2026

Merge pull request #35 from fowoco/develop

8eec3c1

PR #33 dev ->main

hywznn mentioned this pull request Aug 13, 2026

[Intent][P1] Evidence span·model route·fallback reason 계약 보강 #43

Open

16 tasks

Navigation Menu

Uh oh!

fix(intent): Knowledge A.X 프롬프트와 PLAN 재사용 계약 통합 - #33

fix(intent): Knowledge A.X 프롬프트와 PLAN 재사용 계약 통합#33
krestar merged 5 commits into
developfrom
fix/32-ax-knowledge-prompt-contract

hywznn commented Aug 11, 2026 •

edited

Loading

Uh oh!

krestar left a comment

Uh oh!

hywznn commented Aug 11, 2026

Uh oh!

hywznn commented Aug 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

hywznn commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

한 줄 요약

용어와 책임

최종 호출 흐름

주요 변경 사항

1. Knowledge A.X 프롬프트 연결

2. A.X 출력 검증과 fallback

3. PLAN 응답과 confidence 계약

4. ANALYZE에서 PLAN 결정 재사용

5. Workflow 선택 및 Renewal Task 보존

6. OUT_OF_SCOPE terminal outcome

7. Startup warmup과 readiness

Server 연동 상태

Server #138 — PLAN/ANALYZE 및 OUT_OF_SCOPE

Server #131 — Renewal Task Workflow 재사용

운영 설정

검증 결과

병합 체크리스트

Uh oh!

krestar left a comment

Choose a reason for hiding this comment

Uh oh!

hywznn commented Aug 11, 2026

Server #131 연동 후속 보완

확인된 문제

반영 내용

Server canonical pair

검증

아직 남은 통합 확인

Uh oh!

hywznn commented Aug 11, 2026

저장소 관리 후속

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

hywznn commented Aug 11, 2026 •

edited

Loading