Agentic 성숙도 가이드라인 — 한국 공공 API의 AI 에이전트 준비도

생성일: 2026-08-03
단일 소스: 이 문서는 data/rubric.json(version 1.0)에서 렌더된다. 루브릭 JSON은 가이드라인 문서와 대시보드 채점(scripts/build_rubric_scores.py)이 공유하는 단일 정규 기준(normative anchor)이다.
대상: 행정안전부, NIA, 공공데이터전략위원회, data.go.kr 운영팀, 공공 API 설계자
관점 전환: AI 에이전트 시대에는 사람이 아니라 기계(LLM 에이전트)가 공공 API의 주 소비자다. 이 가이드라인은 "사람이 쓰기 좋은 API"가 아니라 "에이전트가 스스로 발견·인증·호출·복구할 수 있는 API"를 7개 기둥으로 정의한다.

성숙도 채점 방식

각 기둥은 매핑된 지표(probe REGISTRY 키)의 Result 점수(0/1/2)를 평균해 Level 0~3으로 환산한다.

data.go.kr 현재 위치 주의: 아래 각 기둥의 "data.go.kr 현재" 레벨은 before_baseline.json(2026-04 스냅샷)의 알려진 사실과 gapi 실증 분석에 기반한 추정치다. Task 9 라이브 프로브가 실행되면 각 기둥의 정확한 현재 Level이 채워진다.

7개 기둥 (Agentic 준비도 우선순위 순)

우선순위는 "에이전트 자동화를 막는 정도"로 정렬했다. 상위 기둥일수록 실패 시 에이전트 파이프라인 전체가 즉시 깨진다.

1. 정직한 HTTP (Honest HTTP) — honest_http

지표: http_semantics, error_self_desc, rate_limit_transparency

왜 에이전트에 필요한가: 에이전트는 HTTP 상태코드로 성공/실패를 자동 분기하고 재시도·백오프한다. 오류에 200을 반환하면 표준 HTTP 클라이언트(requests·axios·fetch)가 모두 무력화되고 무한 재호출·잘못된 성공 판정이 발생한다. Level 3의 429/Retry-After/RateLimit 백프레셔 약속은 rate_limit_transparency 지표가 실측하므로, 이 지표를 포함해야 채점이 그 약속을 실제로 반영한다.

Level 서술
0 모든 상황에서 200 OK를 반환하고 실제 오류를 응답 바디에만 담는다. 상태코드로 성공/실패를 구분할 수 없다.
1 일부 오류에 상태코드를 쓰지만 불완전·비일관적(예: 500만 있고 401/404/429 없음)이다.
2 표준 HTTP 상태코드(400/401/403/404/409/429/500)를 상황에 맞게 일관되게 사용한다.
3 표준 상태코드 + RFC 9457(구 7807) Problem Details 구조화 오류(type/title/status/detail/instance) + 429와 함께 Retry-After/RateLimit 헤더로 백프레셔를 신호한다.

data.go.kr 현재 (추정 Level 0): 인증 실패·파라미터 오류·리소스 부재 모두 200 OK + 바디 resultCode로 반환(http_semantics=0, error_self_desc=0, rate_limit_transparency=0 — Retry-After/RateLimit 헤더 부재). Task 9 라이브 프로브로 확정.

참조:

2. 구조화 포맷 (Structured Format) — structured_format

지표: json_native, data_format

왜 에이전트에 필요한가: JSON은 LLM이 바로 파싱·생성하는 네이티브 구조다. XML 기본값은 토큰을 약 2.5배 소모하고 게이트웨이 오류 시 강제 XML로 되돌아가 에이전트 파이프라인을 깨뜨린다.

Level 서술
0 XML 전용 또는 XML 기본값. JSON은 없거나 별도 파라미터로만 가능하며 오류 시 XML로 강제 회귀한다.
1 JSON을 지원하나 기본값은 XML이라 ?type=json 등 명시가 필요하고, 일부 경로에서 여전히 XML을 반환한다.
2 JSON이 기본 응답이며 정상/오류 경로 모두 일관된 JSON을 반환한다.
3 JSON 기본 + 콘텐츠 협상(Accept 헤더)으로 포맷 선택, ISO 8601 날짜·UTF-8 등 표준 데이터 표현을 준수하고 최상위 객체로 메타데이터 확장이 가능하다.

