Architecture
모델 호출을 한 파이프라인에 몰아넣지 않습니다.
credential의 execution_profile이 경로를 고르고, 그 앞에 Gateway 거버넌스가 있습니다.
- Auth
- DLP
- Rate Limit
- Cost
- Audit
- Execution Profile
Agent가 이미 계획·도구 루프를 가지고 있으면 Runtime을 겹치지 않습니다.
- Router — Requested Interaction / Execution Boundary
- Runtime — Evidence / Policy / Governed Execution
불변 조건
GoVail은 공유 모델 인프라, 범용 프롬프트 품질, 실행 거버넌스를 맡습니다. Application 상태, 도메인 워크플로우, 에이전트 루프는 Core 밖에 둡니다.
기능을 더할지 말지는 이 문장으로 먼저 봅니다.
경로를 나눈 이유
Coding Agent는 이미 저장소와 도구 루프를 가지고 있습니다. 그 위에 Runtime 계획 루프를 올리면 일이 겹칩니다.
대화형 클라이언트는 반대입니다. 최신 사실이나 외부 write를 모델 응답만으로 확정하면 위험합니다. 이쪽은 Router와 Runtime을 탑니다.
Credential Identity > Semantic Guessgv_code_... / gv_web_... prefix와 클라이언트 헤더는 식별용입니다. 권한 SSOT는 서버측 metadata입니다.
CODE / Thin Path
execution_profile = agentic_coding
OpenCode, Codex, Claude Code처럼 Agent가 이미 루프를 가진 경우입니다.
Client → Gateway (Auth, DLP, Rate Limit, Cost, Audit)
→ LLM Direct ProxyRouter와 Runtime은 우회합니다. Gateway는 인프라 안전만 집행하고, Agent 루프는 클라이언트가 유지합니다.
WEB / Governed Path
execution_profile = governed_web
GoVail Web과 일반 대화형 클라이언트용입니다.
Client → Gateway
→ Router /decide
→ Runtime (필요할 때만)
→ Model요청 경로 및 실행 거버넌스 파이프라인
요청에서 실행까지의 검증 단계
- Auth: API Key & Profile SSOT
- DLP: PII/Secret 패턴 차단
- Cost: 토큰 및 Rate Limit 통제
- Routing: CODE vs WEB 분기
- Route Target:
llmvsruntime - Execution Mode: direct / workflow / approval
- Side Effect: read vs write/execute
- Boundary: 실행 권한 분리
- Evidence: 최신 사실·엔티티 취득
- Grounding: 근거-주장 정합성 검증
- Approval: 변경 작업 Payload Hash 검증
- Durable: Fail-closed 안전 실행
- Schema: 정형 이벤트 스트림
- Audit Trail: 요청-판단-실행 전 과정 불변 기록
- Contract: 크로스 서비스 무결성
- Observability: Prometheus / Loki
Router는 답을 직접 생성하지 않고 요청의 실행 경계만 고릅니다.
| Router 필드 | 타입 | 의미 |
|---|---|---|
route_target | llm | runtime | 직행 LLM 프록시인지 거버넌스 런타임 경유인지 판정 |
execution_mode | direct | workflow | approval | 동기 실행, 비동기 워크플로우, 사전 승인 대기 구분 |
side_effect | none | read | write | execute | admin | 외부 시스템 변경 수준 식별 |
approval_required | boolean | 외부 Write 및 파괴적 명령에 대한 승인 필수 여부 |
Requested Interaction은 의미의 확정이 아니라 경로 후보입니다. Knowledge Dependency와 Evidence 취득은 Runtime이 담당합니다.
Core 책임
Gateway — Implemented
Rust / Axum. OpenAI 호환 진입점.
- Authentication, API Key
- DLP
- Rate limiting, cost tracking
- Model policy
- Audit
- Execution Profile 분기
- Runtime SSE → OpenAI
chat.completion.chunk
retrieval, planning, query rewrite, semantic routing은 Gateway 일이 아닙니다.
Router — Implemented
Python / FastAPI. 상태 없는 결정 서비스.
/decide가 실행 경계만 반환- 입력은 원문이 아니라
RoutingSummary - 세션, RAG, agent loop를 소유하지 않음
자명한 대화는 llm / direct. 외부 사실이나 write는 runtime.
Runtime — Implemented
Python / FastAPI. 대화 품질 경로와 외부 실행 경로를 같은 무게로 다루지 않습니다.
Conversational path
- advisory hint (intent, entity, freshness, retrieval)
- Evidence acquisition, grounding
- 원문 user message는 바꾸지 않음
- 검색 실패를 “없다”의 증거로 쓰지 않음
Governed execution path
- 외부 write, 승인, payload hash, provenance, audit
- 대기·재시도가 필요한 작업만 durable execution
V1에서 제품으로 말하는 governed capability는 repository review와 승인된 GitHub Issue 생성입니다. 소설 파이프라인 같은 이전 워크플로우는 호환용입니다.
Contracts — Implemented
OpenAPI / JSON Schema가 서비스 사이 SSOT입니다. route-decision, audit-event, claim-grounding, runtime-run을 한곳에서 맞춥니다.
Companion
GoVail MCP는 Core가 아닙니다. 앱이 가진 context를 MCP로 내보내는 계약/SDK입니다. DB와 workflow 소유권은 앱에 남습니다.
Core가 아닌 것
| 항목 | 위치 | 이유 |
|---|---|---|
| Scanner | Archived | 현재 요청 경로가 아님 |
| 중앙 Memory | Experimental | 앱 상태 경계를 넘기 쉬움. 현재 전역 비활성 |
| 범용 Agent Runtime | Out of Core | 루프는 Client / Application 책임 |
| 도메인 Workflow | App-owned | 소설 파이프라인 등은 Core 밖 |
당시 기록은 Engineering Log에 있습니다.
LiteLLM, Temporal, LangGraph는 구현 수단입니다. 제품 이름처럼 앞에 두지 않습니다.
사용 방법 · Decisions · Validation