Harness Engineering 101, 파이썬 300줄로 배우는 AI 에이전트 구현

핵심 아이디어

출발점은 LLM이 두뇌라면 하네스는 몸이라는 비유다. LLM API는 상태가 없어서 매 턴 전체 대화를 JSON 배열로 보내고 텍스트를 돌려받는다. 하네스는 이 배열을 만들고 유지하고 보호하는 프로그램이다. 우리가 흔히 에이전트라고 부르는 기능은 모두 이 기본 반복문에 덧붙인 수정이고, 각 수정은 구체적인 실패를 해결하려고 추가됐다고 책은 설명한다. 그래서 모든 장이 실패 상황, 최소한의 수정, 그 수정에 따르는 비용의 순서로 구성돼 있다. 캐싱과 컨텍스트 관리, 하위 에이전트가 왜 필요한지를 실제로 생기는 문제와 연결해 보여 준다.

구성

1부는 통신과 기본 루프다. JSON 배열 통신, 다음 토큰을 만드는 모델, 도구 호출, 에이전트 루프, 캐싱 순서를 다룬다. 2부는 오래 실행할 때의 컨텍스트와 시간 관리로, 컨텍스트를 가방이 아니라 예산으로 보는 관점, 하위 에이전트로 컨텍스트 분기하기, 실행 중인 루프 조정, 백그라운드 작업을 다룬다. 3부는 프레임워크와 확장 기능, 디버깅이다. 모든 프레임워크가 결국 1장의 통신 구조를 감싼 래퍼라는 점, MCP와 스킬, 지연 로딩, 훅, 그리고 볼 수 없는 프롬프트는 고칠 수 없으므로 배열을 직접 들여다봐야 한다는 점을 설명한다. 4부는 가드레일과 코딩 에이전트 사례 연구, RAG가 처음부터 하네스 패턴이었다는 해석, 그리고 주석을 붙인 완성형 하네스를 직접 만드는 마지막 장이다. 부록은 모델 라우팅과 비용 엔지니어링, 병렬 에이전트를 위한 작업 환경 격리, 계획 모드, 재시도와 스트리밍을 다룬다.

이용 조건

단계별 실습 코드와 주석이 달린 완성형 하네스가 제공된다. 파이썬 3.10 이상에서 외부 패키지 없이 실행되며 기본 예제에는 Anthropic API 키가 필요하다. 본문은 CC BY-NC-ND 4.0으로 출처를 밝히면 공유할 수 있지만 상업적 이용과 수정본 배포는 안 되고, 코드는 MIT 라이선스로 자유롭게 쓸 수 있다. 저자는 각 장을 직접 썼고 Claude Code와 자신이 만든 오픈소스 코딩 에이전트로 구성 순서를 다듬고 도표와 차트 코드를 만들었다고 밝혔다.