에이전트를 위한 API 설계: 기본값은 빼고 에러는 정확하게

Who Should Read

에이전트가 호출할 SDK나 내부 API를 설계하면서 사람용 편의 기능을 어디까지 둘지 고민하는 백엔드 개발자

Core Mechanics

• 사람용 API 설계와 정반대로 가야 한다
  • 사람용은 50줄 안에 동작하고 나머지 필드는 자동완성으로 알게 하는 방식이다.
  • 에이전트는 첫 프롬프트에서 문서 전체를 읽고 수천 줄 코드를 몇 초 만에 쓴다.
  • 그래서 코드를 읽으면 동작이 그대로 보이는 명확함이 최우선이다.
• 기본값은 나쁘다, 전부 채우게 하자
  • 에이전트는 문서를 읽고 적절한 시작값을 모든 필드에 직접 채울 수 있다.
  • 필드를 많이 채우는 비용은 사라졌고 코드가 뭘 하는지 이해하는 비용은 크게 올랐다.
  • 덜 중요한 필드는 주석으로 구분해 두면 된다.
• 에러는 나쁘지 않다, 정밀하면 된다
  • 대소문자 자동 변환이나 true·yes·on·1 같은 복수 표기 허용은 에이전트 코드베이스에서 오히려 해롭다.
  • 같은 값을 함수마다 다르게 쓰게 되어 나중에 리뷰어가 헷갈린다.
  • 원문 데이터에서는 에이전트가 겪는 마찰의 27%가 에러에서 나온다.
  • 에러 메시지에 문서를 읽으라고 적어 두면 좋다.
• name 같은 일반명 대신 구체적인 필드명을 쓰자
  • name을 10가지 용도로 쓰라고 하면 에이전트는 5가지 다른 방식으로 쓴다.
  • displayName, slug, externalId처럼 가정이 겹치지 않는 이름을 권한다.

Community Reactions

• 에러 메시지로 피드백을 받자는 의견
  • MCP에 feedback 툴을 두고 사용법이 헷갈릴 때마다 호출하라고 툴 설명에 적는 팁이 있다는 댓글이 있었다.
  • 구현이 매우 싸고 쓸 만한 신호를 얻을 것 같다는 의견이다.
• 기본값 제거는 사람 디버깅을 어렵게 한다는 반론
  • curl로 빠르게 호출해 디버깅하기 어려워진다는 의견이다.
  • HTTP/1처럼 필수 헤더 몇 개만으로 손으로 요청할 수 있는 구조가 낫다는 주장이다.
  • 모든 파라미터를 강제하면 CreateFile 같은 코드는 읽기 어렵다는 예시도 나왔다.
• 에이전트용 API 설계 팁 6가지를 공유한 경험
  • 텍스트 우선, grep 가능한 한 줄 출력, 5토큰 안팎의 짧은 ID에 cus_ 같은 접두사를 쓰라는 경험담이다.
  • 목록 응답에 맥락 정보를 넣고 벌크 작업을 지원하고 에러에 문서 링크와 힌트를 넣으라고 했다.
  • 이를 CRM 오픈소스 crmkit에 적용했다고 한다.
• 기본값을 설정 파일에 구체화하는 절충안
  • 확장이 제공하는 기본값을 시작 시 설정 파일에 그대로 써 넣는 방식을 쓴다는 경험이다.
  • 에이전트가 설정 전체를 한눈에 보고 새 설정도 자동으로 추가된다.
  • 대신 어떤 값이 기본값에서 바뀐 것인지는 알 수 없다는 단점이 있다.

How to Apply

• API 필드명 중 모호한 이름 찾아 바꾸기
  • 오늘 우리 API 스키마에서 name, id, type, value 같은 일반명 필드를 grep으로 뽑아라.
  • 용도별로 displayName, slug, externalId처럼 구체적인 이름으로 바꿀 후보 목록을 만들어라.
  • 필드마다 허용 문자와 범위를 doc comment로 적어라.
