NVIDIA Nemotron 3 Ultra 성능 향상을 위한 LangChain Deep Agents 하네스 프로필 만들기

Reading Time: 6 minutes

에이전트 시스템은 종종 정확도와 비용 사이의 트레이드오프에 직면합니다. 최고 성능의 독점 프론티어 모델과 하네스는 높은 정확도를 제공하지만 비용이 많이 듭니다. 파인튜닝은 이 문제를 해결하는 한 가지 방법입니다. 초기 정확도가 낮은 소형 또는 효율적인 오픈 모델을 특정 에이전트에서 더 잘 작동하도록 학습시키는 방식입니다. 그러나 파인튜닝에는 커스텀 모델 학습 및 호스팅을 위한 전문 지식과 하드웨어가 필요합니다.

특정 사용 사례에 맞게 프롬프트를 튜닝하는 것은 일반적인 관행이지만, 에이전트 하네스에 이 프로세스를 공식화하고 유의미한 성능 향상을 검증하는 것은 최근에야 가능해졌습니다. 이를 가능하게 하는 두 가지 발전이 있습니다:

특정 하네스에 맞게 구축된 평가 벤치마크로, 변경 사항이 성능을 개선하는지 검증할 수 있습니다.
LangChain의 에이전트 하네스 프로필과 같은 모델별 커스터마이징 진입점은 팀이 특정 에이전트 워크플로우에 모델을 적응시킬 수 있는 최초의 사례입니다.

이 튜토리얼에서는 독점 프론티어 모델 수준의 지능을 달성하는 NVIDIA Nemotron 3 Ultra용 LangChain Deep Agents 하네스 프로필을 만들어 보겠습니다. 모든 조정은 NVIDIA 클라우드 공급자에서 제공하는 기존 NVIDIA Nemotron 3 Ultra 엔드포인트를 사용하여 에이전트 하네스에 적용됩니다.

사전 준비

Python과 LangChain Deep Agents가 설치된 호스트
NVIDIA Nemotron 3 Ultra용 API 키. 테스트 목적으로는 build.nvidia.com에서 무료 API 액세스를 제공합니다. 프로덕션 환경에서는 Baseten, Crusoe, Fireworks, Nebius, Together AI 등 NVIDIA 클라우드 공급자의 엔드포인트를 사용하세요.
권장 사항: 에이전트 추적 수집을 위한 LangSmith 계정

평가를 실행하여 하네스 프로필 만들기

LangChain Deep Agents는 인기 있는 오픈 소스 에이전트 하네스입니다. 특정 모델에 맞게 에이전트 하네스를 튜닝하기 위해 LangChain은 두 가지 중요한 도구를 제공합니다:

오픈 소스 평가 벤치마크
개발자가 모델에 따라 에이전트 하네스 동작을 변경할 수 있는 일급 확장 포인트를 제공하는 에이전트 하네스 프로필

NVIDIA Nemotron 3 Ultra용 딥 에이전트를 튜닝하는 절차는 다음과 같습니다:

하네스 프로필 없이 NVIDIA Nemotron 3 Ultra를 사용한 딥 에이전트로 평가 벤치마크를 실행하여 기준선을 수립합니다.
실패 사례를 분석합니다.
실패 사례를 해결하는 하네스 프로필 변경 사항을 제안합니다.
벤치마크를 재실행하여 변경 사항이 회귀 없이 평가를 개선하는지 검증합니다.

에이전트 하네스 프로필에서 사용 가능한 변경 유형은 다음과 같습니다:

프롬프트: 딥 에이전트의 기본 시스템 프롬프트 변경, 프롬프트 접미사 적용, 또는 도구 설명 변경. 예를 들어, Nemotron Ultra가 명확화 질문을 선호하거나 모델 회상보다 도구 결과를 선호하도록 지시를 추가합니다.
제외: 제거할 도구 또는 미들웨어.
추가: 잘린 모델 응답이나 잘못된 도구 이름을 확인하는 미들웨어와 같이 추가 미들웨어 또는 서브 에이전트로 하네스를 확장합니다.

하네스 엔지니어링의 목표는 에이전트에서 모델로의 호출이 모델이 학습 데이터에서 본 것과 더 유사하게 만드는 것입니다.

1. 평가 실행

