OpenAPI SDK 생성 자동화: AI 코딩 에이전트 시대의 클라이언트 라이브러리 운영법

Google이 Speakeasy와 함께 OpenAPI 코드 생성 스위트를 오픈소스로 공개한 일은 단순한 도구 뉴스가 아닙니다. AI 코딩 에이전트를 제품 개발에 넣는 팀이라면 SDK 생성, CLI 생성, 문서 MCP 서버 생성이 왜 중요한 운영 레이어인지 봐야 합니다.

Google은 Interactions, Agents, Webhooks API의 새로운 GenAI SDK를 만들면서 Speakeasy와 협업했고, OpenAPI 생성 도구를 AGPLv3 라이선스로 공개한다고 밝혔습니다. 공개 범위에는 Python, TypeScript, Go, Java, C#, PHP, Ruby 등 7개 언어 SDK 생성, SSE 스트리밍, 재시도, 페이지네이션, 에이전트 네이티브 CLI, 문서 MCP 서버 생성이 포함됩니다.

문제: API 문서와 실제 SDK가 어긋나면 AI 에이전트가 더 크게 실패합니다

사람 개발자는 문서가 조금 틀려도 추론해서 고칠 수 있습니다. 타입 이름이 바뀌었거나 응답 필드가 누락되어도 로그를 보고 맞춥니다. 하지만 AI 코딩 에이전트는 낡은 문서와 실제 API가 어긋날 때 그럴듯한 코드를 만들어냅니다. 이 문제가 무서운 이유는 실패가 조용하다는 점입니다.

예를 들어 API 스펙에는 interaction.output_text가 있다고 되어 있는데 실제 SDK에서는 response.outputText로 바뀌었다고 합시다. 사람은 IDE 자동완성으로 금방 알아챌 수 있습니다. 반면 에이전트는 예전 문서 기반 코드를 생성하고, 테스트가 부족하면 PR까지 올라갑니다.

또 다른 예시는 스트리밍입니다. SSE, 재시도, 페이지네이션, 에러 계층은 손으로 구현할 때 버그가 자주 납니다. API가 빠르게 변하는 AI 제품에서는 이 부분을 매번 사람이 맞추기 어렵습니다.

원인: 생성기는 개발 보조 도구가 아니라 공급망입니다

Google 글에서 눈에 띄는 부분은 이전 SDK 생성 제공사가 인수 후 종료를 발표하면서 플랫폼 리스크가 드러났다는 대목입니다. SDK 생성기를 닫힌 도구에 의존하면 API 공급망의 중요한 부분이 외부 일정에 묶입니다.

OpenAPI는 인터페이스 정의의 표준 역할을 합니다. 하지만 스펙 파일만 있다고 SDK가 자동으로 좋은 품질이 되는 것은 아닙니다. 언어별 타입, 에러 처리, 스트리밍, 재시도, 페이지네이션, 문서 예제, CLI, MCP 서버까지 이어지는 파이프라인이 필요합니다. 이 파이프라인이 흔들리면 개발자 경험 전체가 흔들립니다.

AI 코딩 에이전트 시대에는 문제가 더 커집니다. 에이전트는 문서를 읽고 코드를 쓰며 터미널에서 명령을 실행합니다. 따라서 SDK뿐 아니라 CLI와 MCP 서버도 중요한 인터페이스가 됩니다. 에이전트가 최신 스키마를 질의할 수 있어야 추측 코드를 줄일 수 있습니다.

해결: OpenAPI를 단일 진실 공급원으로 만들어야 합니다

실무에서 가장 먼저 할 일은 OpenAPI 스펙을 “문서용 파일”이 아니라 “빌드 입력”으로 격상하는 것입니다. API 변경은 코드, 스펙, SDK, 문서, 예제, MCP 서버가 함께 움직여야 합니다.

권장 파이프라인은 다음과 같습니다.

백엔드 API 변경 PR에서 OpenAPI 스펙을 함께 수정합니다.
CI에서 스펙 lint와 breaking change 검사를 실행합니다.
스펙으로 SDK를 생성합니다.
생성된 SDK로 샘플 테스트를 실행합니다.
CLI와 문서 MCP 서버를 생성하거나 갱신합니다.
에이전트용 smoke test를 돌려 실제 작업 흐름을 확인합니다.

