에이전트 하네스
AI로 번역함. 영어 원문을 사람이 검증함. 우리가 책을 만드는 방식
영어판 2026.11.2판을 번역한 것이다. 원문 읽기
모델을 중심으로 코드를 구성해, 실제 도구를 맡겨도 신뢰할 수 있는 에이전트를 만든다. 작은 Python 라이브러리의 유지보수 에이전트를 예로 들어 루프, 도구, 컨텍스트, 권한, 샌드박싱, 서브에이전트, 테스트를 다룬다.
대상 독자 모델의 API를 호출해 보았고 데모 에이전트를 만들어 본 엔지니어를 위한 책이다. 이제 사람이 모든 단계를 지켜보지 않아도 실제 도구에서 작동하는 에이전트를 만들어야 하는 독자를 대상으로 한다. Python으로 코드를 작성할 수 있고 JSON과 HTTP를 알고 있어야 한다. 모델 내부 구조나 MCP에 대한 배경지식은 필요하지 않다.
Kindle 또는 모든 전자책 리더기에서 읽는다
EPUB은 Apple Books, Kobo 및 대부분의 전자책 단말기에서도 사용할 수 있다.
Kindle로 보내기
이 판의 EPUB을 보냅니다 한국어.
-
우리 주소 승인하기
아마존은 승인된 주소에서 보낸 파일만 킨들로 전달한다. 파일을 이메일로 보내는 서비스마다 한 번씩 승인해야 한다. 우리 주소를 승인된 개인 문서 이메일 목록에 추가한다.
books@rollingedition.comAmazon 개인 문서 설정 열기. Amazon에서는 콘텐츠 및 기기 관리, 환경설정, 개인 문서 설정에 있다.
보냈다. 몇 분 안에 Kindle 서재에 나타난다.
도서가 도착하지 않으면 대부분 1단계의 승인 문제이다. books@rollingedition.com가 승인된 개인 문서 이메일 목록에 있는지 확인한다.
저장한 책의 새 판은 Kindle로도 전송된다.
Kindle 주소가 아니다. 주소는 @kindle.com으로 끝나며, Amazon의 개인 문서 설정에서 찾을 수 있다.
오늘 {count}권의 책을 보냈으며, 이는 한 계정이 하루에 받을 수 있는 최대치입니다. 내일 다시 시도하세요.
오늘 보낼 수 있는 도서는 모두 보냈다. 내일 다시 시도하라.
책을 보내지 못했다. 몇 분 후 다시 시도한다.
이 판은 용량이 커서 이메일로 보낼 수 없다.
Kindle로 보내기는 Labs와 함께 제공된다.
Kindle 주소가 아니다. 주소는 @kindle.com으로 끝나며, Amazon의 개인 문서 설정에서 찾을 수 있다.
책을 보내지 못했다. 몇 분 후 다시 시도한다.
또는 EPUB을 내려받아 Amazon의 Send to Kindle 페이지에 끌어다 놓는다.
Kindle is a trademark of Amazon.com, Inc.
목차
12장, 읽는 데 약 5시간 44분, 64개 예제 포함.
-
1모델에 도구와 루프 제공하기
이 장을 마치면 모델에 세 가지 도구를 주고 루프 안에서 실행할 수 있다. 하나는 파일을 읽고, 하나는 테스트를 실행하며, 하나는 변경한 파일로 작업을 끝낸다. 루프는 모델이 작업을 끝낼 때, 단계를 모두 소진했을 때, 모델이 호출을 멈출 때 중단된다. 먼저 과제를 해결하는 스크립트 모델로 루프를 실행하고, 이어서 과제를 해결하지 못하는 녹화된 오픈 모델로 실행하여 그 모델이 어디에서 잘못되는지 확인한다.
-
2작업이 끝났거나 막혔을 때 루프를 멈춘다
이 장을 마치면 하네스가 실행마다 기록하는 단어 하나만으로 그 실행이 멈춘 이유를 말할 수 있고, 진전이 멈춘 실행을 끝내는 규칙 두 가지를 추가할 수 있다.
-
3모델이 오용할 수 없는 도구를 제공하라
이 장을 마치면 도구가 실행되기 전에 하네스가 인자를 검사하는 도구를 모델에 제공할 수 있고, 모델이 따라 행동할 수 있는 거부 메시지를 작성할 수 있다.
-
4One interface for scripted, replayed, local and hosted models
By the end of this chapter you can run the same loop on a scripted model, a replayed run, a local model and an OpenAI-compatible endpoint, without changing the loop.
-
5작업이 늘어나도 컨텍스트를 쓸모 있게 유지하기
이 장을 마치면 실행 한 번의 프롬프트에 남은 공간이 얼마인지 계산하고, 하네스가 프롬프트의 크기를 정확히 셀 수 없을 때 그 크기를 추정하며, 도구 호출과 그 결과를 떼어 내지 않고 실행의 오래된 단계를 압축할 수 있다.
-
6변경을 일으키는 도구에 관문 두기
이 장을 마치면 에이전트의 변경을 사람이 승인할 때까지 에이전트 자신의 사본에만 두는 방법, 그 승인이 사람이 읽은 바로 그 변경을 대상으로 하는지 확인하는 방법, 거부를 에이전트의 실행이 멈춘 이유로 되돌려 주는 방법을 익힌다.
-
7에이전트의 코드를 샌드박스에서 실행하고 비밀 값을 에이전트의 눈에서 숨기기
이 장을 마치면 에이전트를 위해 명령을 실행하되 시간 제한, 프로세스별 메모리·CPU·파일 크기 상한, 허용 목록으로 구성한 환경, 그리고 작업 폴더로 쓰는 임시 복사본을 적용할 수 있다. 또한 컨테이너나 가상 머신이 이 가운데 어떤 제한을 추가하는지, 이 샌드박스가 어떤 제한을 열어 두는지도 설명할 수 있다.
-
8하위 작업은 자식에게 넘기고, 중단은 되돌려 받는다
이 장을 마치면 자식 루프에 고유한 단계 예산을 주어 하위 작업을 맡기고, 자식의 전체 대화 기록 대신 요약과 중단 사유를 돌려받을 수 있다. 또한 중단이 사람에게 닿도록 만든다. 중단 규칙이 막힌 것으로 끝낸 실행은 부모에게 넘어가고, 부모는 그 중단의 질문을 이슈를 등록한 유지보수자에게 전한다.
-
9하니스를 MCP 서버에 연결하기
이 장을 마치면 다른 사람들이 운영하는 MCP 서버에 하니스를 연결하고, 각 서버의 도구를 하니스 자체 도구와 충돌할 수 없는 이름으로 확인하며, 그 도구에 대한 모든 호출을 승인 게이트로 보낼 수 있다. 6장에서 그 게이트를 만들었고, MCP 도구도 게이트의 승인을 거치게 된다고 말했다. 이 장에서는 그 말이 실제로 성립하게 만들고, 프로토콜이 클라이언트에 맡겨 둔 부분, 즉 하니스가 서버의 도구에 덧붙이는 것이 무엇인지 보여 준다.
-
10에이전트를 테스트하고 작업 세트로 측정한다
이 장을 마치면 스크립트로 작성한 응답으로 하니스를 테스트하고, 완료의 기준을 하나로 정해 작업 세트에서 에이전트의 점수를 매기고, 그 개수를 범위와 함께 제시할 수 있다. 하니스는 일반적인 코드이므로 다른 코드와 똑같이 테스트할 수 있다. 에이전트는 더 어렵다. 에이전트의 동작은 모델에 달려 있고, 모델의 응답은 모델, 설정, 각 프롬프트의 표현에 따라 달라진다. 따라서 오늘 통과한 테스트는 특정한 응답 순서 하나에서 일어난 일만 보여 준다. 이 장은 이 세 단계를 차례로 다룬다. 먼저 미리 고정해 둔 응답 순서로 하니스를 테스트한다. 다음으로 1장에서 소개한, 에이전트가 유지보수하도록 요청받는 라이브러리
unitcraft의 유지보수 작업 20개로 에이전트의 점수를 매긴다. 마지막으로 그 점수를 얼마나 신뢰할 수 있는지 설명한다. -
11각 실행을 추적하고 그 비용을 세기
이 장을 마치면 모든 실행이 단계마다 레코드 하나를 나중에 읽는 사람이 파싱할 수 있는 파일에 쓰도록 만들 수 있다. 각 레코드에 그 실행과 해당 호출을 연결하는 ID를 부여할 수 있으며, 실행에 든 비용을 토큰 수로 말할 수 있다. 여기서 비용은 개수를 뜻한다. 금액을 뜻하지 않는다.
-
12에이전트가 잘못된 설계일 때
이 장을 마치면 사례에 나오는 어떤 작업이든 고정 파이프라인, 단일 모델 호출, 게이트를 갖춘 에이전트 중 하나로 분류하고, 기록된 실행이 그 작업에 대해 무엇을 보여 주는지 말할 수 있다. 첫 번째 시험 사례는 작업 T-02이다.