How to Build a Custom Agent Harness

🖼️ 인포그래픽

How to Build a Custom Agent Harness 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

💡 한 줄 요약

유용한 에이전트를 만들려면 모델 자체보다도 작업에 맞는 맥락, 도구, 상태, 정책을 적시에 제공하는 맞춤형 하네스가 중요하며, LangChain의 create_agent는 이를 미들웨어로 세밀하게 구성하는 최소 기반을 제공한다.

📌 핵심 요약

글은 에이전트를 “모델이 도구를 반복 호출해 작업을 끝내고 결과를 반환하는 구조”로 설명하며, 이를 더 간단히 “agent = model + harness”라고 정의한다.
하네스는 모델을 현실의 맥락, 데이터, 환경에 연결하는 비계이며, 에이전트의 유용성은 하네스가 특정 작업에 얼마나 잘 맞는지에 크게 좌우된다.
LangChain의 create_agent는 모델, 도구, 시스템 프롬프트만으로 작동하는 기본 에이전트를 만들 수 있게 하되, 의도적으로 최소화된 구조를 유지해 세밀한 커스터마이징을 가능하게 한다.
커스터마이징의 핵심 수단은 미들웨어이며, 미들웨어는 모델 호출 전후, 도구 호출 전후, 시작과 종료 시점에 개입해 비즈니스 로직, 도구 생명주기, 상태, 스트림 처리 등을 담당한다.
프로덕션 에이전트에는 컨텍스트 넘침 방지, 메모리 접근과 갱신, 실행 환경에서의 행동, 하위 작업 위임, 실패 복구, 정책 집행, 인간 승인, 비용 제어 같은 여러 하네스 기능이 조합되어야 한다.

🧩 주요 포인트

글은 에이전트를 “모델이 도구를 반복 호출해 작업을 끝내고 결과를 반환하는 구조”로 설명하며, 이를 더 간단히 “agent = model + harness”라고 정의한다.
하네스는 모델을 현실의 맥락, 데이터, 환경에 연결하는 비계이며, 에이전트의 유용성은 하네스가 특정 작업에 얼마나 잘 맞는지에 크게 좌우된다.
LangChain의 create_agent는 모델, 도구, 시스템 프롬프트만으로 작동하는 기본 에이전트를 만들 수 있게 하되, 의도적으로 최소화된 구조를 유지해 세밀한 커스터마이징을 가능하게 한다.
커스터마이징의 핵심 수단은 미들웨어이며, 미들웨어는 모델 호출 전후, 도구 호출 전후, 시작과 종료 시점에 개입해 비즈니스 로직, 도구 생명주기, 상태, 스트림 처리 등을 담당한다.
프로덕션 에이전트에는 컨텍스트 넘침 방지, 메모리 접근과 갱신, 실행 환경에서의 행동, 하위 작업 위임, 실패 복구, 정책 집행, 인간 승인, 비용 제어 같은 여러 하네스 기능이 조합되어야 한다.

🧠 상세 정리

1. 에이전트의 핵심은 모델과 하네스의 결합

글은 유용한 에이전트를 만드는 일이 결국 커스터마이징의 문제라고 설명한다. 에이전트는 기본적으로 모델이 도구를 호출하는 과정을 반복하면서 작업을 완료하고 결과를 반환하는 구조다. 이를 더 압축하면 에이전트는 모델과 하네스의 합으로 볼 수 있다. 여기서 하네스는 모델을 실제 세계의 맥락, 데이터, 환경과 연결하는 비계 역할을 한다. 따라서 모델의 성능만이 아니라, 모델이 매 단계에서 어떤 정보를 받고 어떤 환경에 연결되는지가 에이전트의 실질적 유용성을 결정한다.

2. 좋은 하네스의 기준은 올바른 맥락 제공

본문은 에이전트가 제공받는 맥락만큼만 좋아질 수 있다는 전제를 둔다. 하네스의 임무는 작업 수행의 각 단계에서 모델에게 필요한 맥락을 제공하는 것이다. 이는 단순히 긴 프롬프트를 넣는다는 뜻이 아니라, 작업에 맞는 데이터, 도구, 정책, 상태, 실행 환경을 적절한 시점에 연결한다는 의미다. 같은 모델을 사용하더라도 하네스가 작업에 잘 맞지 않으면 에이전트는 제한적으로 작동할 수밖에 없다. 반대로 하네스가 특정 작업에 맞게 설계되면 모델은 훨씬 더 실용적인 방식으로 행동할 수 있다.

3. create_agent는 최소한의 기본 하네스를 제공

LangChain의 create_agent는 하네스를 만들기 위한 기본 구성 요소로 제시된다. 모델, 도구, 시스템 프롬프트를 전달하면 바로 작동하는 에이전트를 만들 수 있다는 점이 핵심이다. 글은 Deep Agents나 Claude Agent SDK처럼 메모리, 컨텍스트 관리, 샌드박싱 등을 미리 갖춘 하네스도 언급하지만, 그런 방식은 대부분의 경우 빠르게 프로덕션 준비에 접근하게 해주는 대신 세밀한 변경에는 한계가 있을 수 있다고 본다. create_agent는 반대로 의도적으로 미니멀하게 설계되어 핵심 에이전트 루프만 구현한다. 그 대신 미들웨어를 커스터마이징의 기본 단위로 노출해 사용자가 필요한 동작을 직접 쌓을 수 있게 한다.