NVIDIA Nemotron 3 Ultra는 내장 read_file 도구에 대한 테스트에서 실패합니다.

실패한 테스트: tests/evals/test_file_operations.py::test_read_file_truncation_recovery_with_pagination[nvidiahub:ultra-tme]

실패 내용:

success check failed: Expected final text to contain 'opal-fox-91', got: 'x'
Trajectory:
step 1:
  - read_file {'file_path': '/big.txt'}
step 2:
  text: x

read_file 도구는 코딩, 데이터 분석, 스킬 보기와 같은 에이전트 작업에 사용되는 LangChain Deep Agent 하네스의 핵심 구성 요소입니다. 이 작업은 /big.txt에서 마지막 비어 있지 않은 줄을 찾는 것입니다. 첫 번째 read_file 호출은 x 값만 포함된 파일의 첫 번째 페이지를 반환합니다. 정답인 opal-fox-91은 파일의 뒷부분에 있습니다. 모델은 offset/limit 페이지네이션으로 계속 읽어야 했지만 첫 번째 페이지를 기반으로 답변했습니다.

2. 수정 사항 제안

class ReadFileContinuationNoticeMiddleware(AgentMiddleware):
    """Tell the model when a read_file result probably continues."""
    name = "ReadFileContinuationNoticeMiddleware"
    def wrap_tool_call(self, request, handler):
        return self._annotate(request, handler(request))
    @staticmethod
    def _annotate(request, result):
        if not isinstance(result, ToolMessage):
            return result
        if request.tool_call.get("name") != "read_file":
            return result
        content = str(result.text)
        args = request.tool_call.get("args", {}) or {}
        offset = int(args.get("offset", 0))
        limit = int(args.get("limit", 100))
        n_lines = sum(
            1
            for row in content.split("\n")
            if "\t" in row and row.split("\t", 1)[0].strip().isdigit()
        )
        if n_lines < limit:
            return result
        notice = (
            f"\n\n[read_file returned {limit} lines starting at offset {offset}, "
            f"the per-read limit. The file likely continues past this window. "
            f"To read further, call read_file again with offset={offset + limit}. "
            f"Do not assume you have seen the end of the file.]"
        )
        return result.model_copy(update={"content": content + notice})

하네스 프로필에 미들웨어를 추가합니다:

profile = HarnessProfile(
    extra_middleware=[
        ReadFileContinuationNoticeMiddleware(),
    ]
)
register_harness_profile("nvidia:nemotron-ultra", profile)

3. 수정 사항 검증

새 프로필로 실패한 테스트를 재실행합니다:

uv run pytest \
  tests/evals/test_file_operations.py \
  --model nvidia:nemotron-utlra \
  --harness-profile nemotron-ultra

테스트를 통과한 후, 프로필 변경이 회귀를 유발하지 않았는지 확인하기 위해 전체 평가 벤치마크를 재실행합니다. 벤치마크와 테스트 모두 확률적이므로 기준선과 제안된 변경 사항을 여러 번 실행하는 것이 중요합니다.

표 1: 결과

프로필	파일 읽기 테스트	평가 벤치마크
기준선	0 / 3	평균 94 / 127
파일 읽기 미들웨어	3 / 3	평균 96 / 127

결과는 파일 미들웨어가 실패한 세 가지 read_file 테스트를 모두 해결하고 전체 평가 벤치마크 점수를 94에서 96/127로 향상시켰음을 보여줍니다.

변경 사항을 확정하기 전에 과적합을 고려하는 것이 중요합니다. 이 예시에서 파일 페이지네이션 미들웨어는 기계적인 수정입니다. 모델에게 적절한 도구 호출 방법을 가르칩니다. 반면, 에이전트가 “incident alerts”와 “incident triage”를 혼동하여 평가 작업에 실패하는 경우를 상상해 보세요. 하네스에 “alert”이나 “triage”의 정의를 추가하면 과적합이 발생할 가능성이 더 높습니다.

하네스 프로필 생성 자동화

앞의 세 단계의 수동 절차는 하나의 루프입니다. 벤치마크를 실행하고, 실패 사례를 읽고, 프로필을 변경하고, 다시 실행합니다. 이런 루프는 에이전트가 무인으로 실행하기에 적합한 작업입니다. Geoffrey Huntley는 이를 “ralph 루프”라고 부릅니다: 모델이 현재 상태를 반복적으로 읽고, 하나의 변경을 만들고, 대화가 아닌 파일시스템을 메모리로 사용합니다. 코딩 에이전트를 위해 고안되었지만, 이 패턴은 광범위하게 적용됩니다.

