핵심 요약 (Key Takeaways)

• 하네스(Harness)는 모델을 실제 세상과 연결하는 모델 주변의 비계(scaffolding)입니다.
• 하네스가 당면한 작업에 얼마나 잘 부합하느냐가 에이전트의 유용성을 결정합니다.
• LangChain의 create_agent는 주어진 작업에 맞춤화된 커스텀 하네스를 구축하는 가장 쉬운 방법입니다.

유용한 에이전트를 구축하는 것은 주로 *커스터마이징(customization)*에 관한 것입니다. 즉, 에이전트를 당면한 작업에 적합한 컨텍스트(context), 데이터, 그리고 환경(environment)에 연결하는 것입니다.

본질적으로, 에이전트는 작업을 완료하고 결과를 반환할 때까지 루프(loop) 내에서 도구(tools)를 호출하는 모델입니다:

또한 에이전트를 다음과 같이 정의할 수도 있습니다:

agent = model + harness

하네스는 모델을 실제 세상과 연결하는 모델 주변의 비계(scaffolding)입니다.

이 포스트의 나머지 내용은 다음을 전제로 합니다:

• 에이전트의 성능은 모델에 제공되는 컨텍스트(context)만큼만 뛰어납니다.
• 하네스의 역할은 매 단계마다 모델에 컨텍스트(context)를 제공하는 것입니다.

따라서 유용한 에이전트를 구축하려면, 주어진 작업에 대한 적절한 컨텍스트(context)를 모델에 전달하는 데 탁월한 하네스가 필요합니다.

기본 하네스 (The base harness)

create_agent는 하네스를 구축하기 위한 LangChain의 프리미티브(primitive)입니다. 모델, 도구(tools), 그리고 시스템 프롬프트(system prompt)를 전달하면 작동하는 에이전트를 얻을 수 있습니다:

