하네스, 직접 만들어야 할까요? 대부분은 빌려 쓰면 돼요

AI 에이전트 이야기를 하다 보면 하네스라는 말이 자주 나와요. "우리도 하네스를 구축해야 하나?" 싶은데, 결론부터 말하면 대부분은 직접 만들 필요가 없어요. 이미 있는 걸 빌려 쓰면 돼요.

하네스가 뭐예요

하네스(harness)는 원래 말에 채우는 마구예요. AI에서는 모델을 감싸서 실제로 일하게 만드는 바깥 장치를 말해요. 모델은 글을 읽고 다음에 할 말을 정할 뿐, 혼자서는 파일을 열거나 명령을 실행하지 못하거든요.

하네스가 하는 일은 이래요.

• 반복: 모델이 "이 파일 읽어줘"라고 하면 대신 실행하고, 결과를 다시 모델에게 줘요. 일이 끝날 때까지 이걸 되풀이해요
• 도구: 파일 읽기, 명령 실행, 검색 같은 손발을 달아줘요
• 권한: 무엇을 허락 없이 해도 되는지 정해요
• 기억 정리: 대화가 길어지면 앞부분을 줄여요
• 멈춤: 몇 번까지 돌지, 언제 그만둘지 정해요

Claude Code가 바로 이런 하네스예요. Anthropic 문서도 Managed Agents를 "agent harness"라고 불러요.

고를 수 있는 다섯 가지

Anthropic 공식 문서의 비교표에 "하네스가 아예 필요 없는 경우"를 더해 정리했어요.

바이브데일리는 이렇게 써요

• 질문 봇: 기사 내용을 찾아 붙인 뒤 API를 한 번 불러요. 도구를 여러 번 쓸 일이 없어서 하네스가 필요 없었어요. 질문 한 번에 약 12원이에요 (만든 과정)
• 매일 아침 기사 작성: 클라우드에서 도는 Claude Code에 맡겨요. 하네스를 만들지 않고 빌려 쓰는 셈이에요

25줄로 하네스를 빌려봤어요

Agent SDK(파이썬, 0.2.165)로 스킬 기사에서 만든 원화 검사 스킬을 그대로 불러봤어요. 설치는 pip install claude-agent-sdk예요.

import anyio
from claude_agent_sdk import (
    query, ClaudeAgentOptions,
    ResultMessage)
 
opts = ClaudeAgentOptions(
    cwd="work",
    model="sonnet",
    allowed_tools=[
        "Read", "Skill",
        "Bash(python3 *)"],
    max_turns=6,
)
 
async def main():
    async for m in query(
        prompt="draft.md 검토해줘",
        options=opts,
    ):
        if type(m) is ResultMessage:
            print(m.result)
            print(m.num_turns)
            print(m.total_cost_usd)
 
anyio.run(main)

두 번 돌려서 두 번 다 원화가 빠진 3곳을 찾았어요. 한 번에 10–16초, 약 36원이었어요. 반복, 도구, 권한은 SDK가 다 맡고, 저는 허락할 도구와 최대 횟수만 정했어요.

하나 걸린 게 있어요. 처음엔 "Bash(python3 *)" 없이 돌렸더니, 스킬 안의 스크립트 실행이 막혀서 AI가 직접 읽고 답했어요. Claude Code에선 스킬 쪽 허락만으로 돌았던 스크립트라, SDK에선 허락 목록을 따로 챙겨야 해요.

직접 만들어야 할 때

여러 회사 모델을 한 반복 안에서 섞어야 하거나, 도구를 아주 특수한 환경에서 돌려야 할 때예요. 그땐 이걸 다 직접 챙겨야 해요.

• 무한 반복을 막는 최대 횟수와 비용 상한
• 위험한 명령 차단과 비밀 값 보호
• 대화가 길어졌을 때 정리하는 방법
• 무슨 일을 했는지 남기는 기록

이걸 다 만드는 게 곧 하네스를 구축하는 거예요. 시작은 빌려 쓰고, 정말 모자랄 때 만들어도 늦지 않아요. OpenAI, 구글 같은 다른 회사도 비슷한 에이전트 도구를 내놓고 있어요.

짚어둘 것

• 25줄 예시와 시간·값은 제가 직접 돌린 결과예요. 값은 Claude Code가 집계한 값이고, 환율은 1달러 1,400원 기준이에요
• 비교표와 Managed Agents가 베타라는 점은 Anthropic 공식 문서 기준이에요. Managed Agents는 이번에 직접 써보진 않았어요
• Agent SDK로 만든 서비스는 claude.ai 로그인이 아니라 API 키로 써야 한다고 공식 문서에 적혀 있어요

여러분은 AI를 어디까지 직접 만들어 쓰고 있어요? 카톡 오픈채팅 ⚡ AI랑 코딩하는 사람들에서 이야기 나눠요.

참고

• Claude Code — Agent SDK overview
• Claude — Managed Agents overview