GraphQL은 AI 에이전트가 기다려 온 언어다

GraphQL은 프런트엔드 개발을 빠르게 하려고 2015년에 설계되었다. 그런데 그것이 똑똑한 질문을 하는 기계를 위한 완벽한 인터페이스로 드러났다.

앞선 글에서의 주장은, AI 에이전트가 소프트웨어의 주된 소비자가 되고 있으므로 모든 애플리케이션이 API-first여야 한다는 것이었다. API가 제품이다. UI는 하나의 클라이언트다.

그 주장은 거의 아무도 아직 묻지 않지만 모두가 물어야 하는 후속 질문을 남긴다. 어떤 종류의 API를 만들어야 하는가?

에이전트가 소프트웨어를 어떻게 쓰려 하는지 실제로 지켜보면, 답은 한 방향을 강하게 가리킨다. GraphQL이다. 그것이 유행이기 때문이 아니다 — 이 시점에 벌써 10년 된 기술이다. GraphQL을 REST와 다르게 만드는 구체적인 속성들이, 에이전트가 사람 없이 작동하기 위해 필요한 것과 거의 완벽하게 정렬되기 때문이다.

페이스북이 2015년에 실수로 에이전트 시대의 쿼리 언어를 만들었고, 업계는 그 뒤 10년을 주로 React 앱을 약간 더 편하게 만드는 데 썼다는 느낌이다. 그것은 GraphQL을 과소평가하는 것이다. 극적으로.

발견 문제

API가 기계가 아니라 사람을 위해 만들어졌음을 보여 주는 가장 분명한 신호가 있다. 문서 페이지다. 명사로 나열된 엔드포인트. 자신이 무엇을 찾는지 이미 아는 사람을 위해 쓰인 예제. 지난 조직 개편 이후 아무도 갱신하지 않은 버전 이력. 개발자가 도착하면 그는 문서를 읽고, 리소스 그래프의 심상 모델을 머릿속에 담고, 필요한 데이터를 얻기 위해 구체적이고 미리 계획된 호출 순서를 만드는 코드를 쓴다. 문서는 일회성 온보딩 비용이다.

에이전트는 그렇게 작동하지 않는다. 에이전트는 목표를 갖고 당신의 API에 도착한다 — 엔지니어링 팀에 배정된, 우선순위가 가장 높은 열린 티켓 세 개를 찾아 최근 활동을 요약하라 — 그리고 그 목표를 작업들로 어떻게 분해할지 동적으로 알아내야 한다. 미리 만들어진 통합은 없다. 문서를 읽어 줄 시니어 엔지니어도 없다. 에이전트는 당신의 API를 처음 만난 자리에서 실시간으로 추론하고 있다.

이것을 발견 문제라고 부르자. 에이전트는 무엇이 있는지 모르는 상태로 당신의 애플리케이션에 도착하고, 그 무지의 비용은 그것이 실행하려는 모든 워크플로에서 지불된다. REST에서 에이전트는 어떤 엔드포인트가 존재하는지 추측하고, 호출을 하고, 데이터 형태를 이해하려고 응답을 살펴보고, 다른 곳에서 관련 데이터가 필요함을 깨닫고, 또 호출을 하고, 결과를 맞춰 보고, 페이지네이션을 처리하고, 반복해야 한다 — 그 전부를 필요하지도 않은 데이터에 컨텍스트 창을 태우면서.

GraphQL은 발견 문제를 접어 버린다. 에이전트는 단 한 번의 인트로스펙션 쿼리를 실행해 전체 스키마를 돌려받을 수 있다. 모든 타입, 모든 필드, 모든 관계, 모든 인자, 모든 설명. 그 스키마는 현실과 어긋날 수 있는 별도의 산출물이 아니다. 그것이 바로 현실이다. 쿼리를 해석하는 그 코드에서 생성된다.

에이전트에게 이것은 지도 없이 도시를 다니는 것과 GPS를 갖고 시작하는 것의 차이다.

인트로스펙션이 곧 자기 문서화

모든 GraphQL API는 자기 문서화된다. 누군가 OpenAPI 명세를 최신으로 유지하는 것을 기억할 때 REST API도 「자기 문서화」된다고 말하는 그 느슨하고 희망적인 의미가 아니다. GraphQL API는 프로토콜의 핵심 기능으로서, 설계상, 문자 그대로 자기 문서화된다.

