AHOP: Agent × Human Onboarding Protocol을 제안하며
어느 날 깨달은 게 하나 있었습니다.
저는 AI 에이전트를 위한 메모리 인프라를 만들고 있습니다. MaaS, Memory-as-a-Service라는 제품입니다. API를 연동하려면 당연히 문서가 필요합니다. Quick Start, API Reference, Integration Guide도 정성 들여 만들었습니다. 사람이 읽고 따라 할 수 있도록 말입니다.
그런데 문득 의문이 들었습니다. 이 문서를 누가 읽는 걸까요?
현실을 직시하다
요즘 개발자의 워크플로우를 보면 패턴이 명확합니다.
- 서비스에 가입하고 결제합니다.
- API 키를 받습니다.
- Claude Code나 Cursor, Copilot에게 "이거 연동해"라고 말합니다.
끝입니다. 사람이 문서를 직접 읽는 단계가 사라졌습니다. Quick Start는 에이전트가 읽고, API Reference도 에이전트가 참조하고, 에러 메시지도 에이전트가 해석합니다.
문서의 실질적 소비자가 사람에서 에이전트로 이동한 것입니다. 그런데 문서는 여전히 사람이 읽는 것을 전제로 만들어져 있습니다. HTML 페이지에 네비게이션 바, 사이드바, 마케팅 문구, JavaScript 렌더링이 덕지덕지 붙어 있습니다. 에이전트에게는 전부 노이즈입니다.
이 문제를 인식한 사람들이 있었습니다. Jeremy Howard가 제안한 llms.txt가 대표적입니다. 웹사이트 루트에 마크다운 파일을 두고, 이 서비스가 무엇인지, 중요한 문서가 어디 있는지를 에이전트가 읽기 좋은 형태로 정리해 두는 방식입니다. robots.txt가 크롤러를 위한 안내문이라면, llms.txt는 LLM을 위한 안내문입니다.
좋습니다. 그런데 여기서 한 발 더 나가니 빈 구멍이 보였습니다.
빈 레이어를 발견하다
지금 에이전트 인프라의 표준 스택을 보면 이런 구조입니다.
- llms.txt: 이 서비스가 뭐야? Discovery
- OpenAPI: 엔드포인트 스키마가 뭐야? Schema
- MCP: 도구를 실행해. Tool Execution
- AMCP: 세션 간 기억을 유지해. Memory
- A2A: 다른 에이전트와 협력해. Collaboration
전부 잘 정의되어 있습니다. 그런데 딱 하나가 빠져 있습니다.
사람이 결제하고 API 키를 받은 그 순간, 이 키와 이 컨텍스트를 에이전트에게 넘기는 핸드오프 과정이 표준화되어 있지 않습니다.
llms.txt는 서비스가 무엇인지 알려줍니다. 하지만 credential을 받은 뒤 에이전트가 던지는 첫 질문, "지금 뭘 해야 하지?"에는 답하지 못합니다. 어떤 엔드포인트를 먼저 호출해야 하는지, 앵커를 어떤 전략으로 만들어야 하는지, 에러가 나면 무엇을 의미하는지. 이건 llms.txt의 영역이 아닙니다. OpenAPI의 영역도 아닙니다. OpenAPI는 이 엔드포인트의 파라미터가 무엇인지 정의하지, 이 서비스를 처음 연동할 때 어떤 순서로 무엇을 하는 게 올바른 패턴인지 알려주지는 않습니다.
그래서 지금 일어나는 일은 단순합니다. 사람이 에이전트에게 API 키만 던져주면, 에이전트는 문서를 전부 읽거나 추측해야 합니다. 추측이 맞으면 운이 좋은 것이고, 틀리면 사람이 다시 개입해야 합니다. 핸드오프의 의미가 사라집니다.
onboard.txt라는 답
우리가 내놓는 답은 간단합니다.
AHOP, Agent × Human Onboarding Protocol은 사람이 SaaS를 결제하고 credential을 받은 뒤, 에이전트에게 통합 작업을 넘기는 핸드오프를 표준화하는 프로토콜입니다. 표준 파일명은 onboard.txt입니다.
한 줄로 포지셔닝하면 이렇습니다.
llms.txt는 에이전트에게 서비스가 무엇인지 알려줍니다. onboard.txt는 에이전트에게 어떻게 시작하는지 알려줍니다.
실제로는 이렇게 생겼습니다.
Integrate MaaS memory into a character chat application.
Docs: https://maas.nunchiai.com/llms.txt
Full docs: https://maas.nunchiai.com/llms-full.txt
Guide: https://maas.nunchiai.com/docs/guides/character-chat.md
API key: mk_maas_4f7c1d2a9b8e...
Base URL: https://maas.nunchiai.com/v1
Workspace ID: acme-studio-prod
Service source: enterprise-tutor
Integration pattern:
- Create one anchor per user-character pair: POST /v1/anchors
- Before each response: POST /v1/memory/recall
- After each response: POST /v1/atoms to store meaningful memory
- Only store meaningful memory — not trivial chatter
- Send feedback via POST /v1/feedback when recalled memory influenced the answer
Common errors:
- 400 Bad Request → invalid or missing API key
- 402 Payment Required → billing issue
- 403 Forbidden → access policy denied
- 404 Not Found → anchor does not exist; create it first
- 429 Too Many Requests → rate limited; back off and retry사람은 결제 완료 페이지에서 이걸 복사합니다. 에이전트에게 붙여넣습니다. 에이전트는 바로 구현을 시작합니다.
왜 JSON이 아니라 텍스트인가
이 질문은 반드시 나옵니다. 표준이라면서 왜 JSON이나 YAML이 아니냐는 질문입니다.
답은 간단합니다. 이 파일의 소비자가 JSON 파서가 아니라 LLM이기 때문입니다.
전통적인 표준이 JSON을 쓰는 이유는 프로그램이 파싱해서 구조화된 데이터로 쓰기 위해서입니다. robots.txt는 크롤러가 파싱하고, openapi.json은 SDK가 파싱하고, package.json은 npm이 파싱합니다. 소비자가 deterministic한 코드이므로 구조화된 포맷이 맞습니다.
그런데 onboard.txt의 소비자는 LLM입니다. LLM은 JSON을 파싱하는 게 아니라 읽습니다. 그리고 LLM에게 지시를 내릴 때 JSON보다 자연어 프롬프트를 더 안정적으로 따릅니다.
예를 들어 onboard.txt를 JSON으로 쓴다면 이렇게 됩니다.
{
"directive": "Integrate MaaS memory into a character chat application",
"api_key": "mk_maas_4f7c...",
"integration_pattern": ["Create one anchor per user-character pair"]
}이건 에이전트에게 데이터를 준 것이지 지시를 준 것이 아닙니다. 에이전트는 이 JSON을 어떻게 처리해야 하지부터 생각해야 합니다. 반면 plain text 프롬프트는 그 자체가 지시문이어서 바로 행동으로 옮길 수 있습니다.
실용적인 이유도 있습니다. 사람이 이 파일을 복사해서 Claude Code에 붙여넣습니다. JSON을 붙여넣으면 모호함이 생기고, plain text를 붙여넣으면 자연스럽게 프롬프트로 받아들입니다. 마찰이 사실상 0입니다.
소비자가 파서면 JSON이고, 소비자가 LLM이면 자연어입니다. 이게 설계 원칙입니다.
MaaS에서 먼저 만들었다
스펙만 써놓고 누군가 구현하겠지라고 하면 아무 일도 일어나지 않습니다. 그래서 저희 제품에서 먼저 구현했습니다.
Nunchi AI의 MaaS는 AHOP의 첫 번째 프로덕션 구현입니다. Stripe 결제가 끝나면 success 페이지에서 서비스 소스에 따라 동적으로 onboard.txt를 생성하고, 클립보드 복사 버튼과 함께 제공합니다. 사람이 할 일은 Copy 버튼을 누르고 에이전트에게 붙여넣는 것뿐입니다.
문서도 이중 레이어로 재편했습니다.
- Human view: 스타일이 적용된 HTML, 내비게이션, 문법 강조, 다국어 지원
- Agent view: 같은 경로에서
.md확장자로 제공되는 순수 마크다운 /llms.txt: 에이전트 디스커버리용 사이트 인덱스/llms-full.txt: 전체 문서를 한 파일로 합친 버전
하나의 소스에서 두 소비자를 동시에 만족시키는 구조입니다.
프로토콜 스택이 완성된다
AHOP은 단독으로 존재하지 않습니다. 에이전트 인프라 표준 스택의 빈칸을 채우는 역할입니다.
| 레이어 | 표준 | 역할 |
|---|---|---|
| Discovery | llms.txt | 이 서비스가 뭐야? |
| Onboarding | AHOP / onboard.txt | 어떻게 시작해? |
| Schema | OpenAPI | 엔드포인트 스키마 |
| Tools | MCP | 도구 실행 |
| Memory | AMCP | 세션 간 기억 유지 |
| Collaboration | A2A | 에이전트 간 협업 |
저희는 이미 AMCP, Agent Memory Continuity Protocol을 Apache 2.0으로 공개했고 Nexus와 MaaS를 레퍼런스 구현으로 제공하고 있습니다. AHOP도 같은 전략입니다. 스펙은 무료로 공개하고, 가장 좋은 구현은 우리 제품에서 돌아가게 만드는 방식입니다. OAuth 스펙은 무료이고 Auth0가 유료인 것과 같은 구도입니다.
다른 서비스도 쓸 수 있다
이건 MaaS 전용이 아닙니다. 어떤 SaaS든 onboard.txt를 제공할 수 있습니다.
결제 서비스라면 고객 생성, 결제 수단 등록, 구독 생성, 웹훅 설정 순서를 integration pattern에 넣으면 됩니다. 분석 플랫폼이라면 초기화, 이벤트 트래킹, 유저 식별, 대시보드 쿼리 순서를 넣으면 됩니다.
포맷은 같습니다. 도입 지시문, credential, 문서 링크, 통합 패턴, 에러 가이드입니다. GitHub 레포에는 빈 템플릿도 제공하고 있으니, 자기 서비스에 맞게 채우면 됩니다.
다음 단계
AHOP 스펙 v0.1.0과 MaaS 레퍼런스 구현, 가상 예시, 채택용 템플릿을 Apache 2.0으로 공개했습니다.
GitHub: github.com/goldberg-aria/ahop
지금 저희는 MaaS 사이트를 에이전트 퍼스트 구조로 다시 만들고 있습니다. llms.txt, llms-full.txt, 이중 레이어 문서, 그리고 AHOP 기반 success 페이지까지 포함한 구조입니다. 이 과정에서 스펙은 더 다듬어질 것입니다.
앞으로는 에이전트가 OAuth 승인 뒤 API를 통해 직접 onboard.txt를 요청하는 흐름도 가능해질 것입니다. 그러면 사람이 복사해서 붙여넣는 단계도 사라집니다. credential이 유효한지 먼저 검증하는 verification endpoint나, Claude Code와 Cursor 같은 IDE가 onboard.txt를 1급 입력으로 받는 방향도 열려 있습니다.
생각해보면 이건 자연스러운 흐름입니다. 웹사이트는 모바일에 적응했고, 소셜 공유에 적응했고, 음성 검색에 적응했습니다. 이제 AI 에이전트에 적응할 차례입니다. 그리고 그 적응의 출발점은 단순한 질문 하나입니다. 누가 당신의 문서를 읽고 있는가입니다.
그 답은 이미 바뀌었습니다. 온보딩도 바뀌어야 합니다.
피드백과 질문, 기여는 GitHub에서 받습니다.
Nunchi AI: nunchiai.com MaaS: maas.nunchiai.com AHOP: github.com/goldberg-aria/ahop AMCP: github.com/goldberg-aria/amcp