에이전트를 위한 API 설계는 더 이상 RESTful 하지 않다

지난 30년 동안 API 설계는 단 한 명의 독자를 대상으로 하는 규율이었습니다. 워크스테이션에 앉아 문서를 읽고, 이미 알고 있는 엔드포인트(Endpoint)를 호출하는 코드를 작성하는 인간 개발자 말입니다. REST가 내린 모든 선택과 OpenAPI가 표준화한 모든 컨벤션(Convention)은 이 독자를 가정했습니다. 엔드포인트는 개발자가 그에 맞춰 코드를 작성해야 했기에 안정적이었습니다. 동사(Verb)는 일반적이었는데, 이는 개발자가 호출을 작성하는 과정에서 자신의 의도를 일반적인 어휘로 변환할 것이기 때문이었습니다. 계약(Contract)은 빌드 타임(Build time)에 고정되었는데, 이는 개발자의 의도를 빌드 타임에 파악할 수 있었기 때문입니다.

이제 독자가 바뀌었습니다.

이제 에이전트(Agent)가 대부분의 흥미로운 API 호출을 수행합니다. 에이전트는 런타임(Runtime)에 목표를 전달받고, 그 목표를 달성하기 위해 무엇이 필요한지 추론하며, 단 한 번의 단계로 자신의 의도와 일치하는 엔드포인트를 찾거나 제안해야 합니다. 에이전트는 문서를 읽지 않았습니다. 에이전트는 API 표면(API surface)에 대한 사전 지식이 없습니다. 에이전트는 자연어(Natural language)로 사용자의 목표를 추론하고, 그 추론을 서버에서 발견한 것과 대조합니다. 30년 동안의 API 설계에 녹아 있는 모든 가정은 이 독자에게는 적용되지 않는데, 왜냐하면 독자가 수행하는 작업이 다르기 때문입니다.

이 부분은 에이전트 인프라(Agent infrastructure) 논의에서 느리게 진행되어 온 부분인데, 그 함의가 불편하기 때문입니다. 이는 소프트웨어 공학에서 가장 세심하게 설계되어 온 시스템의 표면을 재사고해야 함을 의미합니다. Agentic APIs on AGTP는 누군가가 그 작업을 수행했을 때 재사고가 어떤 모습인지를 보여줍니다.

인간이 API로부터 필요로 했던 것

새로운 독자가 왜 설계를 변화시키는지 이해하려면, 기존의 독자에게 무엇이 제공되었는지를 솔직하게 살펴보아야 합니다.

REST는 인간 개발자에게 소수의 범용적인 동사 어휘(GET, POST, PUT, DELETE, PATCH)와 경로(path)가 리소스를 인코딩하고 동사가 작업을 인코딩한다는 강력한 관례를 제공했습니다. 이것이 작동했던 이유는 개발자가 스스로 번역 계층(translation layer)을 지니고 있었기 때문입니다. 개발자는 "테이블 예약하기"가 /reservations에 대한 POST를 의미한다는 것을 알고 있었습니다. 왜냐하면 예약 리소스를 생성하는 것이 "테이블 예약"을 개발자 모드로 인코딩한 것이기 때문입니다. HTTP 어휘는 서버의 데이터 모델(data model)에 매핑되었고, 개발자는 코드를 작성하는 순간 자신의 사용자 지향적 의도를 데이터 모델 어휘로 번역했습니다.

이러한 번역은 개발자에게 하나의 기능(feature)이었습니다. 왜냐하면 단 하나의 패턴(리소스에 대한 CRUD)만 배우면 어디에나 적용할 수 있었기 때문입니다. 이 번역이 작동했던 이유는 개발자가 그것에 대해 생각할 시간이 있었기 때문입니다. 개발자는 문서를 읽었습니다. 자신의 필요 사항을 엔드포인트(endpoints)와 대조했습니다. 주의를 기울여 호출을 작성했고, 만약 틀렸다면 응답을 디버깅하고, 코드를 수정하고, 다시 시도했습니다. 인간의 API 소비가 가진 비동기적이고 느린 루프(slow-loop) 특성이 바로 이 번역 계층을 비용이 들지 않게 만든 핵심이었습니다.

OpenAPI는 이러한 설계를 확장했습니다. YAML 파일에 고정된 계약(contracts). 이러한 고정된 계약으로부터의 SDK 생성. 개발자가 존재하는 엔드포인트를 호출하고 서버가 기대하는 형태의 파라미터(parameters)를 전달하고 있다는 컴파일 타임 보장(compile-time guarantees). 이 모든 요소는 인간 개발자에게는 아름답게 작동합니다. 하지만 에이전트 독자와 접촉하는 순간, 그 중 어느 것도 살아남지 못합니다.