이것이 에이전트에게는 구체적인 방식으로 중요하다. 단 한 번의 데이터 요청을 하기 전에, 에이전트는 API에게 물어볼 수 있다. 당신은 무엇을 할 수 있는가? 어떤 데이터를 갖고 있는가? 그것들은 어떻게 연결되는가? 그리고 API는 답한다 — 완전하게, 정확하게, 파싱하기가 사소한 형식으로.

최근 청구에 관한 고객 불만을 찾으라는 요청을 받은 에이전트를 상상해 보라. 그것은 스키마를 인트로스펙션해서 tickets 필드를 가진 Customer 타입이 있고, 티켓에는 BILLING을 포함하는 category 열거형이 있고, 티켓에는 createdAt 타임스탬프와 status 필드가 있고, 각 티켓에 comments 연결이 있음을 발견한다. 몇 초 안에 데이터 모델의 완전한 지도를 갖게 된다 — 최신일 수도 아닐 수도 있는 문서에서가 아니라, 살아 있는 시스템 자체에서.

이것이 Model Context Protocol — AI 어시스턴트가 외부 도구를 발견하고 호출하게 하는 Anthropic의 표준 — 이 본질적으로 모든 종류의 API에 나중에 얹으려 하는 그 속성이다. GraphQL 스키마는 이미 MCP 모양의 매니페스트다. 둘이 같은 언어를 말할 때 프로토콜과 데이터 모델은 중간에서 만난다.

정확히 필요한 것만 요청하기

REST API는 고정된 데이터 구조를 돌려준다. /api/users/123을 호출하면 서버가 사용자 응답에 넣기로 결정한 모든 것을 돌려받는다. 이름, 이메일, 주소, 설정, 아바타 URL, 계정 생성일, 마지막 로그인 타임스탬프, 구독 등급, 그 외 마흔 개의 필드. 그 사용자의 최근 주문도 필요하다면 그것은 별도의 호출이다. 그 주문 안의 상품이 필요하다면 그것은 주문마다 또 한 번의 호출이다.

모든 API 소비자가 과다 조회를 처리하고 왕복을 조율하는 맞춤 코드를 쓸 수 있는 프런트엔드 엔지니어였을 때는 이것이 합리적이었다. 소비자가 실제 제약 아래 작동하는 에이전트일 때는 깊이 비효율적이다.

에이전트에게는 컨텍스트 창이 있다. 응답 안의 불필요한 데이터의 모든 토큰은 추론이나 계획, 혹은 다른 관련 맥락을 담는 데 쓰였을 수 있는 토큰이다. REST API가 4KB의 사용자 데이터를 돌려주는데 에이전트가 필요했던 것은 이름과 이메일뿐이라면, 그것은 단순히 낭비된 대역폭이 아니다. 낭비된 인지 용량이다. 그것을 다단계 워크플로의 모든 호출로 곱하면 에이전트의 컨텍스트는 잡음으로 채워진다.

GraphQL은 그 문제를 없앤다. 에이전트가 필요한 정확한 필드를 명시한다.

query {
  user(id: "123") {
    name
    email
    recentOrders(first: 3) {
      status
      total
      items {
        productName
        quantity
      }
    }
  }
}

요청 한 번. 정확히 필요한 데이터. 과다 조회 없음. 과소 조회 없음. 낭비된 토큰 없음. 에이전트는 자신의 정보 필요에 정확히 대응하는 응답을 돌려받는다. 이것은 최적화가 아니다 — 소비자가 형태를 서술하고 서버가 그것을 어떻게 조립할지 알아내는, 근본적으로 다른 데이터 획득 모델이다.

그것이 지능적인 에이전트가 데이터 소스와 상호작용하는 데 쓸 수 있어야 하는 모델이다. 그리고 그것이 GraphQL이 10년 동안 조용히 돌려 온 모델이다.

열두 번 대신 한 번의 요청

REST에서 과소 조회 문제는 과다 조회 문제보다 더 고통스럽고, GraphQL의 우위가 가장 잘 보이는 지점이다.

주간 팀 상태 리포트를 생성하도록 지시받은 에이전트를 상상해 보라. 팀 구성원, 각자에게 배정된 작업, 그 작업의 상태와 우선순위, 이번 주에 갱신된 작업의 댓글, 그리고 그 작업들이 속한 프로젝트가 필요하다. 일반적인 REST API에서 이것은 폭포다. 팀 명단을 가져오고, 각 구성원에 대해 그의 작업을 가져오고, 각 작업에 대해 댓글과 프로젝트를 가져온다. 수십 번의 요청, 각각이 앞의 것에 의존한다. 에이전트는 그 전부를 조율하고, 모든 엔드포인트에서 페이지네이션을 처리하고, 요청 제한에 대응하고, 서로 다른 응답 형태의 데이터를 꿰매야 한다. 개념적으로는 질문 하나인 것을 위한 많은 순차 로직이다.

