튜토리얼 25: 코드 실행 | Easy Understand Hermes Agent

이 글은 Hermes Agent 공식 튜토리얼 시리즈의 일부입니다. 전체 튜토리얼 보기

케이크를 구울 때 재료를 하나씩 가져오는 대신, 레시피 전체를 적어서 조수에게 건네주고 완성된 케이크만 돌려받는 상황을 상상해 보세요. 바로 그게 Code Execution이 Hermes Agent에게 해주는 일입니다. 에이전트가 여러 도구를 내부에서 호출하는 전체 Python 스크립트를 실행하고, 최종 결과만 대화에 반환하는 방식이죠.

Code Execution이란?

일반적으로 Hermes가 웹 검색, 파일 읽기, 명령 실행을 할 때는 한 번에 하나씩 처리합니다. 그리고 그 중간 결과물들이 전부 “메모리”(컨텍스트 윈도우)에 쌓이죠. 이건 느리고 토큰 낭비도 심합니다.

execute_code 도구를 사용하면 Hermes는 Python 스크립트를 작성해서 web_search, read_file, patch 같은 도구들을 프로그래밍 방식으로 한 번에 호출할 수 있습니다. 스크립트는 별도의 자식 프로세스에서 실행되고, print() 출력만 에이전트에게 돌아옵니다. 지저분한 중간 데이터는 전부 숨겨지는 거죠.

작동 방식: 단계별로 살펴보기

1단계: 에이전트가 Python 스크립트 작성
특별한 모듈에서 도구를 임포트하는 것부터 시작합니다:

from hermes_tools import web_search, web_extract

2단계: Hermes가 헬퍼 모듈 생성
스크립트를 메인 에이전트에 연결해 주는 hermes_tools.py 스텁을 자동으로 생성합니다.

3단계: 통신 채널 개설
Hermes는 Unix 도메인 소켓(프로세스 간 빠른 로컬 “전화선”)을 열고 리스너 스레드를 시작합니다.

4단계: 스크립트가 자식 프로세스에서 실행
스크립트 안의 모든 도구 호출은 그 소켓을 통해 Hermes로 전달되고, Hermes가 실행한 뒤 결과를 다시 보내줍니다.

5단계: print 출력만 반환
스크립트의 print() 문이 LLM이 볼 수 있는 유일한 결과물입니다. 모든 중간 도구 결과는 컨텍스트 윈도우에 들어오지 않아서 엄청난 양의 토큰을 절약할 수 있습니다.

Hermes는 언제 이 기능을 사용할까?

에이전트는 다음과 같은 상황을 감지하면 자동으로 execute_code를 선택합니다:

로직이 포함된 3회 이상의 도구 호출 (필터링이나 비교 같은 작업)
대량 데이터 처리 — 예: 여러 파일을 검색해서 스니펫 추출
반복문 — 여러 항목에 동일한 작업 반복

가장 큰 장점? 토큰 효율성입니다. 모든 검색 결과를 대화에 집어넣는 대신, 최종 요약만 통과하니까요.

직접 시도해 볼 수 있는 실용 예제

1. 데이터 처리 파이프라인

from hermes_tools import search_files, read_file
import json

# 모든 설정 파일을 찾아 데이터베이스 설정 추출
matches = search_files("database", path=".", file_glob="*.yaml", limit=20)
configs = []
for match in matches.get("matches", []):
    content = read_file(match["path"])
    configs.append({"file": match["path"], "preview": content["content"][:200]})

print(json.dumps(configs, indent=2))

2. 다단계 웹 리서치

from hermes_tools import web_search, web_extract
import json

results = web_search("Rust async runtime comparison 2025", limit=5)
summaries = []
for r in results["data"]["web"]:
    page = web_extract([r["url"]])
    for p in page.get("results", []):
        if p.get("content"):
            summaries.append({
                "title": r["title"],
                "url": r["url"],
                "excerpt": p["content"][:500]
            })

print(json.dumps(summaries, indent=2))

3. 대량 파일 리팩토링

from hermes_tools import search_files, read_file, patch

matches = search_files("old_api_call", path="src/", file_glob="*.py")
fixed = 0
for match in matches.get("matches", []):
    result = patch(
        path=match["path"],
        old_string="old_api_call(",
        new_string="new_api_call(",
        replace_all=True
    )
    if "error" not in str(result):
        fixed += 1

print(f"Fixed {fixed} files out of {len(matches.get('matches', []))} matches")

4. 빌드 및 테스트 파이프라인

from hermes_tools import terminal
import json

result = terminal("cd /project && python -m pytest --tb=short -q 2>&1", timeout=120)
output = result.get("output", "")

passed = output.count(" passed")
failed = output.count(" failed")

print(json.dumps({"passed": passed, "failed": failed}, indent=2))

꼭 기억해야 할 핵심 포인트

스크립트에서 사용 가능한 도구: web_search, web_extract, read_file, write_file, search_files, patch, terminal (포그라운드 전용).
print() 출력만 반환됨 — 나머지는 전부 숨겨집니다.
반복문, 필터링, 다단계 워크플로우에 최적 — Hermes에게 미니 프로그래밍 환경을 제공하는 셈입니다.

요약

Code Execution은 Hermes를 단계별 어시스턴트에서 일괄 처리 프로세서로 바꿔줍니다. 스크립트를 작성하고 실행한 뒤 최종 답변만 돌려주는 방식으로 시간, 토큰, 인지 부하를 모두 절약하죠. Hermes가 반복적인 도구 호출을 많이 하는 걸 본다면, 아마 내부적으로 이 기능을 사용하고 있는 겁니다.

다음 편: 튜토리얼 26 — 배치 처리: 수백 개의 프롬프트를 병렬로 실행하기.