하네스 엔지니어링도 동일한 루프를 다른 대상에 적용한 것입니다. 코드베이스 대신 프로필 파일을, 테스트 스위트 대신 평가 벤치마크를 사용하면 형태가 동일합니다. 변경 사항을 제안하고, 객관적인 신호로 확인하고, 유지하거나 버리고, 반복합니다. 평가 벤치마크가 이를 자동화해도 안전하게 만드는 요소입니다—루프에 ground-truth 검증자를 제공하여 제안된 변경이 측정 가능하게 도움이 될 때만 유지됩니다.

LangSmith Engine은 하네스 개선을 위한 이 루프의 LangChain 관리형 버전입니다. 프로덕션 추적에서 실패를 감지하고, 소스 코드에 대해 근본 원인을 진단하고, 수정 사항을 초안 작성하고, 회귀가 재발하지 않도록 평가자를 추가합니다. 각 제안된 변경 사항은 출시 전에 사람이 검토합니다.

나머지 섹션에서는 유사한 알고리즘의 간소화된 버전을 설명하며, NemoClaw 커뮤니티 저장소에 LangChain Deep Agents를 기반으로 한 실행 가능한 참조 구현이 있습니다. 의도적으로 소규모로 설계되었으며—라이브 트래픽이 아닌 평가 벤치마크에 대해 단일 하네스 프로필을 튜닝합니다—하지만 유사한 자기 수정 루프를 end-to-end로 실행하여 메커니즘을 따라가고 직접 시도해볼 수 있습니다.

개선 루프

외부 루프는 의도적으로 단순하지만, 몇 가지 결정이 신뢰할 수 있는 개선 루프와 과적합 머신을 구분합니다:

믿기 전에 검증하기. 모델 호출은 확률적이고, LLM이 판단하는 벤치마크도 마찬가지입니다. 수정 사항은 동일한 테스트를 연속으로 여러 번 통과해야만 수락되어, 운 좋게 한 번 통과한 변경 사항을 걸러냅니다.
스냅샷 저장 및 롤백. 각 시도 전에 프로필이 저장되고 시도가 도움이 되지 않으면 복원되므로, 나쁜 제안이 프로필을 시작보다 더 나쁘게 만들 수 없습니다.
마지막 시도에서 배우기. 시도가 실패하면, 루프는 다음 시도에 방금 시도한 것과 실패 방법을 정확히 전달하여 모델이 동일한 수정을 다시 제안하는 대신 접근 방식을 개선합니다.
전체 스위트 재검사. 수정 사항이 적용된 후, 수정된 테스트만이 아니라 전체 벤치마크가 재실행되어 회귀를 잡고, 새로 차단 해제된 경로가 노출하는 테스트를 발견합니다.

루프는 프로필이 깨끗하게 통과하거나, 전체 라운드에서 개선이 없거나, 반복 예산이 소진될 때까지 라운드별로 계속됩니다.

그림 1. 개선 루프—벤치마크 실행, 실패에 대한 프로필 변경 제안, 반복 검증, 유지 또는 롤백, 전체 스위트 재실행 반복

에이전트 제안자

흥미로운 부분은 “변경 사항 제안” 단계로, 모델이 실패에 대한 설명을 받고, 솔루션 탐색을 위한 도구가 주어지며, 프로필 수정을 제안합니다.

각 제안은 짧고 제한된 에이전트 세션으로 실행됩니다. 에이전트는 프로필의 쓰기 가능한 복사본과 실패한 테스트, 관찰된 에이전트 추적, SDK 및 벤치마크 코드에 대한 읽기 전용 액세스를 받습니다. 파일 읽기, 편집, grep, glob과 같은 일반 도구를 사용하여 스니펫에서 추측하는 대신 미들웨어 훅이나 도구 기본값이 어떻게 동작하는지 확인할 수 있습니다. 그런 다음 진단된 실패를 해결하는 최소한의 변경을 하고 변경한 내용과 이유에 대한 간단한 설명을 작성합니다.