GraphQL에서는 그것이 쿼리 하나다. 왕복 한 번. 모든 데이터가 제대로 중첩되어, 에이전트가 요청한 정확한 형태로. 에이전트는 조율 패턴을 이해할 필요도, 중간 상태를 관리할 필요도, 엔드포인트들이 어떻게 연쇄되는지에 대한 심상 모델을 유지할 필요도 없다. 없어진 모든 왕복은 제거된 실패 양상이고, 절약된 지연 비용이며, 에이전트가 결코 쓰지 않아도 되는 조율 코드 한 조각이다.

불필요한 복잡도를 최소화하려는 추론 엔진에게 이것은 엄청난 우위다.

검증이 내장된 뮤테이션

GraphQL의 우위는 데이터 읽기에 국한되지 않는다. 에이전트가 무언가를 해야 할 때 — 레코드를 만들고, 상태를 갱신하고, 워크플로를 촉발할 때 — GraphQL 뮤테이션은 구조화되고 예측 가능하며 스스로 검증하는 인터페이스를 제공한다.

에이전트가 REST API를 통해 지원 티켓을 만들 때, 그것은 JSON 본문이 있는 POST 요청을 구성해야 하지만 그 본문의 정확한 형태 — 어떤 필드가 필수인지, 어떤 것이 선택인지, 어떤 타입을 기대하는지, 어떤 값이 유효한지 — 는 외부 문서에만 정의되어 있다. 틀리면 에이전트는 실행 시점에, 도움이 될 수도 안 될 수도 있는 오류 응답을 통해 알게 된다.

GraphQL 뮤테이션에는 타입이 지정된 입력 객체가 있다. 스키마가 모든 인자와 그 타입, 필수 여부, 설명을 명시적으로 선언한다. 에이전트는 호출하기 전에 뮤테이션을 인트로스펙션해, 확신을 갖고 유효한 페이로드를 구성하고, 필요한 확인 데이터를 정확히 요청해 돌려받을 수 있다. 추측 없음. 시행착오 없음. 희망으로 꿰맨 불안정한 통합 없음.

기계가 애플리케이션과 상호작용할 수 있어야 하는 방식이 이것이다.

스키마가 곧 계약

GraphQL 스키마는 실질적으로 기계가 읽을 수 있는 역량 매니페스트다. 그것은 선언한다. 이 애플리케이션이 할 수 있는 모든 것이 여기 있고, 관련된 데이터 타입이 여기 있고, 그것들이 어떻게 서로 관계 맺는지가 여기 있고, 사용 가능한 작업이 여기 있다. 그것은 당신의 애플리케이션과 그것을 쓰려는 모든 지능 시스템 사이의 계약이다.

에이전트가 GraphQL API를 만나면 맞춤 통합이 필요하지 않다. 누군가 손으로 어댑터를 쓸 필요가 없다. 스키마를 읽고 일을 시작한다. 스키마가 곧 통합 계층이다.

이것이 Archie Core가 그 중심으로 설계된 속성이다. Archie Core 위에 만들어진 모든 애플리케이션 — 프런트엔드든 백엔드든 둘 다든 — 은 GraphQL 스키마를 무료로 얻는다. 사후 고려로서가 아니고, 옆에 붙은 부속물로서가 아니라, 주된 인터페이스로서. 함의는 미묘하지 않다. Archie 위에서 배포되는 모든 애플리케이션은 첫날부터 에이전트 대응이다. 에이전트가 이미 그 언어를 말하기 때문이다.

에이전트가 사용자를 대신해 어떤 도구를 호출할지 점점 더 많이 결정하는 경제에서, 「함께 일하기 쉬움」은 기술적 세부사항이 아니다. 그것은 시장 진입 전략이다.

정직한 트레이드오프

GraphQL에는 실제 비용이 있고, 없는 척하는 것은 게으른 일이다. GraphQL 서버를 만드는 것은 REST 엔드포인트를 세우는 것보다 손이 더 간다. 순진한 구현은 과도한 데이터베이스 쿼리를 만들어 낼 수 있고 — N+1 문제 — 이를 완화하려면 DataLoader 패턴과 쿼리 계획이 필요하다. 캐싱은 REST의 URL 기반 리소스보다 어렵다. CDN 계층 캐싱에 의존하는 대신 지속 쿼리 같은 애플리케이션 수준 전략이 필요하다. 그리고 애플리케이션이 관계가 거의 없는 평평한 리소스 모델을 갖고 있다면, 에이전트에게도 REST가 충분히 적절할 수 있다.