여기서 핵심은 “생성된 코드를 사람이 손으로 고치지 않는다”입니다. 예외 처리가 필요하면 생성기 설정, 템플릿, 스펙 확장 필드에 반영해야 합니다. 생성 결과를 직접 패치하면 다음 생성 때 사라지고, 팀은 다시 수동 작업에 갇힙니다.

AI 코딩 에이전트용 MCP 문서 서버가 필요한 이유

문서 MCP 서버는 단순 검색보다 강합니다. 에이전트가 “이 API의 최신 파라미터가 뭐야?”, “이 엔드포인트는 스트리밍을 지원해?”, “페이지네이션 응답 타입은 뭐야?” 같은 질문을 스키마 기반으로 확인할 수 있습니다.

일반 문서 페이지는 사람이 읽기 좋게 구성되어 있습니다. 하지만 에이전트에게는 정확한 메서드 이름, 타입, 필수 필드, 오류 코드, 예제 요청이 더 중요합니다. 문서 MCP 서버는 에이전트가 오래된 블로그 글이나 기억에 의존하지 않고 현재 스펙을 조회하게 만듭니다.

특히 사내 API가 많은 팀은 효과가 큽니다. AI 에이전트가 내부 API를 추측해서 호출하는 대신 MCP 서버에서 검증된 스키마를 가져오면 실패율이 줄어듭니다.

라이선스와 운영 리스크도 확인해야 합니다

Speakeasy 생성 스위트는 AGPLv3로 공개됐다고 설명됩니다. Google 글의 요지는 생성기를 개발 또는 CI 파이프라인에서 실행해도 생성된 SDK 코드의 소유권은 팀이 선택한 라이선스로 유지할 수 있다는 것입니다. 다만 생성기 자체를 수정해 배포하거나 서비스 형태로 제공하는 경우에는 AGPL 의무를 검토해야 합니다.

따라서 도입 전 법무 또는 오픈소스 정책 담당자와 다음을 확인해야 합니다.

생성기를 그대로 CI에서 실행하는지
생성기 코드를 수정하는지
수정한 생성기를 외부에 서비스로 제공하는지
생성된 SDK를 어떤 라이선스로 배포할지
사내 전용 SDK와 공개 SDK를 분리할지

이 검토를 건너뛰면 나중에 SDK 공개 시점에 문제가 생길 수 있습니다.

적용 예시: 작은 SaaS 팀의 현실적인 시작법

모든 언어 SDK를 한 번에 만들 필요는 없습니다. 작은 팀이라면 TypeScript와 Python부터 시작하는 것이 일반적입니다. TypeScript는 프론트엔드와 Node 백엔드, Python은 데이터·자동화·AI 사용자가 많기 때문입니다.

첫 달 목표는 다음 정도면 충분합니다.

OpenAPI 스펙 정리
breaking change 검사 추가
TypeScript SDK 자동 생성
Python SDK 자동 생성
README 예제 코드 자동 테스트
CLI 5개 명령만 생성
MCP 서버는 읽기 전용 스키마 조회부터 시작

이 정도만 해도 AI 코딩 에이전트가 내부 API를 사용할 때 추측이 크게 줄어듭니다.

실행 체크리스트

OpenAPI 스펙을 문서가 아니라 빌드 입력으로 관리합니다.
API 변경 PR에는 스펙 변경과 생성 SDK 테스트를 필수로 넣습니다.
생성된 SDK 파일을 직접 수정하지 않습니다. 수정이 필요하면 스펙 또는 생성기 설정을 바꿉니다.
TypeScript, Python처럼 실제 사용자가 많은 언어부터 시작합니다.
스트리밍, 재시도, 페이지네이션, 에러 계층을 샘플 테스트에 포함합니다.
AI 코딩 에이전트가 최신 스키마를 조회할 수 있도록 문서 MCP 서버를 검토합니다.
생성기 라이선스와 생성물 라이선스를 분리해서 확인합니다.
내부 API에도 같은 원칙을 적용합니다. 사내 API일수록 문서가 낡기 쉽습니다.

AI 시대의 개발자 경험은 문서 페이지 예쁘게 만드는 것으로 끝나지 않습니다. 사람이 쓰는 SDK, 터미널에서 실행하는 CLI, 에이전트가 질의하는 MCP 서버가 같은 스펙에서 나와야 합니다. OpenAPI SDK 생성 자동화는 편의 기능이 아니라 API 제품의 신뢰성을 지키는 운영 파이프라인입니다.