LLM AI Agent

Article Review - LangChain: Building a Custom Agent Harness

ybjeon.today 2026. 6. 20. 20:55

Link: https://www.langchain.com/blog/how-to-build-a-custom-agent-harness

Date: 2026-06-03

 

Key Takeaways

  • Harness는 모델을 실제 세계와 연결하는 scaffolding(비계, 자동으로 생성되는 기본 코드 구조나 뼈대)이다.
  • Harness가 주어진 task에 얼마나 잘 맞느냐가 agent의 유용성을 결정한다.
  • LangChain의 create_agent는 특정 task에 맞춘 custom harness를 가장 쉽게 구축하는 방법이다.

 

Core Concepts

유용한 agent 구축의 핵심은 커스터마이징 — 특정 task에 맞는 context, 데이터, 환경을 연결하는 것이다.

Agent의 기본 구조는 "model + harness"다. Harness는 모델을 실제 애플리케이션과 연결하는 scaffolding을 제공한다.

 

 

Core Principle

두 가지 핵심 전제:

  • Agent의 품질은 모델에 제공되는 context에 달려 있다.
  • Harness의 목적은 각 단계에서 적절한 context를 전달하는 것이다.

 

The Base Harness

create_agent는 LangChain의 harness 구축을 위한 기본 도구다:

from langchain.agents import create_agent

agent = create_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=tools,
    system_prompt="you are a helpful assistant..."
)

이 framework은 "의도적으로 미니멀리스트"한 접근 방식을 취하며, middleware를 커스터마이징의 기본 단위로 제공한다.

 

Middleware: Customization Mechanism

Middleware는 agent loop의 여러 지점에서 개입한다:

  • 모델 호출 전후
  • tool 호출 전후
  • 시작 및 종료 시

각 middleware 컴포넌트는 고유한 관심사를 처리하며 다른 컴포넌트와 조합된다.

 

Middleware Capabilities

  • Deterministic Logic: 비즈니스 규칙, 정책 집행, 런타임 agent 제어 — 프롬프트 처리보다 특정 loop 실행 지점이 필요한 항목
  • Tools: tool의 전체 생명주기 관리 (설정, 종료, 등록). 의존성이나 초기화가 필요한 tool에 특히 유용하다
  • Custom State: Middleware가 agent 상태를 확장해 hook 간 데이터 추적 및 공유를 가능하게 한다
  • Stream Handlers: 출력 스트림을 가로채고 변환 — 이벤트 필터링, 메타데이터 주입, 이벤트 타입을 다른 consumer로 라우팅

 

Harness Capabilities Matrix

Capability Purpose Middleware
Prevent context overflow 장기 세션에서 메시지 기록 관리 SummarizationMiddleware, ContextEditingMiddleware
Access and update memory 반복적 개선을 위한 지식 로드/저장 FilesystemMiddleware, MemoryMiddleware, SkillsMiddleware
Take environment actions 파일/실행 접근으로 솔루션 범위 확장 ShellToolMiddleware, FilesystemMiddleware, CodeInterpreterMiddleware
Delegate tasks 깔끔한 context로 복잡한 subtask 관리 SubAgentMiddleware, AsyncSubAgentMiddleware, TodoListMiddleware
Handle transient failures 재시도 로직과 fallback 제공 ToolRetryMiddleware, ModelRetryMiddleware, ModelFallbackMiddleware
Enforce policies PII, 컴플라이언스, 승인 요건 관리 PIIMiddleware, HumanInTheLoopMiddleware
Steer the agent 중요한 작업에 대한 사람의 승인 활성화 HumanInTheLoopMiddleware
Control costs 토큰 지출 감소 및 비용 초과 방지 ModelCallLimitMiddleware, ToolCallLimitMiddleware, PromptCachingMiddleware

 

Task-Harness Fit

"Task-harness fit"은 harness 설계와 실제 task 요구사항 — 필요한 context, 예상 실패, 필수 정책, 운영 환경 — 간의 정합성을 나타낸다.

LangChain의 내부 agent (GTM agent, 비동기 코딩 agent, no-code agent builder)는 모두 커스터마이징된 middleware 스택으로 create_agent를 사용한다.

 

Key Insight

"최고의 agent는 단순히 강력한 모델로만 만들어지지 않는다. task에 긴밀히 맞는 harness와 함께 만들어진다." 최적의 agent 설계는 harness 아키텍처를 mission 요건에 정확히 맞추는 것을 요구한다.