data.go.kr 현재 (추정 Level 1): format.default=xml이나 JSON 지원(supports_json=true, json_native=1). 게이트웨이 오류 시 XML 강제 회귀 문제가 남아 있어 Level 2에 미달. Task 9로 확정.

참조:

3. 기계 발견성·자기설명 (Machine Discovery & Self-description) — machine_discovery

지표: machine_schema, llms_txt

왜 에이전트에 필요한가: 에이전트는 사람이 읽는 HWP/웹페이지를 파싱할 수 없다 — 기계판독 스키마와 진입점이 있어야 API를 스스로 발견·이해·호출할 수 있다.

Level 서술
0 기계판독 명세 전무. 문서가 HWP/PDF/HTML 산문뿐이라 에이전트가 엔드포인트·파라미터를 추론할 수 없다.
1 부분적 구조화 문서(포털 내 표 형태 파라미터 설명 등)는 있으나 표준 OpenAPI 문서나 llms.txt는 없다.
2 유효한 OpenAPI 3.x 명세를 제공해 함수 호출/코드젠이 가능하다. 다만 사이트 수준 AI 진입점(llms.txt)은 없다.
3 OpenAPI 3.x 명세 + llms.txt(또는 동급 AI 진입점)를 함께 제공해 에이전트가 카탈로그부터 개별 엔드포인트까지 자기설명적으로 발견한다.

data.go.kr 현재 (추정 Level 0): technical.openapi_spec=false, machine_schema=0, llms.txt 없음. API 문서가 HWP/포털 텍스트 위주라 이것이 MCP 커버리지 5% 미만의 핵심 원인. Task 9로 확정.

참조:

4. 도구 네이티브 접근 (Tool-native Access) — tool_native

지표: tool_native

왜 에이전트에 필요한가: 에이전트는 API를 '도구(tool)'로 호출한다. MCP 서버나 함수 호출 스키마가 있으면 에이전트가 즉시 도구로 등록해 자연어로 데이터를 조회하지만, 없으면 개발자가 수동 래퍼를 만들어야 해 커버리지가 5% 미만에 머문다.

Level 서술
0 MCP 서버·함수 호출 스키마가 전무. 에이전트가 API에 접근하려면 사람이 수동으로 래퍼 코드를 작성해야 한다.
1 비공식 커뮤니티 MCP/툴 래퍼가 일부 존재하나 유지·책임 주체가 불명확하고 부분 커버리지다.
2 OpenAPI 명세 기반으로 MCP 서버/함수 호출 도구를 안정적으로 생성할 수 있는 상태(자동 생성 가능).
3 정부/기관이 공식 운영하는 MCP 서버로 카탈로그 전체를 도구로 노출하고 Claude·ChatGPT·Gemini 등 주요 클라이언트와 호환된다(프랑스 data.gouv.fr, 미국 GovInfo 모델).

data.go.kr 현재 (추정 Level 1): 공식 MCP 없음. 비공식 커뮤니티 구현(Koomook/data-go-mcp-servers, ceami/opendata-mcp)이 존재하나 부분 커버·유지주체 불명확. Task 9로 확정.

참조:

5. 에이전트 인증 (Agent Authentication) — agent_auth

지표: programmatic_auth

왜 에이전트에 필요한가: 자율 에이전트는 서버 간(machine-to-machine) 무인 실행이 기본이다. URL 쿼리에 노출되고 2년마다 수동 갱신하는 API Key는 로그 유출과 운영 중 서비스 중단을 유발한다 — 토큰 자동 갱신과 헤더 전달이 필요하다.

Level 서술
0 인증키를 URL 쿼리 파라미터(?serviceKey=)로 전달하고 수동 갱신만 가능. 서버 로그·브라우저 히스토리·Referrer로 키가 노출된다.
1 API Key를 HTTP 헤더(Authorization / X-API-Key)로 전달할 수 있으나 여전히 장기 정적 키다.
2 OAuth 2.0 Client Credentials 등 토큰 기반 M2M 인증을 제공해 단기 토큰을 자동 발급·갱신한다.
3 OAuth 2.0/OIDC 기반 + scope 기반 최소권한, 자동 토큰 갱신, MCP 인가 흐름과 호환되는 표준 인증을 제공한다.