4. 미들웨어는 에이전트 루프의 각 지점에 개입한다

미들웨어는 에이전트의 실행 루프 안에서 모델 호출 전후, 도구 호출 전후, 시작과 종료 단계에 연결된다. 각각의 미들웨어는 하나의 관심사를 처리하고, 다른 미들웨어와 자유롭게 조합될 수 있다. 이 구조 덕분에 특정 비즈니스 규칙, 정책 집행, 동적 제어처럼 프롬프트에 넣기 어렵거나 넣어서는 안 되는 로직을 명확한 실행 지점에 배치할 수 있다. 예를 들어 작업 복잡도에 따라 모델을 바꾸거나, 프롬프트를 조정하거나, 메시지 기록을 압축 과정에서 갱신하는 일이 가능하다. 즉 미들웨어는 에이전트의 행동을 외부에서 안정적으로 조율하는 확장 지점이다.

5. 도구, 상태, 스트림도 미들웨어로 관리한다

본문은 미들웨어가 단순한 전후처리 장치가 아니라 도구의 전체 생명주기까지 관리할 수 있다고 설명한다. 도구를 에이전트에 직접 등록하는 대신, 미들웨어가 초기화, 정리, 등록 과정을 담당하고 에이전트에는 정돈된 도구 집합을 넘길 수 있다. 이는 도구가 의존성을 갖거나 실행 전 준비와 종료 후 정리가 필요한 경우 특히 중요하다. 또한 미들웨어는 커스텀 상태를 확장해 실행 중 카운터, 플래그, 지속 값 등을 유지하고 여러 훅 사이에서 데이터를 공유할 수 있다. 출력 스트림을 가로채 이벤트를 필터링하거나 메타데이터를 주입하고, UI·감사 로그·모니터링 시스템에 서로 다른 이벤트를 전달하는 역할도 수행할 수 있다.

6. 프로덕션 하네스에는 여러 기능이 함께 필요하다

글의 후반부는 하네스가 실제 운영 환경에서 담당해야 하는 대표 기능들을 정리한다. 긴 세션은 메시지 기록이 빠르게 쌓여 컨텍스트 창을 넘칠 수 있으므로 요약이나 컨텍스트 편집이 필요하다. 실행 시작 시 관련 지식을 불러오고 종료 시 다시 기록하는 메모리 기능은 에이전트가 실제 사용 경험을 통해 개선되도록 돕는다. 고정된 도구만으로는 한계가 있기 때문에 파일시스템, 셸, 코드 실행 환경에 접근하면 더 창의적이고 효율적인 해결이 가능해진다. 복잡한 하위 작업은 서브에이전트와 할 일 목록으로 위임하고 추적할 수 있으며, 모델과 도구의 일시적 실패에는 재시도, 백오프, 대체 모델 같은 복구 로직이 필요하다. 또한 개인정보 처리, 컴플라이언스, 승인 절차, 호출 제한, 프롬프트 캐싱 같은 정책과 비용 제어도 프롬프트가 아니라 하네스 차원에서 안정적으로 강제되어야 한다.

🧾 핵심 주장 / 시사점

이 글의 핵심 관점은 에이전트 개발의 차별점이 모델 선택보다 하네스 설계에 있다는 점이다. 같은 모델이라도 어떤 맥락을 언제 제공하고, 어떤 도구와 정책을 어떻게 연결하느냐에 따라 실제 업무 능력이 달라진다.
미들웨어 방식은 프롬프트에 모든 지시를 밀어 넣는 접근의 한계를 보완한다. 반드시 실행되어야 하는 정책, 비용 제한, 승인 절차, 실패 복구 같은 요소는 모델의 자율 판단에 맡기기보다 루프의 특정 지점에서 결정적으로 작동하도록 설계하는 것이 더 적합하다.
create_agent가 미니멀한 기본 루프를 제공한다는 점은 장점과 책임을 동시에 의미한다. 빠른 시작은 가능하지만, 프로덕션 수준의 에이전트를 만들려면 컨텍스트 관리, 메모리, 도구 생명주기, 관측, 비용 통제 같은 요소를 작업 목적에 맞게 조합해야 한다.

✅ 액션 아이템

에이전트 개발을 시작할 때 모델 선택보다 먼저 컨텍스트 관리, 도구 생명주기, 메모리, 관측, 비용 통제 같은 하네스 요구사항을 목록화한다.
정책 집행, 승인 절차, 재시도, 모델 라우팅처럼 반드시 실행되어야 하는 로직은 프롬프트가 아니라 미들웨어 훅으로 분리한다.
create_agent 같은 최소 루프를 사용할 경우, 프로덕션 전 긴 세션 요약, 상태 공유, 스트림 필터링, 오류 복구를 별도 미들웨어로 보강한다.