이것들은 알려진 해법이 있는 엔지니어링 과제이며, 근본적 한계가 아니다. 문제는 그 비용이 에이전트 시대의 이익에 견줄 만한지이고, 그 미래를 진지하게 받아들이는 애플리케이션에게 답은 점점 더 「그렇다」다.

기계가 함께 생각할 수 있는 API를 만들라

API-first에 대한 주장은, 에이전트가 주된 소비자가 되고 있으므로 애플리케이션이 프로그래밍 인터페이스를 통해 완전히 접근 가능해야 한다는 것이다. GraphQL에 대한 주장은 그것의 자연스러운 연장이다. API는 지능적인 기계가 최소한의 마찰로 발견하고 이해하고 사용할 수 있는 방식으로 설계되어야 한다.

GraphQL은 살아 있는 역량 매니페스트 역할을 하는 자기 서술적 스키마를 준다. 에이전트의 컨텍스트 한계를 존중하는 정밀한 데이터 획득을 준다. 추측을 없애는 타입 지정 뮤테이션을 준다. 능동적 행동을 가능하게 하는 실시간 구독을 준다. 그리고 그 전부를 단일 엔드포인트와 통합된 쿼리 언어를 통해 준다.

REST는 개발자가 한 번에 하나의 엔드포인트씩 손으로 통합을 쓰던 세계를 위해 만들어졌다. 그 세계는 여전히 존재하고, REST는 여전히 그것을 잘 섬긴다. 하지만 부상하는 세계 — 에이전트가 애플리케이션 역량을 동적으로 발견하고 즉석에서 구성하는 세계 — 는 더 표현력 있고 더 구조화되고 더 인트로스펙션 가능한 무언가를 요구한다.

GraphQL은 더 이상 그저 개발자의 편의가 아니다. 그것은 지능적인 에이전트가 함께 추론할 수 있는 인터페이스 언어다. 그리고 그것을 말하는 애플리케이션이 그들이 먼저 손을 뻗는 애플리케이션이 될 것이다.

더 읽을 거리

이 아래 아키텍처에 대한 근거는 UI는 거짓이다에, 그것의 상업적 버전은 API-first의 비즈니스 근거에 있다.

자주 묻는 질문

AI 에이전트에게 GraphQL이 REST보다 나은 이유는? GraphQL은 인트로스펙션을 통해 자기 문서화되고, 에이전트가 필요한 필드를 한 번의 왕복으로 정확히 요청하게 하며, 뮤테이션에 타입 지정 입력을 강제한다. REST는 에이전트가 엔드포인트 형태를 추측하고, 관련 데이터를 위해 여러 호출을 조율하고, 필수 필드를 시행착오로 발견하도록 요구한다.

발견 문제란 무엇인가? 발견 문제는 AI 에이전트가 어떤 데이터와 작업이 가능한지 모르는 상태로 애플리케이션에 도착할 때 지불하는 비용이다. REST API는 에이전트가 추측하도록 강제한다. GraphQL API는 전체 스키마를 돌려주는 한 번의 인트로스펙션 쿼리로 답한다.

GraphQL은 Model Context Protocol(MCP)과 어떤 관계인가? MCP는 AI 어시스턴트가 외부 도구를 발견하고 호출하게 하는 Anthropic의 표준이다. GraphQL 스키마는 이미 MCP 모양이다 — MCP가 노출하도록 설계된 그 기계 판독 가능 역량 매니페스트를 제공한다. GraphQL 애플리케이션은 에이전트 생태계와 중간에서 만난다.

GraphQL에 실제 비용과 복잡도가 없는 것은 아니지 않나? 있다. GraphQL 서버는 REST 엔드포인트보다 만들기 복잡하다. 캐싱이 더 어렵다. 순진한 구현에는 N+1 쿼리 문제가 있다. 이것들은 알려진 해법이 있는 엔지니어링 과제다 — DataLoader, 지속 쿼리, 스키마 계획 — 근본적 한계가 아니다.

Archie Core는 왜 GraphQL을 주된 API로 선택했나? Archie Core는 그 위에 만들어진 모든 애플리케이션이 GraphQL 스키마를 무료로 얻도록 설계되었고, 그것이 애플리케이션을 첫날부터 AI 에이전트가 발견하고 조작할 수 있게 만든다. 에이전트 대응은 나중에 추가된 기능이 아니라 아키텍처의 속성이다.