data.go.kr 현재 (추정 Level 0): auth.type=api_key_query, serviceKey URL 파라미터, 2년 수동 갱신(auto_renewal=false). serviceKey 이중 인코딩 버그까지 겹쳐 자동화 난이도가 높다. Task 9로 확정.

참조:

6. 데이터 제품화 (Data-as-a-Product) — data_product

지표: data_product, sdk_samples

왜 에이전트에 필요한가: 에이전트가 신뢰하고 통합하려면 데이터가 '제품'처럼 다뤄져야 한다 — SDK·샘플코드·샌드박스·SLA·명확한 메타데이터가 있어야 에이전트 개발자가 빠르게 검증·연동하고 프로덕션에서 안정적으로 소비한다.

Level 서술
0 SDK·샘플코드·샌드박스가 없고 데이터가 부산물처럼 방치된다. 검증하려면 실서버에 직접 호출해야 한다.
1 샘플코드나 커뮤니티 SDK가 일부 있으나 공식 지원·샌드박스·SLA가 없다.
2 공식 SDK/샘플 + 테스트 콘솔(Swagger UI)이나 DEMO_KEY로 회원가입 전 체험이 가능하다.
3 데이터를 제품으로 관리 — 공식 다국어 SDK, 샌드박스, SLA/유지관리 주체 명시, 재사용 친화 라이선스, 풍부한 메타데이터(DCAT-AP)로 EU HVD 수준의 제품화를 달성한다.

data.go.kr 현재 (추정 Level 1): technical.sandbox=false. 커뮤니티 SDK(WooilJeong/PublicDataReader)와 샘플코드는 존재하나 공식 SDK·샌드박스·SLA 부재. Task 9로 확정.

참조:

7. 통합 정체성·카탈로그 (Unified Identity & Catalog) — unified_identity

지표: unified_identity, signup_ease

왜 에이전트에 필요한가: 에이전트가 여러 API를 조합하려면 단일 신원·단일 진입점이 필요하다. 전체 커버에 ID 130개가 필요한 파편화 구조에서는 에이전트가 수십 개 계정을 관리할 수 없어 실질적 자동화가 불가능하다.

Level 서술
0 포털마다 별도 가입·별도 키가 필요하고 통합 카탈로그가 없다(전체 커버에 다수 ID 필요). 가입 절차도 무겁다.
1 일부 포털이 공통 게이트웨이/카탈로그에 연결되나 대부분은 원본 기관 별도 가입이 필요하다.
2 주요 포털이 단일 SSO/공통 키와 통합 API 카탈로그로 묶여 있고, 즉시 키 발급 등 가입이 간소하다.
3 국가 단일 신원 페더레이션(OAuth/OIDC 기반)과 통합 카탈로그로 1~3개 ID면 전 포털 접근 가능하고, 무인증 Key-Free 탐색 접근까지 제공(프랑스 FranceConnect, 싱가포르 SingPass, 영국 api.gov.uk 모델).

data.go.kr 현재 (추정 Level 1): data.go.kr 게이트웨이가 전체의 18%(31개 포털)만 커버하고 82%는 원본 기관 별도 가입 필요. 가입 난이도 medium(signup_ease=1), SSO 없음. Task 9로 확정.

참조:

data.go.kr 현재 위치 요약 (before_baseline 기반 추정)

기둥 추정 현재 Level 근거(before_baseline) 목표 Level
honest_http 0 항상 200 반환, error_self_desc=0, rate_limit_transparency=0 3
structured_format 1 JSON 지원하나 XML 기본값 3
machine_discovery 0 OpenAPI 없음, llms.txt 없음 3
tool_native 1 공식 MCP 없음, 비공식 커뮤니티만 3
agent_auth 0 serviceKey URL 파라미터, 수동 갱신 3
data_product 1 샌드박스 없음, 커뮤니티 SDK만 2→3
unified_identity 1 게이트웨이 18% 커버, SSO 없음 2→3
위 Level은 추정치이며 Task 9 라이브 프로브가 각 지표를 실측하면 scripts/build_rubric_scores.py가 정확한 현재 Level을 산출한다.

격차 + 제안 (data.go.kr 중심)

