Is it agentic enough? Benchmarking open models on your own tooling

에이전트를 위한 소프트웨어 테스트의 시대

이제 코딩 에이전트는 우리 대신 소프트웨어를 다루는 일이 점점 더 많아지고 있어요. 개발자가 작업을 설명하면 에이전트가 알아서 라이브러리를 선택하고, 코드를 작성하고, 실행하며, 스스로 오류를 디버깅합니다. 만약 사용하려는 라이브러리가 복잡하고 방해가 된다면 에이전트는 라이브러리를 우회해 처음부터 로직을 새로 작성해 버리기도 하죠.

여기서 라이브러리 개발에 있어 새로운 개념이 등장합니다. 코드가 단순히 정확하고 빠를 뿐만 아니라, 에이전트가 이를 효과적으로 제어할 수 있도록 설계되어야 한다는 점이에요. 엉성한 API나 업데이트되지 않은 문서는 인간 개발자뿐만 아니라 에이전트까지 헤매게 만들어 더 길고 비용이 많이 드는 길로 가게 만듭니다.

대부분의 벤치마크는 최종 답변만 확인하지만, 우리는 전체 과정을 보고 싶었습니다. 단순히 에이전트가 정답을 맞췄는지가 아니라, 거기에 도달하기 위해 얼마나 많은 작업이 필요했는지, 그리고 모델과 라이브러리 버전, 태스크에 따라 그 과정이 어떻게 변화하는지 측정하고자 했어요. 우리는 transformers 라이브러리를 케이스 스터디로 삼아 이 과정을 정확히 측정해 보았습니다.

우리는 에이전트가 정답을 찾아낸 과정에 초점을 맞춘 도구 전용 벤치마크를 소개하고, 오픈 소스 모델과 pi 코딩 에이전트로 구동되는 하네스(Harness)의 간단한 구현체를 제공합니다. 모든 실험은 동일한 하드웨어 조건을 보장하기 위해 Hugging Face Jobs 환경에서 실행되었어요.

소프트웨어를 에이전트에 최적화하는 핵심 원칙: 1. 테스트되지 않은 기능은 작동하지 않는 것이다. 2. 문서화되지 않은 기능은 존재하지 않는 것이다.

에이전트가 여러분의 도구를 사용하게 하려면 발견 가능성(discoverability)이 높아야 해요. API는 명확해야 하고, 문서는 광범위해야 합니다. 그래야 에이전트가 필요한 파일과 예제에 신속하게 접근할 수 있죠. 에이전트를 위해 도구를 작동하게 하려면, 에이전트 관점의 사용성을 직접 테스트해 보아야 합니다.

모든 성공이 같은 가치를 가지는 것은 아닙니다

두 에이전트가 감성 분류(Sentiment Classification) 작업에서 동일하게 올바른 라벨을 도출했다고 가정해 볼게요. 하지만 그 과정은 완전히 다를 수 있습니다.

• A 에이전트: 40줄짜리 파이썬 스크립트를 작성하고, transformers를 임포트하고, 텐서 크기 에러를 디버깅하고, 두 번 재실행한 끝에 최종 결과를 출력합니다.
• B 에이전트: 터미널에 transformers classify --model ... --text "..."라는 한 줄의 명령어를 입력하고 끝냅니다.

두 에이전트 모두 POSITIVE (0.9999)라는 동일한 결과에 도달했지만, 소요된 비용, 지연 시간(latency), 토큰 소모량, 실패율은 극적으로 다릅니다.

# A 에이전트의 번거로운 방식: 스크립트를 작성해 python으로 파이핑하고 출력 파싱
python - <<'PY'
from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch
import torch.nn.functional as F

model = AutoModelForSequenceClassification.from_pretrained("distilbert/distilbert-base-uncased-finetuned-sst-2-english")
tokenizer = AutoTokenizer.from_pretrained("distilbert/distilbert-base-uncased-finetuned-sst-2-english")
inputs = tokenizer("I absolutely loved the movie, it was fantastic!", return_tensors="pt")
with torch.no_grad():
    logits = model(**inputs).logits
    probs = F.softmax(logits, dim=1)
    idx = torch.argmax(probs, dim=1).item()
    print(model.config.id2label[idx], probs[0][idx].item())
PY