에이전트에게 필요하지만 인간에게는 필요 없었던 것

에이전트와 API 간의 상호작용을 실제로 일어나는 일로 축소해 보면, 네 가지 속성이 타협 불가능한 요소가 됩니다.

에이전트는 API 표면(surface)에 대한 사전 지식이 없습니다. 에이전트는 아무런 정보 없이 서버에 도착합니다. 에이전트는 무언가를 시도하는 바로 그 호출 과정에서 서버가 무엇을 할 수 있는지 발견해야 합니다. 인간 개발자가 코드를 작성하기 전에 참고할 문서(documentation)는 에이전트가 결코 보지 못하는 문서입니다. 발견(discovery)은 반드시 프로토콜 상에서(on-protocol) 이루어져야 합니다.

에이전트는 자연어(natural language)로 사용자의 목표에 대해 추론합니다. 해당 추론을 엔드포인트(endpoint)로 매핑하는 과정은 단 한 번의 추론 단계(inference step)로 이루어집니다. 일반적인 CRUD 동사들은 에이전트가 인간 개발자가 사전에 수행했던 번역 과정을 강제로 수행하게 만드는데, 이 번역 단계야말로 에이전트가 오류를 범하는 지점이라는 실증적 증거가 이제 압도적으로 많습니다. 에이전트에게는 번역할 기회가 없기 때문에, API가 노출하는 어휘(vocabulary)는 에이전트가 추론하는 언어와 일치해야 합니다.

에이전트는 서버가 미처 예상하지 못한 기능(capabilities)을 필요로 할 수도 있습니다. 엔드포인트가 누락된 것을 발견한 인간 개발자는 기능 요청(feature request)을 작성하고 다음 릴리스를 기다립니다. 하지만 엔드포인트가 누락된 것을 발견한 에이전트는 지금 당장 눈앞에 사용자의 목표를 마주하고 있습니다. API 표면(API surface)은 에이전트가 필요한 것을 제안하고, 서버가 그 제안을 지원할 수 있는지 평가할 수 있게 해주는 런타임 협상 프리미티브(runtime negotiation primitive)를 수용해야 합니다.

에이전트는 API 작성자가 결코 만나본 적 없는 다른 에이전트들과 상호작용을 구성할 것입니다. 서로 다른 두 조직의 에이전트가 서로 협력하며 동일한 API를 사용할 것이고, 조직 간의 경계를 가로질러 구성되어야 하는 감사 추적(audit trails)이 존재할 것입니다. API 표면은 서버 간 추론(cross-server reasoning)을 위한 충분한 구조를 노출해야 하며, 이는 공유된 어휘, 예측 가능한 경로 문법(path grammar), 그리고 모든 엔드포인트에서의 식별 가능한 의미론적 블록(semantic blocks)을 의미합니다.

이 네 가지 속성이 결합되어 에이전트가 실제로 사용할 수 있는 API 표면을 설명합니다. OpenAPI 표면은 이 중 어느 것도 충족하지 못합니다. 에이전트 생태계는 프롬프트 엔지니어링(prompt engineering), 커스텀 래퍼(custom wrappers), 그리고 양자 통합(bilateral integration)을 통해 이 간극을 우회하며 작동해 왔습니다. Agentic API를 기반으로 하는 AGTP-API는 이 간극이 프로토콜 계층(protocol layer)에서 대신 메워져야 한다는 제안입니다.

프로토콜 바닥(The protocol floor)과 오픈 카탈로그

AGTP-API는 '왜(why)'라는 질문을 진지하게 받아들입니다. 이에 대한 답변에는 두 가지 계층이 있으며, 그 둘 사이의 구분이 중요합니다.

첫 번째 계층은 프로토콜 바닥(protocol floor)입니다. 규약을 준수하는 모든 AGTP 서버가 반드시 지원해야 하는 18개의 메서드(methods)로 구성됩니다. 7개의 인지 동사(cognitive verbs: QUERY, DISCOVER, DESCRIBE, INSPECT, SUMMARIZE, PLAN, PROPOSE), 6개의 메커니즘 동사(mechanics verbs: EXECUTE, DELEGATE, ESCALATE, CONFIRM, SUSPEND, NOTIFY), 그리고 5개의 라이프사이클 동사(lifecycle verbs: ACTIVATE, DEACTIVATE, REINSTATE, REVOKE, DEPRECATE)가 이에 해당합니다. 이 바닥은 모든 에이전트가 신뢰할 수 있고, 모든 서버가 준수해야 하며, 모든 게이트웨이가 라우팅할 수 있는 계약입니다. 이 바닥은 프로토콜이 확정 짓는 부분입니다.

