MAO Prompt Ops API Contract

모든 엔드포인트는 /api/admin/prompt-console/*를 통해 BFF(Route Handler)에서 내부 Prompt Service/Observability API로 프록시한다. 기본 응답 포맷은 JSON, 인증은 Admin 세션 쿠키 사용.

1. Prompt Templates

1.1 GET /templates

항목	내용
Query	agentType? status? search? page pageSize
Response	{ items: PromptTemplate[], total: number }

PromptTemplate:

{
  "id": "tmpl_123",
  "agentType": "SUPERVISOR",
  "version": "v2025-11-01",
  "status": "DRAFT|REVIEW|ACTIVE|DEPRECATED",
  "modelProfileId": "model_profile_vertex_gemini_flash",
  "slotMeta": { "context": "...", "dataReadiness": "READY" },
  "updatedBy": "bok@weltcorp.com",
  "updatedAt": "2025-11-01T12:00:00Z"
}

1.2 POST /templates

Body	예시
{ "agentType": "CBTI_THERAPIST", "content": "...", "slotMeta": {...}, "sourceTemplateId?": "tmpl_101" }	신규/Duplicate 생성

Response: 201 Created + { id: "tmpl_123", version: "v2025-11-01" }

1.3 PATCH /templates/{id}

Body	설명
{ "content": "...", "slotMeta": {...}, "status?": "REVIEW" }	Draft 업데이트 또는 Review 요청

1.4 GET /templates/{id}

상세 + Diff:

{
  "template": { ...PromptTemplate, "content": "...", "slotMeta": {...} },
  "diff": { "previousVersion": "v2025-10-15", "changes": "..." },
  "reviews": [ { "reviewer": "ops@welt", "status": "APPROVED", "comment": "...", "createdAt": "..." } ]
}

1.5 POST /templates/{id}/reviews

| Body | { "comment": "Need CTA tone tweak", "status": "APPROVED|REJECTED" } |

2. Deployments

2.1 POST /deployments

Body	예시
{ "templateId": "tmpl_123", "environment": "CANARY", "rolloutPlan": { "trafficPercent": 20, "durationMinutes": 120 }, "metricsGate": { "routingAccuracy": 0.8, "ctaConversionDelta": -0.05 } }

Response: { "deploymentId": "dep_456", "state": "IN_PROGRESS" }

2.2 POST /deployments/{id}/promote

Promote CANARY→PROD. Body 예: { "note": "Canary stable" }

2.3 POST /deployments/{id}/rollback

Body: { "reason": "Guardrail violation" }

2.4 GET /deployments/{id}

{
  "deploymentId": "dep_456",
  "templateId": "tmpl_123",
  "modelProfile": {
    "id": "model_profile_vertex_gemini_flash",
    "provider": "vertex",
    "modelName": "gemini-1.5-flash",
    "fallback": [
      { "provider": "openai", "modelName": "gpt-4o-mini" },
      { "provider": "anthropic", "modelName": "claude-3-5-sonnet" }
    ]
  },
  "environment": "CANARY",
  "state": "IN_PROGRESS|PAUSED|ROLLED_BACK|COMPLETED",
  "rolloutPlan": {...},
  "metrics": { "routingAccuracy": 0.82, "ctaConversionDelta": -0.01 },
  "guardrailEvents": [ ... ],
  "timeline": [
    { "ts": "...", "event": "STARTED" },
    { "ts": "...", "event": "GUARDRAIL_TRIGGER", "details": {...} }
  ]
}

3. Experiments

3.1 GET /experiments

List with pagination.

3.2 POST /experiments

{
  "name": "Routing Weight Test",
  "targetAgents": ["SUPERVISOR", "CBTI_THERAPIST"],
  "bucketConfig": [
    { "label": "Control", "templateId": "tmpl_base", "trafficPercent": 50 },
    { "label": "VariantA", "templateId": "tmpl_new", "trafficPercent": 50 }
  ],
  "metricsGate": { "routingAccuracy": 0.75 },
  "durationMinutes": 720
}

3.3 PATCH /experiments/{id}

Update status (e.g., PAUSED, COMPLETED) 또는 버킷 비율 조정.

4. Metrics & Guardrails

4.1 GET /metrics

• Query: agentType?, window (15m/1h/1d)
• Response: { "series": { "routingAccuracy": [...], "ctaConversion": [...], "latencyP95": [...], "tokenUsage": [...] }, "lastUpdated": "..." }
• SSE: GET /metrics/stream (text/event-stream)

4.2 GET /guardrail-events

| Query | severity?, promptVersion?, limit? | | Response | { items: [ { "id": "gr_1", "policyId": "P01", "severity": "HIGH", "promptVersion": "v2025-11-01", "samplePayload": "masked...", "timestamp": "..." } ] } |

5. Model Profiles & LLM 설정

5.1 GET /model-profiles

• Query: provider?, search?, page, pageSize
• Response: { items: ModelProfile[], total: number }

ModelProfile 예시:

{
  "id": "model_profile_vertex_flash",
  "name": "Gemini 1.5 Flash (Routing)",
  "provider": "vertex",
  "modelName": "gemini-1.5-flash",
  "maxOutputTokens": 2048,
  "temperature": 0.4,
  "topP": 0.95,
  "fallbackChain": [
    { "provider": "openai", "modelName": "gpt-4o-mini" },
    { "provider": "anthropic", "modelName": "claude-3-5-sonnet" }
  ],
  "updatedAt": "2025-11-01T12:00:00Z",
  "updatedBy": "prompt-ops@welt"
}

5.2 POST /model-profiles

• Body: { "name": "...", "provider": "vertex|openai|anthropic", "modelName": "...", "parameters": { "temperature": 0.2, "maxOutputTokens": 4096 }, "fallbackChain": [...] }
• Response: { "id": "model_profile_xyz" }

5.3 PATCH /model-profiles/{id}

• Body: { "parameters": {...}, "fallbackChain": [...], "status": "ACTIVE|DEPRECATED" }

5.4 POST /templates/{id}/model-binding

• Body: { "modelProfileId": "model_profile_vertex_flash", "effectiveFrom": "2025-11-02T00:00:00Z" }
• Response: { "bindingId": "bind_123", "status": "PENDING_APPROVAL" }

5.5 GET /model-quotas

• Response: { "items": [ { "provider": "openai", "dailyTokenLimit": 5_000_000, "currentUsage": 1_240_000, "costPer1KTokens": 0.002 } ] }

6. Tool Management

6.1 GET /tools

• Query: provider?, type?, search?, page, pageSize
• Response: { items: ToolDefinition[], total: number }

6.2 POST /tools

• Body: { "id": "tool-http-search", "name": "...", "provider": "internal|gemini|openai", "type": "http|function|workflow", "config": {...}, "parameters": {...JSON Schema...} }
• Response: { id: "tool-http-search" }

6.3 POST /agents/{agentId}/tools/{toolId}

• Body: { "enabled": true, "config": {...} }
• Response: { bindingId: "bind_123", "enabled": true }

6.4 GET /tools/invocations

• Query: agentId?, toolId?, status?, from?, to?, page, pageSize
• Response: { items: ToolInvocation[], total: number }

7. RAG (Managed File Search)

7.1 POST /rag/index

• 목적: 외부 File Search Store 메타 등록(예: Gemini File Search vector_db 이름) 및 파일 추가 요청
• Body 예시:

{
  "storeName": "legal_docs",
  "provider": "gemini",
  "files": [
    { "uri": "files/abc123", "displayName": "Contract 2024" }
  ],
  "metadata": { "domain": "legal" }
}

• Response: { storeId: "store_legal_docs", "status": "INDEXING" }

7.2 GET /rag/query-logs

• Query: agentId?, taskId?, search?, page, pageSize
• Response: { items: RagQueryLog[], total: number } (query, topK, filters, retrievedChunkIds 포함)

8. 에러 처리

코드	의미	예시
400	Validation 실패	SlotMeta 누락, metricsGate 형식 오류
403	권한 부족	prompt.deploy scope 없음
409	상태 충돌	Draft가 REVIEW 상태일 때 수정
422	Guardrail 기준 미충족	Canary Promote 시
500	내부 오류	Upstream 서비스 실패

Error Body:

{ "error": "VALIDATION_FAILED", "message": "slotMeta.context is required" }

7. 트레이싱 & 로깅

• 모든 API 호출은 x-admin-user 헤더를 삽입해 감사 로그와 연동.
• Route Handler에서 traceId를 생성해 Observability Stack과 연결.

---

이 계약은 2025-11-17 기준 초안이며, 필드 추가 시 버전 필드를 명시하거나 Query include=content,diff 식 옵션을 제공한다.