korea_improvement_roadmap.md의 즉시/중기/장기 3단계 구조를 계승하되, 각 항목을 Agentic 준비도 우선순위(어느 기둥을 얼마나 끌어올리는가)로 재정렬했다.

즉시 (0~6개월, 예산 최소 · 서버 설정 수준)

법령 개정·예산·기관 협의 없이 data.go.kr 운영팀 단독 착수 가능. 이 4개만으로 honest_http·structured_format을 L0→L2로 끌어올린다.

우선 개선안 대상 기둥 Level 효과 근거
★★★★★ HTTP 상태코드 정상화 (401/404/429/400/500) honest_http L0 → L2 오류에 4xx/5xx 반환. 에이전트 자동 에러 복구의 전제.
★★★★★ JSON 기본 응답 전환 (XML은 Accept 헤더 선택) structured_format L1 → L2 LLM 토큰 60% 절감, 게이트웨이 오류 시 JSON 회귀.
★★★★★ X-RateLimit / Retry-After 헤더 honest_http (백프레셔) L2 → L3 근접 429와 함께 잔여 한도 신호 → 에이전트 자동 속도조절.
★★★★ CORS 헤더 추가 (횡단: 브라우저 에이전트) — 브라우저 기반 AI 앱 직접 호출, 프록시 불필요.

중기 (6개월~2년, 정책·기관 협의 필요)

machine_discovery·agent_auth·data_product를 구조적으로 개선. OpenAPI 의무화가 tool_native 자동화의 선결조건.

우선 개선안 대상 기둥 Level 효과 근거
★★★★★ OpenAPI 3.x 명세 의무화 (HWP 문서 폐지) machine_discovery L0 → L2 MCP 서버·SDK·Swagger UI 자동 생성의 기반.
★★★★ RFC 9457 Problem Details 오류 표준화 honest_http L2 → L3 에이전트가 오류 원인 파악·자동 대응(키 갱신 등).
★★★★ API Key를 HTTP 헤더로 이동 (URL 노출 중단) agent_auth L0 → L1 로그·히스토리 키 유출 차단.
★★★★ 샌드박스 / DEMO_KEY 제공 data_product L1 → L2 회원가입 전 체험, 실서버 오염·한도 낭비 방지.
★★★★ 한국 정부 API 디자인 표준 제정 (GitHub 공개) (전 기둥 거버넌스) — 위 항목들을 신규 API에 계층적 의무화.

장기 (2~3년, 제도·인프라 전환)

agent_auth·tool_native·unified_identity를 최고 수준으로. 국가 단위 AI 네이티브 인프라.

우선 개선안 대상 기둥 Level 효과 근거
★★★★ 정부 공식 MCP 서버 운영 (data.go.kr 카탈로그) tool_native L1 → L3 프랑스 data.gouv.fr(4만 데이터셋, 7개 도구) 모델.
★★★ OAuth 2.0 / OIDC 전환 agent_auth L1 → L3 토큰 자동 갱신으로 무인 장기 운영, scope 최소권한.
★★★ 통합 인증 (API SSO) + 통합 게이트웨이 unified_identity L1 → L3 필요 ID 130개 → 1~3개. 정부24 신원 확장.
★★★ Key-Free 탐색 접근 (개인정보 없는 순수 공공데이터) unified_identity L2 → L3 진입 장벽 제로화(싱가포르 data.gov.sg 모델).

핵심 메시지

기계가 읽을 수 없는 XML(structured_format L0~1), 기계가 해석할 수 없는 200 오류(honest_http L0), 기계가 자동화할 수 없는 URL API Key(agent_auth L0) — 이 셋이 한국 공공 API의 AI 시대 적합성을 가로막는 최상위 3대 장벽이다. 이 셋은 모두 즉시~중기 서버 설정 수준에서 해결 가능하다. "데이터 공개량 세계 1위"에서 "에이전트가 쓸 수 있는 데이터 세계 1위"로의 전환은 기술이 아니라 거버넌스의 문제다.

다음 단계: Task 9 라이브 프로브 실행 → scripts/build_rubric_scores.py가 각 포털의 기둥별 실측 Level 산출 → 대시보드가 이 루브릭 기준으로 before/after 델타를 시각화한다.