두 번째 계층은 오픈 카탈로그(open catalog)입니다. 에이전트가 다양한 도메인에 걸쳐 실제로 사용하는 동작 어휘를 포괄하는 465개의 의도 정렬 동사(intent-aligned verbs)로 구성됩니다. BOOK(예약), RESERVE(확보), AUDIT(감사), REFUND(환불), ESCALATE(상신), SCHEDULE(일정 예약), NOTIFY(알림), DELEGATE(위임) 등이 그 예입니다. 이 카탈로그는 공개된 URL에 오픈 리빙 문서(open living document)로 큐레이션되며, 유의적 버전(semver)에 따라 버전이 관리되고 카테고리별로 인덱싱됩니다. 서버의 매니페스트(manifest)는 자신이 어떤 카탈로그 버전을 지원하는지 선언합니다. 서버에 대해 추론하는 에이전트는 자신이 마주치는 모든 동사를 동일한 공유 카탈로그에서 찾아보고 일관된 의미론(semantic)을 얻을 수 있습니다.

카탈로그는 의도적으로 바닥보다 더 넓게 설계되었습니다. 바닥은 서버 간 상호 운용성(interoperability)을 위해 존재합니다. 반면 카탈로그는 특정 도메인 내부에서의 표현력(expressiveness)을 위해 존재합니다. 예약 서버는 BOOK과 RESERVE를 사용합니다. 거래 서버는 BUY, SELL, TRANSFER를 사용합니다. 의료 기록 서버는 ADMIT, DISCHARGE, PRESCRIBE를 사용합니다. 카탈로그의 각 동사는 동일한 어휘 규칙과 큐레이션 원칙(명령형 동작-의도, 단일 의미론, HTTP 메서드 이름과 구별됨)을 충족하며, 각 동사는 다운스트림 시스템이 필터링, 탐색 및 분석에 사용할 수 있는 카테고리 메타데이터와 함께 등록됩니다.

동사 카탈로그는 설계 단계부터 오픈되어 있습니다

명시할 가치가 있는 참고 사항이 있습니다. AGTP-API 카탈로그에 동사를 추가하기 위한 IANA 레지스트리 경로는 존재하지 않으며, 이는 의도된 설계입니다.

IANA의 프로세스는 보수적으로 변경되어야 하는 사항들에 적합한 속도(cadence)를 가지고 있습니다. 상태 코드(Status codes), 미디어 타입(media types), 응답 헤더(response headers) 등이 이에 해당합니다. 이것들은 생태계의 모든 구성원이 합의해야 하는 인프라 수준의 문법(grammar)이며, IETF 프로세스의 느리고 신중한 속도가 바로 이들에게 안정성을 부여합니다. AGTP-API는 자신의 상태 코드, 미디어 타입, 응답 헤더를 위해 IANA 레지스트리를 요청하며, 해당 등록이 암시하는 속도를 존중합니다.

동사(Verbs)는 다릅니다. 에이전트 생태계가 필요로 하는 어휘는 에이전트 배포의 속도에 맞춰 성장하며, 이는 IETF 프로세스와는 다른 시간 규모를 가집니다. 에이전트를 실무에 투입하는 새로운 산업은 거의 즉각적으로 새로운 동사를 발견합니다. 의료 도메인은 PRESCRIBE(처방)와 TRIAGE(트리아지)를 원합니다. 물류 도메인은 DISPATCH(파견), ROUTE(경로 지정), CONSOLIDATE(통합)를 원합니다. 창의적 도메인은 SKETCH(스케치), ITERATE(반복), FINALIZE(완료)를 원합니다. 동사 어휘를 IETF 속도에 맞춰 고정하는 것은 레지스트리가 닫히는 순간 생태계를 동결시키는 것이며, 에이전트가 필요로 하는 것과 레지스트리가 허용하는 것 사이의 간극은 점점 커질 것입니다.

오픈 카탈로그(open catalog)는 큐레이션(curation)을 표준화 기구(standards body) 밖으로 옮김으로써 이 문제를 해결합니다. 이 카탈로그는 공개되며, 버전이 관리되고, 기계 판독이 가능하며(machine-readable), 개방적으로 유지 관리됩니다. 큐레이션 규율(명령형, 단일 의도, HTTP와 구별 가능성)은 관리자들에 의해 공개적으로 집행됩니다. 누구나 동사를 제안할 수 있습니다. 수용은 생태계가 실제로 움직이는 속도에 맞춰 이루어집니다. 프로토콜은 동사를 사용하는 계약을 규정하며, 카탈로그는 어떤 동사가 존재하는지를 규정합니다.

