에이전트 시대 API는 더 명시적이어야 한다

좋은 API의 고객이 바뀐다

Freestyle의 Ben Swerdlow가 쓴 "Designing APIs for Agents"는 개발자 경험의 기본 가정을 뒤집는다. 사람을 위한 좋은 API는 짧은 예제, 좋은 기본값, 적은 설정, 친절한 SDK를 중시했다. 그러나 에이전트가 API의 주요 소비자가 되면 기준이 달라진다. 에이전트는 문서를 많이 읽고, 수십 개 필드를 채우고, 수천 줄 코드를 빠르게 생성할 수 있다. 반대로 모호한 이름과 암묵적 기본값에는 취약하다.

글은 에이전트에게 필요한 것이 "편리함"보다 "명확함"이라고 주장한다. 예를 들어 name이라는 필드는 표시 이름인지, 고유 ID인지, slug인지 맥락마다 다르다. 사람은 문서를 읽고 감으로 맞추지만, 에이전트는 비슷한 API의 기억에 끌려 잘못된 패턴을 만들 수 있다. displayName, externalId, workspaceSlug처럼 길고 구체적인 이름이 오히려 안전하다.

OpenAPI Specification은 사람과 컴퓨터가 서비스 기능을 이해할 수 있는 표준 인터페이스 설명을 목표로 한다. Model Context Protocol 사양은 LLM 애플리케이션이 외부 데이터와 도구에 연결되는 방식을 표준화한다. 이 두 흐름은 같은 방향을 가리킨다. API는 더 이상 사람 개발자만 읽는 문서가 아니라, 에이전트가 실행 계획을 세우는 계약서다.

기본값과 관용은 버그가 될 수 있다

사람을 위한 API에서는 관용이 장점이었다. 대소문자를 알아서 고치고, 여러 표현을 같은 값으로 받아들이고, 옵션을 생략하면 적절히 채워주는 방식이다. 그러나 에이전트가 만든 코드베이스에서는 이런 관용이 나중에 리뷰 비용을 키운다. 같은 의미를 여러 값으로 표현하면 에이전트는 파일마다 다른 관습을 만들고, 다음 에이전트나 사람이 그 차이를 다시 해석해야 한다.

좋은 오류 메시지도 달라진다. 사람에게는 오류가 좌절이지만, 에이전트에게는 경로 수정 신호다. 단, 오류가 정확해야 한다. "잘못된 요청"이 아니라 어떤 필드가 왜 틀렸고, 어떤 문서를 보아야 하며, 재시도 가능한지 알려줘야 한다. Vercel AI SDK는 여러 모델 호출을 일관된 함수로 다루게 하고, E2B 문서와 Daytona SDK 같은 샌드박스 제품은 에이전트 실행 환경의 계약을 제품화한다. 차이는 얼마나 명시적인가에 있다.

SDK의 역할은 줄어들까

Freestyle 글에서 가장 도발적인 부분은 SDK 회의론이다. 사람 개발자는 언어별 SDK가 없으면 시작을 꺼렸지만, 에이전트는 HTTP 문서와 OpenAPI를 읽고 직접 래퍼를 만들 수 있다. 따라서 SDK가 너무 많은 유틸리티와 숨은 동작을 품으면 오히려 에이전트가 디버깅하기 어려운 층이 된다. 에이전트에게 좋은 SDK는 마법 상자가 아니라 사실을 안정적으로 노출하는 얇은 층이어야 한다.

이 주장은 MPMC 큐와 에이전트 런타임 같은 시스템 설계 논의와도 이어진다. 에이전트가 실행하는 코드는 많아지고, 병렬 작업과 도구 호출도 늘어난다. 추상화가 편의보다 모호함을 더 많이 만들면 장애 지점이 늘어난다. Onboard-CLI 코드베이스 지도가 보여주듯 에이전트는 명시적 구조와 읽을 수 있는 맥락에서 더 잘 작동한다.

물론 SDK가 사라진다는 뜻은 아니다. 인증, 재시도, 스트리밍, 타입 생성, 감사 로그처럼 반복 실수를 줄이는 층은 여전히 필요하다. 다만 "사람이 몰라도 되게 숨기는" SDK에서 "에이전트가 정확히 알 수 있게 드러내는" SDK로 역할이 바뀐다. 한국 API 제품팀은 SDK 다운로드 수보다 에이전트가 문서를 읽고 첫 통합에 성공하는 비율을 지표로 삼아야 한다.

한국 B2B API 팀의 개편 포인트

첫째, API 문서의 모호한 필드명을 찾아 바꾼다. 기존 호환성 때문에 바로 바꿀 수 없다면 새 버전에서 명시적 alias를 제공하고, 구 필드는 deprecation 계획을 둔다. 둘째, 오류 메시지에 재현 가능한 원인과 수정 경로를 넣는다. 셋째, OpenAPI 스키마를 실제 동작과 맞추고 CI에서 검증한다. 넷째, 에이전트가 읽을 수 있는 짧은 통합 가이드를 제공하되 마법 같은 유틸리티보다 원시 계약을 우선한다.

Designing APIs for Agents는 특정 회사의 의견 글이지만, 시장 신호로 읽을 가치가 있다. API 소비자가 사람 개발자에서 사람과 에이전트의 조합으로 바뀌면 문서, 오류, SDK, 샌드박스, 권한 모델이 모두 제품 기능이 된다. ChatGPT Work 업무 앱 전쟁에서 보았듯 업무 앱은 에이전트가 직접 조작하는 표면이 되고 있다. API가 불명확하면 제품 전체가 에이전트에게 어려운 앱이 된다.

자주 묻는 질문

Q1: 에이전트용 API는 사람에게 불편해지나요?

A: 꼭 그렇지는 않다. 필드가 길어지고 명시적일 수는 있지만, 의미가 분명해지면 사람 리뷰와 디버깅에도 도움이 된다.

Q2: 기본값을 모두 없애야 하나요?

A: 아니다. 다만 중요한 동작을 숨기는 기본값은 줄여야 한다. 기본값이 있다면 문서와 응답에 명확히 드러내야 한다.

Q3: OpenAPI만 있으면 충분한가요?

A: 좋은 시작이지만 충분하지 않다. 실제 동작과 스키마가 일치해야 하고, 오류 메시지와 예제가 에이전트의 수정 루프를 도와야 한다.

Q4: SDK 투자는 줄여야 하나요?

A: 불투명한 편의 유틸리티는 줄이고, 인증, 타입, 스트리밍, 로깅처럼 계약을 안정화하는 기능에 집중하는 편이 좋다.

Q5: 한국 API 기업은 무엇부터 해야 하나요?

A: 상위 20개 오류와 상위 20개 필드명을 점검하는 것이 빠르다. 에이전트가 자주 틀리는 지점을 로그로 모아 문서와 스키마를 고쳐야 한다.