🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Harbor와 LangChain 통합은 장기 실행·상태 변경형 에이전트를 격리된 샌드박스에서 병렬 평가하고, LangSmith로 점수와 실행 추적을 함께 확인하게 해주는 평가 스택이다.

📌 핵심 요약

• 본문은 파일 읽기, 스크립트 실행, 코드 실행처럼 실제 컴퓨터 환경을 다루는 에이전트가 늘어나면서 기존의 단순 LLM 평가 방식만으로는 충분하지 않다고 설명한다.
• Harbor는 에이전트, 데이터셋, 샌드박스를 받아 각 작업을 재현 가능한 환경에서 실행하고, 마지막에는 평가 스크립트로 결과와 생성된 산출물을 검증하는 평가 하네스다.
• LangChain은 Harbor와 Deep Agents, LangSmith Sandboxes, LangSmith Observability 세 지점에서 연결되며, langgraph.json과 make_graph 진입점만으로 LangGraph 또는 Deep Agents 기반 에이전트를 Harbor 안에서 실행할 수 있게 한다.
• 각 trial은 별도의 클라우드 샌드박스에서 실행되므로 상태 공유 없이 격리되며, n_attempts와 작업 수의 조합으로 여러 번 반복 실행해 비결정적인 에이전트 결과를 평균화할 수 있다.
• LangSmith 플러그인을 켜면 Harbor 작업이 데이터셋과 실험으로 기록되고, verifier의 reward가 feedback으로 남으며, 지원되는 경우 에이전트 trace가 붙어 단순 성공 여부가 아니라 실패와 성공의 이유까지 확인할 수 있다.

🧩 주요 포인트

1. 본문은 파일 읽기, 스크립트 실행, 코드 실행처럼 실제 컴퓨터 환경을 다루는 에이전트가 늘어나면서 기존의 단순 LLM 평가 방식만으로는 충분하지 않다고 설명한다.
2. Harbor는 에이전트, 데이터셋, 샌드박스를 받아 각 작업을 재현 가능한 환경에서 실행하고, 마지막에는 평가 스크립트로 결과와 생성된 산출물을 검증하는 평가 하네스다.
3. LangChain은 Harbor와 Deep Agents, LangSmith Sandboxes, LangSmith Observability 세 지점에서 연결되며, langgraph.json과 make_graph 진입점만으로 LangGraph 또는 Deep Agents 기반 에이전트를 Harbor 안에서 실행할 수 있게 한다.
4. 각 trial은 별도의 클라우드 샌드박스에서 실행되므로 상태 공유 없이 격리되며, n_attempts와 작업 수의 조합으로 여러 번 반복 실행해 비결정적인 에이전트 결과를 평균화할 수 있다.
5. LangSmith 플러그인을 켜면 Harbor 작업이 데이터셋과 실험으로 기록되고, verifier의 reward가 feedback으로 남으며, 지원되는 경우 에이전트 trace가 붙어 단순 성공 여부가 아니라 실패와 성공의 이유까지 확인할 수 있다.

🧠 상세 정리

1. 에이전트 평가가 어려워진 배경

본문은 에이전트의 능력이 커지면서 평가 방식도 더 복잡해졌다는 문제의식에서 출발한다. Claude Code, Pi, Deep Agents 같은 에이전트 하네스는 이제 전체 컴퓨터에 접근해 파일을 읽고, 스크립트를 실행하고, 코드를 돌릴 수 있다. 이런 에이전트는 단순히 최종 응답 문자열만 비교하는 방식으로는 제대로 평가하기 어렵다. 작업 중간에 파일을 만들거나 상태를 바꾸고, 실행 환경의 조건에 따라 결과가 달라질 수 있기 때문이다. 그래서 각 에이전트는 주어진 과제를 수행할 때 깨끗하고 재현 가능하며 격리된 환경에서 실행되어야 한다는 점이 핵심 전제로 제시된다.

2. Harbor가 해결하려는 평가 문제