두 가지 제약이 에이전트를 올바른 방향으로 유지합니다. 쓰기 액세스는 프로필 파일에만 범위가 제한되어 있어 전체 코드베이스를 컨텍스트로 읽을 수 있지만 튜닝 중인 한 파일만 수정할 수 있습니다. 그리고 특정 해킹보다 일반적인 수정을 선호하도록 지시받습니다—하나의 테스트의 정확한 입력을 특수하게 처리하는 것이 아니라 실패가 드러내는 더 광범위한 동작을 추론하도록 합니다. 이 구별이 모델에게 지속적인 스킬을 가르치는 것과 단일 답변을 암기하는 것의 차이입니다.

과적합을 더 방지하기 위해 이 평가 스위트의 일부를 검증 세트로 보류하도록 지정할 수 있습니다. 변경을 수행하는 에이전트 루프는 이 테스트를 볼 수 없지만, 테스트의 점수는 프로필 개선을 검증하는 데 사용됩니다.

다음 축약된 출력은 앞서 식별된 read_file 페이지네이션 실패를 해결하기 위해 딥 에이전트 하네스와 Nemotron 3 Ultra에 대해 참조 구현이 실행되는 것을 보여줍니다:

$ hep langchain ralph \
    --model "openai:nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B" \
    --profile examples/deepagents/profiles/nvidia_nemotron_3_ultra.py \
    --evals-dir external/deepagents/libs/evals \
    --category file_operations \
    --ralph-model "anthropic:...:bedrock-claude-opus-4-8" \
    --ralph-max-turns 100 \
    --max-iters 100 \
    --max-iters-per-failure 5 \
    --verify-runs 3

[ralph] baseline: 20 passed, 1 failed  (correctness: 0.95)

  FAILED test_read_file_truncation_recovery_with_pagination
  Expected final text to contain 'opal-fox-91', got: 'x'
    step 1: read_file {'file_path': '/big.txt'}
    step 2: text: x

[ralph] round 1 — fixing pagination failure (attempt 1/100)
[ralph:proposer] Root cause: read_file pages by lines (100),
  and the result gives no signal the file continues past the
  page — so the model treated the first page's last line as
  EOF and answered after one call.

  Fix (profile levers, not test-specific values):
    1. Middleware: when a page returns full (lines == limit),
       append a hint to keep paging (offset=<last line>)
       until a short page signals EOF.
    2. Prompt: page to EOF before answering end-of-file
       questions.

[ralph]   verify 1/3 ✓   2/3 ✓   3/3 ✓
[ralph]   FIXED

[ralph] === re-running full suite ===
  results: 21 passed, 0 failed  (correctness: 1.00)

result: 20 → 21 passed, 1 → 0 failed

에이전트는 실패의 근본 원인을 진단하고, 세 번의 연속 검사를 통과한 수정을 적용했으며, 회귀 없이 전체 스위트 재실행을 통과했습니다.

Ultra를 다른 하네스에 적용하기

이 자동화 루프의 어떤 부분도 LangChain Deep Agents에 한정되지 않습니다. 이 프레임워크를 사용하여 Ultra를 다른 에이전트 프레임워크에 적용하려면 세 가지를 노출해야 합니다: 평가를 실행하고 테스트별 통과/실패 결과와 추적을 보고하는 방법, 프로그래밍 방식으로 편집하고 검증할 수 있는 프로필 또는 구성 파일, 편집 사항을 제안할 프론티어 품질 모델. 이 세 가지가 주어지면, 동일한 루프—제안, 검증, 유지 또는 롤백, 재실행—가 변경 없이 실행됩니다.

더 알아보기

LangChain 팀이 게시한 Nemotron 3 Ultra 에이전트 하네스 프로필을 검토하세요.
Nemotron을 포함하고 NVIDIA OpenShell을 추가한 LangChain Deep Agents용 NVIDIA NemoClaw 블루프린트를 테스트해보세요.
LangChain 개발자는 Baseten, Crusoe Cloud, DeepInfra, Fireworks, Nebius, Together AI 플랫폼에서 Nemotron 3 Ultra에 액세스할 수 있습니다.
에이전트 하네스, 모델, 워크로드를 튜닝하여 NVIDIA가 Deep Research Bench에서 1위를 달성한 방법을 살펴보세요.
실습 학습 모듈로 첫 번째 딥 에이전트를 만들어보세요.