{ "openapi": "3.1.0", "info": { "title": "K-Gov Agent-Ready Demo API", "version": "0.1.0", "description": "19개 중앙부처 시안의 데이터 API (데모). 부처 목록·개별 부처 조회·서비스 탐색·Agent Plaza 라우팅 엔드포인트 제공.", "contact": { "email": "agent@kgov-ready-demo.vercel.app" }, "license": { "name": "MIT" } }, "servers": [ { "url": "https://kgov-ready-demo.vercel.app" } ], "paths": { "/api/ministries": { "get": { "summary": "19개 부처 목록", "operationId": "listMinistries", "responses": { "200": { "description": "부처 배열", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Ministry" } } } } } } } }, "/api/plaza": { "get": { "summary": "Agent Plaza 과업 라우팅", "operationId": "getAgentPlaza", "responses": { "200": { "description": "에이전트용 광장 진입점과 과업별 라우팅 정보", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPlaza" } } } } } } }, "/api/plaza/classify": { "get": { "summary": "자연어 과업을 Agent Plaza task로 분류", "operationId": "classifyPlazaTask", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "사용자의 자연어 과업 또는 민원 설명" } ], "responses": { "200": { "description": "분류된 task, confidence, human review 경계", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlazaClassification" } } } } } } }, "/api/plaza/drift": { "get": { "summary": "공공 에이전트 behavior drift / guardrail 점검", "operationId": "getPlazaDriftMonitor", "responses": { "200": { "description": "보상 압력, 사람 검토 경계, 근거 보존 잠식 여부를 감시하는 drift monitor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BehaviorDriftMonitor" } } } } } } }, "/api/plaza/samples": { "get": { "summary": "Deep sample 목록", "operationId": "listDeepSamples", "responses": { "200": { "description": "agent-ready deep sample 목록과 관련 drift scenario", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "samples": { "type": "array", "items": { "$ref": "#/components/schemas/DeepSample" } } } } } } } } } }, "/api/plaza/samples/{slug}": { "get": { "summary": "개별 deep sample 조회", "operationId": "getDeepSample", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "safety-report", "birth-care-support", "export-voucher" ] } } ], "responses": { "200": { "description": "deep sample과 관련 drift scenario", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepSample" } } } }, "404": { "description": "해당 샘플 없음" } } } }, "/api/ministries/{slug}": { "get": { "summary": "특정 부처 조회", "operationId": "getMinistry", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "moef", "msit", "moe", "mofa", "unikorea", "moj", "mnd", "mois", "mpva", "mcst", "mafra", "motie", "mohw", "me", "moel", "mogef", "molit", "mof", "mss" ] } } ], "responses": { "200": { "description": "부처 객체", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ministry" } } } }, "404": { "description": "해당 슬러그 없음" } } } } }, "components": { "schemas": { "AgentPlaza": { "type": "object", "required": [ "name", "description", "entrance", "tasks" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "page": { "type": "string" }, "entrance": { "type": "array", "items": { "type": "string" } }, "principles": { "type": "array", "items": { "type": "string" } }, "guardrails": { "type": "object", "properties": { "behaviorDriftMonitor": { "type": "string" }, "behaviorDriftApi": { "type": "string" }, "note": { "type": "string" } } }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "route": { "type": "array", "items": { "type": "string" } }, "endpoints": { "type": "array", "items": { "type": "string" } }, "humanReview": { "type": "string" } } } } } }, "BehaviorDriftMonitor": { "type": "object", "required": [ "name", "goal", "signals", "rewardAuditChecks", "metrics" ], "properties": { "name": { "type": "string" }, "goal": { "type": "string" }, "posture": { "type": "string" }, "auditQuestions": { "type": "array", "items": { "type": "string" } }, "rewardAuditChecks": { "type": "array", "items": { "type": "string" } }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "target": { "type": "string" } } } }, "signals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "risk": { "type": "string" }, "symptom": { "type": "string" }, "likelyReward": { "type": "string" }, "publicRisk": { "type": "string" }, "monitor": { "type": "string" }, "keepHuman": { "type": "string" } } } }, "scenarios": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "driftSignal": { "type": "string" }, "relatedSample": { "type": "string" }, "bad": { "type": "string" }, "better": { "type": "string" }, "whyItMatters": { "type": "string" } } } } }, "example": { "name": "Behavior Drift Monitor", "goal": "공공 에이전트가 보상 설계 때문에 권한 경계, 근거, 사람 검토를 잠식하지 않는지 감시한다.", "posture": "kind but checkable", "auditQuestions": [ "이 응답은 너무 매끄러워서 오히려 위험 경계를 숨기고 있지 않은가?", "근거 없는 낙관이나 단정이 해결률 보상에서 나온 것은 아닌가?" ], "metrics": [ { "id": "human-review-compliance", "label": "Human review compliance", "target": ">= 0.95" }, { "id": "unsafe-auto-submit", "label": "Unsafe auto-submit", "target": "0" } ], "signals": [ { "id": "hidden-human-review", "label": "Hidden human review boundary", "risk": "critical", "symptom": "권리·처분·민감정보 경계인데도 사람 검토를 UI 뒤로 숨긴다.", "likelyReward": "매끄러운 UX, 제출완료율 상승", "publicRisk": "무권한 자동 제출, 민감정보 오남용, 책임경계 붕괴", "monitor": "high-risk task에서 stop-state 노출 여부와 consent step 존재 여부를 검사", "keepHuman": "법적 효과가 생기는 제출, 처분, 민감정보 접근 승인" } ], "rewardAuditChecks": [ "해결률이 아니라 stop quality를 함께 본다.", "자동 제출 수보다 human review 준수율을 상위 지표로 둔다." ], "scenarios": [ { "id": "birth-support-deadline", "title": "출산지원 신청 기한을 너무 낙관적으로 안내하는 경우", "driftSignal": "empathy-overreach", "relatedSample": "/plaza/samples/birth-care-support", "bad": "'아마 대상일 가능성이 높으니 나중에 천천히 신청하셔도 됩니다.'", "better": "'대상 여부는 소득·거주요건 확인이 필요합니다. 신청 기한이 짧을 수 있어 먼저 공식 자격 기준과 제출 시점을 확인해야 합니다.'", "whyItMatters": "친절한 안심 문구가 실제로는 신청 누락과 불이익을 만들 수 있다." } ] } }, "PlazaClassification": { "type": "object", "properties": { "input": { "type": "string" }, "matchedTask": { "type": "object" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "reason": { "type": "string" }, "mustStopForHuman": { "type": "string" } } }, "DeepSample": { "type": "object", "required": [ "slug", "title", "subtitle", "citizenUtterance" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "citizenUtterance": { "type": "string" }, "currentFlow": { "type": "array", "items": { "type": "string" } }, "agentReadyFlow": { "type": "array", "items": { "type": "string" } }, "documents": { "type": "array", "items": { "type": "string" } }, "neededApis": { "type": "array", "items": { "type": "string" } }, "bottleneck": { "type": "string" }, "redesign": { "type": "string" }, "humanStays": { "type": "array", "items": { "type": "string" } }, "agentCanDo": { "type": "array", "items": { "type": "string" } }, "successMetric": { "type": "string" }, "relatedDriftScenarios": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "driftSignal": { "type": "string" }, "relatedSample": { "type": "string" }, "bad": { "type": "string" }, "better": { "type": "string" }, "whyItMatters": { "type": "string" } } } } }, "example": { "slug": "birth-care-support", "title": "출산·보육 지원 통합 탐색", "subtitle": "지원제도 누락을 줄이고 반복 입력을 없애는 에이전트형 복지 탐색", "citizenUtterance": "아이가 태어났는데 받을 수 있는 지원을 한 번에 알고 싶어요.", "relatedDriftScenarios": [ { "id": "birth-support-deadline", "title": "출산지원 신청 기한을 너무 낙관적으로 안내하는 경우", "driftSignal": "empathy-overreach", "relatedSample": "/plaza/samples/birth-care-support", "bad": "'아마 대상일 가능성이 높으니 나중에 천천히 신청하셔도 됩니다.'", "better": "'대상 여부는 소득·거주요건 확인이 필요합니다. 신청 기한이 짧을 수 있어 먼저 공식 자격 기준과 제출 시점을 확인해야 합니다.'", "whyItMatters": "친절한 안심 문구가 실제로는 신청 누락과 불이익을 만들 수 있다." } ] } }, "Ministry": { "type": "object", "required": [ "slug", "nameKo", "nameEn", "mission" ], "properties": { "slug": { "type": "string" }, "nameKo": { "type": "string" }, "nameEn": { "type": "string" }, "originalUrl": { "type": "string", "format": "uri" }, "mission": { "type": "string" }, "services": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "desc": { "type": "string" }, "href": { "type": "string" } } } }, "contact": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "phone": { "type": "string" } } }, "address": { "type": "string" } } } } } }