실제 AI 에이전트로 설치 가이드를 테스트하며 발견한 3가지 버그

오늘 무언가를 배포했다: 오픈소스 AI 메모리 레이어를 위한 '원 프롬프트 설치' 흐름이다. 아이디어는 최근 Karpathy가 언급한 것과 같다. 인간이 아닌 에이전트를 위해 작성된 문서 말이다. 사용자가 Claude Desktop / Cursor / Codex에 프롬프트 하나를 붙여넣으면, 에이전트가 일반 텍스트 가이드를 가져와서 나머지를 수행한다(pip install, 회원가입, MCP 설정 편집, 왕복 검증).

몇 시간 동안 합성 테스트 환경에서 테스트했다. Doctor는 통과했고, 모든 CI는 녹색이었다. 배포해도 안전하다고 느꼈다.

그런 다음 내 컴퓨터에서 실제 Claude Desktop의 실제 에이전트가 가이드를 실행하게 했다. 6시간 동안 3번의 릴리즈를 거쳤다. 실제 LLM이 구동될 때만 드러난 문제들은 다음과 같다:

1. pip install <pkg>를 하면 사용자가 바로 설치해서 쓸 수 있을 것이라고 가정하고 가이드를 작성했다. 하지만 python.org의 기본 파이썬에서는 그렇지 않다. 파이썬의 기본 urllib은 CA 번들 없이는 TLS 검증을 거부한다. pip install은 필수 의존성만 가져오고 선택적 의존성은 가져오지 않는다. certifi를 필수 의존성으로 만들어야 했다. 릴리즈 한 번이 소요되었다.

2. 내 MCP 서버는 내가 이전 개발 작업에서 mcp 패키지를 설치해 두었기 때문에 작동했던 것이다. 이 패키지는 mengram-ai[mcp]와 같이 선택적 추가 요소로 나열되어 있었다. 일반적인 pip install만으로는 서버를 시작할 수 없었다. Claude Desktop이 연결을 시도하면 "프로세스가 즉시 종료됨"이라는 오류가 떴다. mcp도 필수 의존성으로 만들었다. 또 다른 릴리즈가 필요했다.

3. 세 번째 시도: Claude Desktop에 도구가 나타났고, 에이전트가 30개의 도구를 모두 발견했다. 하지만 모든 도구 호출이 SSL: CERTIFICATE_VERIFY_FAILED로 실패했다. 내 CLI의 HTTP 도우미들은 certifi를 올바르게 사용하고 있었지만, 내 SDK의 HTTP 도우미(실제로 MCP 서버가 호출하는 것)는 그렇지 않았다. 두 개의 별도 코드 경로가 있었고, 하나만 패치되었다. 세 번째 릴리즈였다.

합성 테스트는 매번 통과했다. 내 설치 가이드의 "검증" 단계도 매번 통과했다. 이것들을 찾아낸 유일한 방법은 내 개발 환경이 섞이지 않은, 실제 호스트의 실제 머신에서 실제 에이전트를 돌리는 것뿐이었다.

더 큰 교훈: 에이전트가 따라 할 설치 지침을 작성하는 사람들에게 말한다. 당신의 의존성 그래프는 에이전트와의 계약이다. 선택적 추가 요소(pkg[xyz])나 "아, 그냥 이거 수동으로 한 번 실행하세요" 같은 단계는 에이전트 실행에서 살아남지 못한다. 에이전트는 당신을 위해 Install Certificates.command를 실행하지 않는다. 그것이 필요한 단계 이전에 평문으로 정확히 명시하지 않는 한, 선택적 추가 요소를 설치해야 한다는 것을 기억하지 못한다.

또한, 호스트가 크게 실패할 것과 동일한 지점에서 크게 실패하도록 "Doctor"를 작성하라. 내 Doctor는 API 왕복만 테스트했지 import mcp는 테스트하지 않았다. 거기에 사전 검사를 추가하자, 다음 설치에서는 사용자가 Claude Desktop을 열었을 때가 아니라 검증 단계에서 문제를 잡아낼 수 있었다.

혹시 에이전트 네이티브 설치 패러다임을 구축하고 있는 다른 사람 있나? 어떤 점이 당신을 당황하게 했는가?