# B 에이전트의 최적화된 방식: 단 한 줄의 명령어로 해결
transformers classify \
  --model distilbert/distilbert-base-uncased-finetuned-sst-2-english \
  --text "I absolutely loved the movie, it was fantastic!"

최종 텍스트 결과물만 검증하는 단순 평가 방식으로는 이러한 내부 과정의 비효율성을 전혀 발견할 수 없습니다. 우리가 릴리스한 CLI 개선 사항이나 에러 메시지, 그리고 컨텍스트에 추가된 스킬(Skill)이 실제로 에이전트에게 도움이 되었는지 알기 위해서는 새로운 평가 체계가 필요합니다.

에이전트 평가는 어떻게 진행될까요?

우리는 에이전트가 transformers에 접근하는 방식을 다음의 세 가지 계층(Tier)으로 나누어 테스트를 진행했습니다.

이 세 계층은 상호 배타적입니다. 예를 들어 skill은 소스 트리를 포함하지 않고 오직 큐레이션된 문서와 예제만 제공합니다. 때에 따라 모델이 skill보다 clone 환경에서 더 우수한 성능을 보여주기도 해요.

안정적인 비교 분석을 위해 몇 가지 설정을 더 추가했습니다.

• 정확한 텍스트 매칭이 가능한 결정론적 작업 위주로 우선 평가를 설계했습니다.
• 매 실험은 독립된 Hugging Face Job에서 개별적으로 구동되어, 모든 (모델 × 리비전 × 태스크) 조합이 완전히 동일한 하드웨어 조건에서 병렬 실행됩니다.
• 결과와 에이전트의 전체 실행 추적(Traces) 데이터는 Hugging Face Bucket에 실시간으로 기록됩니다.

대형 오픈 모델: 모델은 고정하고 라이브러리 버전을 변경하기

충분히 뛰어난 대형 오픈 모델들은 웬만한 일반적인 작업에서 결국 정답을 찾아냅니다. 따라서 이러한 모델을 평가할 때는 작업 성공률보다 거기에 도달하기 위해 투입된 에이전트의 노력(턴 수, 소모 토큰, 소요 시간 등)을 측정하는 것이 합리적입니다.

강력한 대형 모델 하나를 고정해 두고, 라이브러리의 버전(Revision)을 다르게 적용해 보았습니다. 즉, 공식 릴리스 버전(v5.8.0, v5.9.0)부터 CLI와 Skill이 새로 도입된 최신 커밋까지 차례대로 대입하며 에이전트의 작업 부하가 어떻게 달라지는지 추적한 것이죠.

테스트 결과, CLI와 스킬 문서가 도입된 리비전(Skill commit)에서 대형 모델들은 확실히 작업을 훨씬 빠르게 끝마치는 양상을 보였습니다. 하지만 흥미로운 트레이드오프도 발견되었습니다.