Harbor는 장기 실행되고 상태를 바꾸는 에이전트를 평가하기 위한 eval harness로 소개된다. 본문이 정리한 목표는 실제 환경에서 에이전트를 실행하고, 같은 조건을 재현할 수 있게 하며, 서로 격리된 실행을 병렬로 많이 돌리고, 마지막에 결정적인 검증을 수행하는 것이다. Harbor 사용자는 에이전트, 데이터셋, 샌드박스라는 세 가지 요소를 가져오면 된다. 각 데이터셋은 여러 task로 구성되며, task는 Dockerfile 또는 Docker Compose YAML로 된 환경, Markdown 형식의 instruction, test.sh 형태의 평가 스크립트를 포함한다. 이 구조는 평가 대상이 텍스트 응답이 아니라 환경 안에서 수행된 실제 작업이라는 점을 반영한다.

3. 단순 LLM 평가와의 차이

본문은 Harbor식 에이전트 평가가 단순 LLM 평가와 다른 지점을 두 가지로 설명한다. 첫째, 에이전트가 실행되는 환경 자체가 평가의 중요한 일부가 되며, 그래서 task 정의 안에 환경을 명시해야 한다. 일반적인 LLM 평가는 모델을 호출해 응답을 받는 방식이지만, 에이전트는 파일 시스템, 쉘, 코드 실행 같은 외부 상태와 상호작용한다. 둘째, 에이전트의 평가는 최종 답변만 보는 것이 아니라 스크립트로 판정된다. 에이전트가 만든 파일, 변경한 상태, 수행 과정의 산출물이 실제 성공 여부를 결정할 수 있으므로 verifier script가 필요한 것이다.

4. LangChain이 Harbor에 연결되는 세 지점

LangChain은 Harbor와 세 가지 방식으로 연결된다. 첫째, Deep Agents와 통합되어 사용자가 만든 deep agent를 Harbor의 샌드박스 환경 안에서 실행할 수 있다. 둘째, LangSmith Sandboxes와 통합되어 Harbor가 각 task를 별도의 LangSmith sandbox에서 실행하게 하며, 각 run은 깨끗한 머신을 가진다. 셋째, LangSmith Observability와 연결되어 평가 결과를 자세히 볼 수 있는 플랫폼을 제공한다. 이때 모든 job은 dataset과 experiment로 남고, 에이전트가 trace를 지원하면 실행 trace가 함께 붙어 trial이 왜 통과했는지 또는 왜 실패했는지 확인할 수 있다.

5. langgraph.json과 make_graph 진입점

사용자는 Harbor의 내장 langgraph agent를 선택해 커스텀 에이전트를 연결할 수 있으며, 명령에서는 --agent langgraph를 사용한다. Harbor는 langgraph.json을 일종의 registry로 다루고, 이 파일에는 에이전트가 필요로 하는 dependencies와 graph 이름이 어떤 함수로 빌드되는지가 적힌다. 예시에서는 deep_agent라는 graph 이름이 agent.py의 make_graph 함수로 연결되고, 이 함수가 Deep Agent를 만든 뒤 Harbor가 호출할 compiled graph를 반환한다. 본문은 이것이 사용자가 작성해야 하는 거의 유일한 glue code라고 강조한다. 에이전트 로직은 기존 코드로 유지되고, make_graph는 Harbor가 들어오는 작은 진입점 역할만 한다.

6. 샌드박스 접근과 모델 선택의 유연성

본문은 Deep Agents의 기본 파일 처리 방식과 Harbor 샌드박스 접근 사이의 차이도 설명한다. create_deep_agent는 기본적으로 파일을 인메모리 가상 파일 시스템에 보관해 실제 샌드박스에 닿지 않으므로, Harbor 환경의 파일과 쉘에 접근하려면 LocalShellBackend와 함께 사용해야 한다. 또한 graph가 모델을 하드코딩할 수도 있지만, Harbor가 run config를 넘겨주는 factory 함수로 만들면 모델 선택을 명령행에서 바꿀 수 있다. Harbor는 --model로 선택된 모델을 configurable.model에 넣고, make_graph는 이를 읽어 create_deep_agent에 전달한다. 이 방식 덕분에 같은 에이전트 진입점이 특정 모델에 고정되지 않고 Harbor 실행 설정을 따라갈 수 있다.