• 에러 응답에 원인과 문서 링크 넣기
  • 400대 에러에 어떤 값이 잘못됐고 무엇이 허용되는지 적어라.
  • 에러 본문에 해당 문서 URL과 올바른 예시를 넣어라.
  • 대소문자 자동 변환이나 복수 표기 허용 같은 조용한 보정은 에러로 바꿔라.
• 에이전트 대상 API에 feedback 툴 추가하기
  • MCP나 내부 툴에 feedback 툴을 하나 두어라.
  • 툴 설명에 사용법을 모르겠을 때 호출하라고 적어라.
  • 쌓인 로그로 에이전트가 자주 막히는 지점을 정리해 문서에 반영하라.
• 얇은 래퍼 SDK를 가이드로 대체해 보기
  • 에이전트가 쓰는 유틸 SDK 메서드 중 exec나 HTTP 호출 하나로 대체되는 것을 골라라.
  • 그 메서드를 지우고 사용 방법을 가이드 문서 한 편으로 옮겨라.
  • 에이전트에게 가이드를 읽히고 코드가 제대로 생성되는지 확인하라.

Try It

// Claude나 ChatGPT에 붙여넣는 프롬프트 (원문 원칙의 간이 버전: 에이전트용 API 감사)

아래는 우리 API 스키마(OpenAPI 또는 SDK 타입 정의)다.
{{API 스키마}}

이 API를 코딩 에이전트가 쓴다고 가정하고 다음 기준으로 감사해 줘.
1. name, id, type처럼 의미가 여러 가지로 읽힐 수 있는 필드를 찾고, 각각 구체적인 대체 이름을 제안해 줘.
2. 기본값에 의존하는 필드를 찾아, 명시적으로 채워야 할 값 목록을 만들어 줘.
3. 잘못된 입력을 조용히 보정하는 곳(대소문자 변환, 여러 표기 허용)을 찾고, 에러로 바꾸면 어떤 메시지가 좋을지 써 줘.
4. 에러 메시지 예시 5개를 쓰되 원인, 허용값, 문서 링크를 포함해 줘.

결과는 표로 정리해 줘.

이어서 해 볼 것: 고친 스키마를 에이전트에게 주고 같은 작업을 10번 시켜 필드를 같은 방식으로 쓰는지 비교해 보자.

Terminology

관련 논문

• 같은 시뮬레이션, 다른 근거: 도구 출력을 파일로 넘기면 LLM 에이전트 정확도가 어디서 깎이나

  긴 툴 출력을 파일로 넘기자 GPT-5.1은 정확도 11.3%p 하락, 정식 출력 지정하니 회복

• 가짜 뉴스가 진짜 폭락을: LLM 트레이딩 에이전트 대상 정보 주입 공격

  가짜 헤드라인 한 줄로 LLM 트레이딩 에이전트 62%를 조종했다(프롬프트 주입은 14%)

• Harness Engineering 101: LLM은 뇌, harness는 몸

  에이전트는 JSON 배열을 관리하는 루프이고, 16개 챕터로 직접 만들어 본다

• Harness²: 에이전트 harness를 스스로 고쳐 쓰는 재귀 최적화 프레임워크

  모델은 고정하고 harness를 재귀로 고쳤더니 벤치마크 점수가 최대 11.8%p 올랐다

• 해고된 Savannah 경찰관, ICE 요원 남편에게 Flock 계정 공유

  경찰관이 Flock 계정을 남편(ICE 요원)에게 공유했고, 감사에서 983건 검색이 드러나 해고됐다

• tmux와 Claude Code: 세션, send-keys, 그리고 한계선

  tmux로 Claude Code 여러 개를 돌리면 편하지만 에이전트 4개쯤에서 한계가 온다

• Hybrid Reasoning Agents: 잠재 공간에서 생각하고 텍스트로 행동하는 LLM 에이전트

  잠재 공간 추론과 텍스트 도구 호출을 섞었더니 성능 10.4%↑, 토큰 최대 54.7%↓

Related Resources

• https://www.freestyle.sh/blog/opinion/designing-apis-for-agents
• https://github.com/crmkit/crmkit
• https://slinkydeveloper.com/blog/designing-apis-for-vibe-cod...
• https://agentauthprotocol.com
• https://workos.com/auth-md