clone 환경의 경우, 리포지토리 전체가 에이전트 앞에 노출되기 때문에 새로 도입된 CLI 명령어의 구현 코드와 cli/agentic/*.py 예제 소스들을 에이전트가 직접 탐색하며 읽어내려가기 시작했습니다. 이 때문에 중간 입력 토큰 크기가 기존 ~4k에서 ~6.4k 토큰으로 크게 증가하는 현상이 발생했습니다.

이러한 현상은 에이전트가 매번 새로운 세션에서 새로 공부하는 일회성 실험 구조 때문에 생기는 일종의 '학습 비용'입니다. 실제 프로덕션 환경에서는 세션 초기에 한 번만 인터페이스를 학습하면 이후 수많은 작업을 비용 효율적으로 해결할 수 있기 때문에 감수할 만한 트레이드오프라고 볼 수 있습니다.

소형 모델: 라이브러리 버전은 고정하고 모델을 변경하기

소형 오픈 모델들은 제한된 크기로 인해 구 버전 API를 오용하거나 불필요한 도구 호출을 남발하여 정답률 자체가 크게 떨어지는 경우가 많습니다. 따라서 소형 모델을 평가할 때는 버전은 고정한 채 여러 종류의 모델들을 교체해가며 정답 매칭률(Match %)과 도구 호출 안정성을 평가하는 것이 중요합니다.

실험을 해보니 모델 크기가 작을수록 도구를 다루는 난이도가 급격히 상승하며, 정답률 또한 요동치는 모습을 확인할 수 있었습니다. 재미있는 점은 대형 모델들의 구원 투수였던 skill 계층이 소형 모델에서는 오히려 정답률을 떨어트리는 악영향을 주기도 했다는 점입니다.

도구의 미세 조정: 마커(Marker)와 결과

단순히 토큰 수와 시간만 보는 것으로는 시스템 내부에서 어떤 일이 일어났는지 완전히 이해하기 어렵습니다. 그래서 우리는 마커(Marker)라는 개념을 도입했습니다. 마커는 에이전트가 실행한 쉘 명령어, 작성한 코드, 읽은 파일 중에서 우리가 감지하고 싶은 행동 양식을 가리키는 라벨입니다.

• cli 마커: 파이썬 코드를 작성하는 대신 transformers CLI 도구를 실행한 경우 감지
• pipeline 마커: 파이썬의 고수준 pipeline(...) API를 직접 호출한 경우 감지

모델의 크기가 커질수록 사전 학습된 기억에만 의존하기보다 주어진 문서(Skill) 환경을 기민하게 포착하여 새로 도입된 CLI 도구를 훌륭히 다루는 모습을 확인할 수 있었습니다. 실제로 CLI 문서가 탑재된 skill 계층에서 대형 모델들의 CLI 도입율(CLI Adoption)은 55.3%에 달했습니다.

CLI + Skill 커밋은 실제로 도움이 되었을까요?

결론부터 말씀드리면, 대형 모델에는 날개를 달아주었지만 일부 소형 모델에는 오히려 독이 되었습니다.

Kimi-K2.6, GLM-5.1, MiniMax-M2.7 같은 최상위 대형 에이전트들은 skill 계층이 주어졌을 때 적극적으로 CLI를 채택해 최소한의 턴 수와 시간으로 태스크를 완수했습니다.

하지만 Qwen3-4B 같은 소형 모델의 경우, 새로 추가된 CLI 예제 코드들을 무작정 전부 읽어들이는 바람에 신규 소모 토큰이 무시무시하게 폭증하는 대참사가 일어났습니다.

심지어 정답률 향상도 전혀 없었습니다. Qwen3-14B 모델의 경우, 더욱 특이한 실패 양상을 보여주었습니다.

그 원인을 에이전트 트레이스 뷰어(Trace Viewer)를 통해 살펴보니 다음과 같았습니다. 에이전트가 Skill(문서 내용)을 읽고 이를 '자신이 직접 파라미터로 호출할 수 있는 도구'로 오인한 것입니다. 시스템에 등록되지도 않은 transformers(command="classify", ...) 형태의 에러 유발 도구를 호출하려 하거나, 마땅한 실행 도구를 찾지 못하자 수행이 불가능한 작업이라 단정 짓고 중간에 포기해 버리는 흐름이 발견되었습니다.

이것이 바로 저희가 이 벤치마킹 하네스를 구축한 이유입니다. 대형 모델을 편리하게 만드는 변경 사항이 소형 모델에서는 혼란을 자초하는 결과를 낳을 수 있다는 점을 눈으로 직접 확인한 것이죠. 라이브러리 메인테이너라면 반드시 에이전트용 API를 설계할 때 다양한 체급의 모델 환경을 모두 교차 평가해야 합니다.

직접 시도해보기

이 벤치마크 하네스는 단 하나의 CLI 도구인 agent-eval로 쉽게 동작시킬 수 있습니다. 설치하고 실행 스위트를 선언한 뒤, Hugging Face Jobs 환경에 모델과 버전 조합을 배포하고 결과를 Hugging Face Space 웹 페이지 형태의 보고서로 바로 뽑아볼 수 있어요.

⚠️ 보안 유의 사항 본 하네스는 코딩 에이전트가 시스템 권한 제약을 우회해 코드를 실행하는 구조이므로, 신뢰할 수 있는 로컬 환경 혹은 격리된 샌드박스에서만 실행해야 합니다. 내가 직접 작성하지 않은 외부 코드를 타겟으로 구동할 때는 반드시 보안 지침서(SECURITY.md)를 먼저 숙지해 주세요.

직접 여러분의 커스텀 라이브러리를 등록하고 몇 가지 태스크와 기대 정답을 기술해 보세요. 대형 언어 모델들이 여러분의 라이브러리를 마주했을 때 얼마나 헤매는지, 혹은 얼마나 매끄럽게 문제를 해결하는지 흥미로운 인사이트를 가득 얻으실 수 있을 것입니다.