7. 클라우드 샌드박스와 trial 단위 실행

LangSmith sandbox와 Harbor의 통합은 평가를 수평 확장할 수 있게 한다는 점에서 강조된다. 하나의 머신에서 trial을 순차적으로 처리하는 대신, 클라우드 기반 샌드박스를 사용하면 수백 개 trial을 동시에 실행해 더 빠르게 피드백을 얻을 수 있다. 본문에서 trial은 하나의 task에 대해 에이전트를 한 번 실행하는 원자적 작업 단위로 정의된다. 에이전트는 비결정적일 수 있으므로 같은 task를 여러 번 실행하는 n_attempts가 중요하며, Harbor는 각 반복을 별도 trial로 처리하고 점수를 평균화한다. 각 trial마다 Harbor는 신선한 샌드박스를 만들고 에이전트 코드, task, 시작 파일을 복사한 뒤 instruction 실행, verifier 실행, 결과 기록을 순서대로 수행한다.

8. LangSmith Observability와 전체 평가 스택

harbor-langsmith 통합은 --plugin langsmith 플래그 하나로 활성화되며, Harbor 작업을 LangSmith에 기록한다. Harbor는 dataset을 동기화하고 experiment를 만들며, trial마다 run을 남기고 verifier의 reward를 feedback으로 기록한다. 에이전트가 LangSmith tracing을 지원하면 trace가 experiment에 직접 붙어 점수와 단계별 실행 궤적을 함께 볼 수 있다. trace가 없더라도 dataset, experiment, results, feedback은 남기 때문에 평가 기록의 중심 저장소 역할은 유지된다. 본문은 최종적으로 Harbor가 trial orchestration을 맡고, Deep Agents가 평가 대상 에이전트 구축을 맡고, LangSmith sandboxes가 격리 실행 환경을 제공하며, LangSmith가 dataset, experiment, trace, score의 기록 시스템이 되는 전체 스택을 제시한다.

🧾 핵심 주장 / 시사점

• 본문의 핵심은 에이전트 평가가 이제 모델 출력 비교가 아니라 실행 환경, 상태 변화, 산출물 검증을 포함하는 시스템 평가로 바뀌고 있다는 점이다.
• Harbor와 LangSmith의 결합은 병렬 실행과 격리뿐 아니라, 점수와 trace를 연결해 평가 결과를 디버깅 가능한 설명으로 바꾸는 데 초점을 둔다.
• langgraph.json과 make_graph만으로 통합 지점을 작게 유지한 설계는 기존 LangGraph 또는 Deep Agents 코드의 소유권을 유지하면서도 Harbor 평가 흐름에 편입할 수 있게 한다.

✅ 액션 아이템

• 기존 단일 LLM 평가 방식은 파일·스크립트·코드 실행 시나리오를 충분히 반영하지 못하므로 Harbor 재현형 하네스 기반 평가로 확장한다.
• Harbor-구동을 위해 langgraph.json 및 make_graph 진입점을 정리해 LangGraph와 Deep Agents 통합 실행 파이프라인을 정의한다.
• trial별 독립 샌드박스 특성을 반영해 n_attempts와 작업 수 조합으로 반복 수행한 뒤 LangSmith trace·reward를 함께 점검해 성공·실패 원인을 분석한다.

❓ 열린 질문

• 비결정성 완화를 위해 n_attempts와 작업 수의 조합을 어디까지 넓혀야 평균화 신뢰도를 확보할 수 있는가?
• Harbor-verified reward 값을 운영 의사결정 지표로 사용할 때 어떤 기준선으로 성능 임계값을 설정할 것인가?
• LangSmith trace가 수집되지 않는 실행에서 실패 원인 추적을 보완하기 위한 최소 검증 로그·산출물 기준은 무엇인가?