이것이 바로 에이전트 생태계에 결여되어 있었던 아키텍처적 구분입니다. 프로토콜 계층은 IETF의 규율이 필요합니다. 어휘 계층은 오픈 문서(open-document) 규율이 필요합니다. AGTP-API는 이 두 가지가 서로 다르다는 것을 인정하고 이를 다르게 취급하는 최초의 프로토콜 중 하나입니다.

실증적 사례

18개의 동사 하한선과 465개의 동사 카탈로그는 철학적 근거만으로도 옹호될 수 있습니다. 하지만 실증적 증거는 그보다 더 강력합니다.

7,200회의 실험을 통한 통제된 벤치마크와 4개의 모델 제품군을 대상으로, 의도에 부합하는 동사(intent-aligned verbs)를 사용하는 에이전트와 동일한 기본 기능에 대해 CRUD 동사를 사용하는 에이전트의 정확한 엔드포인트(endpoint) 선택 정확도를 측정했습니다. 프런티어(frontier) 규모에서의 격차는 상당했습니다. 모델에 따라 정확도에서 10~29%포인트의 차이가 발생했습니다. 연구에 포함된 세 가지 프런티어 모델을 통합했을 때, 평균 상승 폭은 18.5%포인트였으며, z-통계량(z-statistic)은 3.77, p-값(p-value)은 0.001 미만이었습니다. 서로 다른 조직이 서로 다른 아키텍처를 기반으로 구축한 세 개의 독립적인 모델 제품군 모두 유사한 규모로 동일한 방향성을 보였습니다.

이 메커니즘은 세 가지 절제 연구(ablations)를 통해 분리되었습니다. 의도에 부합하는 동사를 유지한 채 문서화(documentation)를 제거했을 때 정확도가 더욱 향상되었습니다(동사가 신호를 전달하고 있었으며, 문서는 노이즈를 추가하고 있었습니다). 두 패러다임 간의 설명을 서로 바꿨을 때, CRUD 정확도는 39~43%포인트 급락한 반면, 의도 부합형 정확도는 거의 변하지 않았습니다(동사는 나쁜 문서화 속에서도 살아남았지만, CRUD는 실패했습니다). 정답을 포함하도록 후보 집합을 제한했을 때도 격차는 그대로 유지되었습니다(문제는 엔드포인트 발견이 아니라 동사 선택에 있었습니다).

이 결과가 무엇을 의미하는지에 대한 한 단락 요약: 독자가 프런티어 규모의 언어 모델일 때, 메서드(method) 이름은 전체 엔드포인트 설명에서 가장 강력한 단일 신호입니다. 동사가 경로(path)를 이깁니다. 동사가 파라미터(parameters)를 이깁니다. 동사가 문서화(documentation)를 이깁니다. 18.5%포인트의 평균 상승 폭은 서버 앞에 붙는 동사 외에는 아무것도 바꾸지 않고 얻을 수 있는 결과입니다.

이것이 AGTP-API 설계의 경험적 사례입니다. 의도에 부합하는 동사(Intent-aligned verbs)는 에이전트가 추론하는 방식입니다. CRUD 동사는 인간이 자신의 추론을 서버의 데이터 모델로 번역하던 방식이었습니다. 독자가 에이전트일 때, 이를 수정하기 위한 두 번째 단계(second pass)는 존재하지 않으므로 번역 단계가 사라져야 합니다. 동사는 첫 시도에 바로 의도를 담아내야 합니다.

에이전트 간 상호작용(Agent-to-agent)은 다른 문제이다

기술적인 논의에서 과소평가되는 경향이 있는, 언급할 가치가 있는 또 다른 변화가 하나 더 있습니다.

지난 30년 동안의 API는 애플리케이션 간 통합(application-to-application integration)을 위해 설계되었습니다. 애플리케이션 A가 애플리케이션 B를 호출합니다. A와 B의 개발자들은 서로 만난 적이 없을 수도 있지만, 그들의 애플리케이션은 문서화되고, 버전이 관리되며, 고정된 안정적인 계약(contract)을 통해 만납니다. 양측 모두 이 계약에 맞춰 구축합니다. 상호작용은 설계 단계부터 양자 간(bilateral) 방식입니다.

에이전트는 다른 일을 하고 있습니다. 에이전트 A는 런타임(runtime)에 에이전트 B를 발견합니다. 에이전트 A와 에이전트 B는 조직적 경계도, 사전 소개도, 양자 간 합의도 공유하지 않을 수 있습니다. 그들의 상호작용은 사전에 조율하지 않고도 양측이 이해할 수 있는 기본 요소(primitives)로부터 즉석에서 구성(compose)되어야 합니다.