from langchain.agents import create_agent
agent = create_agent(
model="anthropic:claude-sonnet-4-6",
...

Deep Agents나 Claude Agent SDK와 같은 하네스들은 메모리(memory), 컨텍스트 관리(context management), 샌드박싱(sandboxing) 등 의견이 반영된(opinionated) 미들웨어(middleware) 스택이 미리 조립되어 제공됩니다. 이들은 사용자가 빠르게 프로덕션 준비가 된 에이전트를 확보할 수 있도록 설계되었으며, 대부분의 사례에서 잘 작동합니다. 하지만 많은 에이전트들은 이러한 하네스들이 지원하는 것보다 더 세밀한 수준의 커스터마이징(customization), 즉 커스텀 프롬프팅(custom prompting), 비즈니스 로직(business logic), 가드레일(guardrails) 등을 필요로 합니다.

create_agent는 다른 접근 방식을 취합니다. 그것은 *의도적으로 미니멀리즘(minimalistic)*을 지향합니다. 우리의 철학은 매우 구성 가능한 코딩 에이전트 하네스인 Pi의 철학과 유사합니다. create_agent는 핵심적인 에이전트 루프(agent loop)만을 구현하며, 커스터마이징을 위한 프리미티브(primitive)로서 **미들웨어(middleware)**를 노출합니다.

미들웨어(Middleware): 하네스를 커스터마이징하는 방법

미들웨어는 에이전트 루프(agent loop)의 각 단계, 즉 모델 호출 전후, 도구 호출(tool calls) 전후, 에이전트 시작 및 종료 시점에 개입합니다. 각 구성 요소는 하나의 관심사(concern)를 처리하며, 다른 어떤 요소와도 자유롭게 조합될 수 있습니다:

미들웨어를 사용하면 종종 함께 작동하는 몇 가지 레버(levers)를 통해 에이전트에 **기능(capabilities)**을 추가할 수 있습니다:

결정론적 로직 (Deterministic Logic). 비즈니스 로직, 정책 강제(policy enforcement), 동적 에이전트 제어 등 루프의 특정 시점에 실행되어야 하는 모든 것을 의미합니다. 여기에는 에이전트 자체에 대한 런타임 제어가 포함됩니다. 예를 들어, 작업 복잡도에 따라 모델을 교체하거나, 프롬프트(prompt)를 조정하거나, 에이전트의 메시지 히스토리(message history)를 업데이트(예: 압축(compaction) 과정 중)하는 작업 등이 있습니다. 프롬프트에 담을 수 없거나(또는 담아서는 안 되는) 모든 것을 처리하기에 적합한 장소입니다.

도구 (Tools). 에이전트에 도구를 직접 등록하는 대신, 미들웨어가 전체 생명주기(lifecycle)—설정(setup), 종료(teardown), 등록(registration)—를 관리하고 에이전트에게 작업에 필요한 깔끔한 도구 세트를 전달할 수 있습니다. 이는 도구에 의존성(dependencies)이 있거나, 초기화(initialization)가 필요하거나, 실행 종료 시 깔끔하게 정리(teardown)되어야 하는 경우에 중요합니다. 또한 도구 설정이 에이전트 정의 곳곳에 흩어져 있지 않고, 이를 관리하는 로직 근처에 머물게 해줍니다.

커스텀 상태 (Custom state). 미들웨어가 훅(hooks) 전반에 걸쳐 상태를 추적해야 하는 경우, 미들웨어는 커스텀 속성을 통해 에이전트의 상태를 확장할 수 있습니다. 이를 통해 미들웨어는 실행 과정 전반에 걸쳐 상태를 추적하고(카운터, 플래그 또는 에이전트 실행 동안 지속되는 기타 값 유지), 훅 간에 데이터를 공유할 수 있습니다.

스트림 핸들러 (Stream handlers). 미들웨어는 에이전트의 출력 스트림(output stream)을 가로채고 변환할 수 있습니다. 즉, 이벤트를 필터링하거나, 메타데이터(metadata)를 주입하거나, 서로 다른 이벤트 유형을 서로 다른 소비자(consumer)에게 라우팅할 수 있습니다. 이는 스택의 서로 다른 부분들이 에이전트의 서로 다른 동작에 반응해야 할 때 유용합니다. 예를 들어, 토큰 델타(token deltas)를 소비하는 UI, 도구 호출을 캡처하는 감사 로그(audit log), 지연 시간(latency)을 추적하는 모니터링 시스템 등이 이에 해당합니다.

미들웨어의 묘미는 다음과 같습니다:

• 에이전트 루프(agent loop)의 어느 지점에서든 커스터마이징을 가능하게 합니다.
• 관련 로직을 결합 가능하고 공유 가능한 코드 단위로 묶어줍니다.

LangChain은 가장 일반적인 패턴을 위한 사전 구축된 미들웨어(prebuilt middleware)를 제공합니다. 귀하의 사용 사례에 특화된 기능이 필요하다면 단 하나의 커스텀 미들웨어만으로 구현할 수 있습니다. 각 구성 요소가 격리되어 있기 때문에, 동일한 미들웨어를 조직 내 모든 에이전트에서 재사용할 수 있으며, 이를 통해 새로운 에이전트가 다시 구축할 필요 없이 검증된 동작(battle-tested behavior)을 상속받을 수 있습니다.

하네스 기능 (Harness capabilities)

하네스의 역할은 주어진 작업에 대해 모델이 적절한 시점에 적절한 컨텍스트(context)를 가질 수 있도록 하는 것입니다.

아래 표는 일반적인 기능들을 이를 지원하는 미들웨어와 매핑하여 보여줍니다. 대부분의 프로덕션 에이전트는 에이전트의 요구 사항(장기 실행 여부, 작업의 복잡도, 에이전트 동작의 민감도 등)에 따라 여러 미들웨어를 함께 사용하게 됩니다:

사전 구축된 미들웨어의 전체 목록은 여기에서 확인하십시오.

작업-하네스 적합성 (Task-harness fit)

작업-하네스 적합성이란 하네스가 작업의 실제 요구 사항(필요한 컨텍스트, 직면할 실패 사례, 준수해야 할 정책, 동작 환경 등)과 얼마나 잘 일치하는지를 의미합니다. 고객 서비스 에이전트를 위한 하네스는 장기 실행되는 코딩 에이전트를 위해 구축된 하네스와는 매우 다르게 보입니다.

GTM 에이전트, 비동기 코딩 에이전트, 노코드(no-code) 에이전트 빌더를 포함하여 LangChain에서 구축하는 모든 에이전트는 해당 에이전트의 미션에 맞춤화된 미들웨어 스택과 함께 create_agent를 기반으로 구축됩니다.

최고의 에이전트는 단순히 유능한 모델로만 만들어지는 것이 아니라, 작업에 긴밀하게 부합하는 하네스와 함께 만들어집니다. 커스텀 하네스를 구축하는 가장 쉬운 방법은 create_agent를 사용하는 것입니다.

참고 문헌 (References)

시작하기 (Get Started)

• 퀵스타트: create_agent로 첫 번째 에이전트 구축하기
• create_agent 가이드
• 미들웨어 레퍼런스 (Middleware reference)
• 커스텀 미들웨어 가이드
• Deep Agents: create_agent로 구축된 프로덕션 하네스

감사의 글 (Acknowledgements)

사려 깊은 검토와 피드백을 주신 @hwchase17, @huntlovell, @masondrxy, @Vtrivedy10 님께 감사드립니다.