AI 에이전트에게 파일을 저장하는 툴을 주려 했습니다. S3, R2, Dropbox… 모두 써봤지만 에이전트는 브라우저로 로그인하거나 신용카드를 입력할 수 없었습니다. 기존 서비스가 모두 인간을 위해 설계된 도구였기 때문입니다.

이 경험을 한 사람은 PromptHub 운영자이자 개발자인 Danny Richman입니다. 그는 이 문제를 해결하기 위해 AI 에이전트 전용 파일 호스팅 서비스 Agentstorage를 직접 만들었고, 그 과정에서 얻은 인사이트를 공유했습니다. 핵심 메시지는 단순합니다. 현존하는 소프트웨어의 99%는 인간을 위해 설계됐고, 에이전트는 완전히 다른 방식으로 도구를 사용한다는 것입니다.

출처: What I learned from building a product for agents – PromptHub Substack

인간용 UX와 에이전트용 UX는 다릅니다

인간은 대시보드, 온보딩 플로우, 예쁜 UI, 알림을 원합니다. 에이전트가 원하는 건 다릅니다. API, 문서, 속도, 그리고 실행입니다.

이 차이는 생각보다 훨씬 깊습니다. 개발자가 Cloudflare R2를 에이전트 관점에서 벤치마킹한 결과를 보면 분명해집니다.

개발자가 R2 첫 사용까지 직접 걸린 시간은 약 30분이었습니다. CLI 설치, 브라우저 OAuth 로그인, 버킷 생성 시도, 활성화 게이트 차단, 대시보드로 이동해 R2 활성화, 결제 수단 등록, 버킷 재생성, 브라우저 동의 승인… 총 10단계, 브라우저 조작 여러 번, 신용카드 필요. 에이전트에게 신용카드를 쥐여줘도 Cloudflare 대시보드를 탐색하는 건 사실상 불가능합니다.

Agentstorage에서 같은 작업은 두 단계입니다. 에이전트에게 사용 방법이 담긴 파일을 전달하고, 파일 링크를 돌려받는 것. 끝입니다.

에이전트 친화적 설계의 핵심 조건

개발자가 직접 경험하며 정리한 에이전트용 제품의 필수 조건은 세 가지입니다.

문서가 단일 URL에 구조화되어야 합니다. 에이전트는 여러 페이지에 흩어진 문서를 탐색하지 못합니다. 모든 정보가 하나의 마크다운 파일(Skills.md)에 담겨 있어야 합니다. 흩어진 문서는 에이전트에게 마찰입니다.

API만으로 온보딩이 완결되어야 합니다. 에이전트는 계정 생성, 워크스페이스 설정, API 키 발급, 서비스 사용까지 인간의 개입 없이 처리할 수 있어야 합니다. 대시보드가 필요한 순간, 에이전트는 멈춥니다.

에이전트는 API를 인간과 전혀 다른 방식으로 씁니다. 하나의 워크플로우에서 수백 개의 요청을 순식간에 쏘고, 실패하면 자동으로 재시도합니다. AI 개발 환경 서비스 E2B는 샌드박스 시작 시간을 400ms에서 80ms까지 줄였는데, 인간에겐 체감하기 어려운 차이지만 수백 개 샌드박스를 연속으로 돌리는 에이전트에겐 누적 효과가 큽니다. 에러 메시지도 마찬가지입니다. 에이전트는 “요청이 잘못됐습니다. 다시 시도해주세요” 같은 산문형 안내를 해석하지 못합니다. 에러 코드와 원인이 구조화된 형태로 반환되어야 에이전트가 다음 동작을 스스로 결정할 수 있습니다.

에이전트를 테스터로 쓰는 개발 루프

에이전트를 주 사용자로 삼으면 예상치 못한 이점도 생깁니다. 에이전트가 사용자라면 에이전트를 테스터로도 쓸 수 있습니다. 문서를 업데이트하고 에이전트에게 다시 실행시켜보면서 어디서 막히는지 바로 확인하는 방식입니다. 인간 사용자에게 피드백을 요청하거나 기다릴 필요가 없습니다. 개발-테스트 사이클이 훨씬 빠르게 돌아갑니다.

대형 서비스들도 결국 CLI를 추가하고 문서를 재구조화하고 API를 에이전트 친화적으로 바꿀 것입니다. 하지만 에이전트를 나중에 지원하는 제품과, 처음부터 에이전트를 주 사용자로 설계한 제품이 만들어내는 경험의 차이는 클 수밖에 없습니다. 원문에는 클레임 링크 온보딩, 스코프 API 키, 웹훅 우선 통합 등 Agentstorage의 구체적인 설계 패턴이 상세히 담겨 있습니다.