에이전트를 위한 API 설계는 왜 다른가
오늘날 API를 소비하는 주체의 상당수는 사람이 아니라 에이전트가 작성한 코드다. 2년 전만 해도 이 명제는 사실이 아니었지만, 지금은 API 설계 철학 자체를 뒤흔드는 현실이 됐다. 사람을 위한 좋은 API와 에이전트를 위한 좋은 API는 같지 않다. 이 차이를 이해하지 못하면, 우리가 지금까지 당연하게 여겼던 설계 원칙들이 오히려 독이 될 수 있다.
사람을 위한 API 설계의 핵심
사람을 위한 API를 설계할 때 핵심은 최소한의 코드로 동작하는 경험을 만드는 것이다. 50줄 안에 무언가 작동하는 결과를 보여줄 수 있어야 하고, 나머지 기능은 자연스럽게 탐색 가능해야 한다. 20개의 필드 중 하나만 필요한 사용자는 자동완성을 통해 나머지를 발견하면 충분하다.
Twilio와 Stripe의 SDK가 대표적인 예다.
# Twilio
client.messages.create(
body="Join Earth's mightiest heroes.",
from_="+15017122661",
to="+15558675310",
)
// Stripe
const paymentIntent = await stripe.paymentIntents.create({
amount: 1099,
currency: "usd",
automatic_payment_methods: { enabled: true },
});
이 두 API는 ACH가 무엇인지, Twilio의 봇 스케줄링이 어떻게 동작하는지 전혀 몰라도 즉시 사용할 수 있다. 문서를 거의 읽지 않아도 자기 설명적으로 동작한다는 점이 핵심이다. 짧은 이름, 편리한 유틸리티 함수, 스마트한 기본값이 이 경험을 만든다.
에이전트를 위한 API 설계는 무엇이 달라야 하는가
에이전트는 사람처럼 자동완성을 탐색하거나 문서를 직관적으로 훑지 않는다. 에이전트는 컨텍스트로부터 추론하고, 이름과 구조 자체에서 의미를 읽어낸다. 이 때문에 설계 철학이 반전된다.
- 긴 이름이 좋다: 사람에게는 장황하게 느껴지는
createPaymentIntentWithAutomaticMethodsEnabled가 에이전트에게는 명확한 시그널이다. - 유틸리티 함수는 오히려 해롭다: 편의를 위해 여러 동작을 묶은 헬퍼는 에이전트가 내부 동작을 오해할 가능성을 높인다.
- 암묵적 기본값보다 명시적 파라미터: 사람은 기본값 덕분에 코드가 줄어드는 것을 환영하지만, 에이전트는 명시적으로 기술된 파라미터에서 더 정확한 판단을 내린다.
- 패키지와 추상화에 회의적이어야 한다: 레이어가 많을수록 에이전트가 실제 동작을 추적하기 어렵다. 얇고 투명한 인터페이스가 에이전트 친화적이다.
백엔드 개발자 입장에서 이는 실질적인 설계 결정을 바꾼다. REST 엔드포인트 네이밍, 함수 분리 수준, SDK 제공 방식 모두가 영향을 받는다. "사람이 읽기 좋은가"라는 질문 옆에 "에이전트가 추론하기 좋은가"라는 질문을 반드시 병행해야 하는 시대가 됐다.
정리
- 에이전트는 자동완성·문서 탐색 대신 이름과 구조에서 의미를 추론하므로, 명시적이고 긴 네이밍이 유리하다.
- 편의를 위한 유틸리티 추상화는 에이전트의 오해를 유발할 수 있으며, 얇고 투명한 인터페이스가 에이전트 친화적이다.
- API 소비 주체가 사람에서 에이전트 중심으로 전환되고 있으므로, 설계 시 두 관점을 모두 고려하는 이중 검토가 필요하다.