코드 실행 (Programmatic Tool Calling)

execute_code 도구는 Hermes 도구 프로그래밍을 호출하는 에이전트가 Python 스크립트를 작성하고 단일 LLM 턴으로 멀티 스텝 워크플로를 동기화합니다. 스크립트는 에이전트 호스트에 아이 프로세스에서 실행되며, 유닉스 도메인 소켓 RPC에 Hermes와 공동 작업.

어떻게 작동하나요?

1. from hermes_tools import...를 사용하여 Python 스크립트를 작성합니다.
2. Hermes는 RPC 기능을 가진 hermes_tools.py stub 단위를 생성합니다
3. Hermes는 유닉스 도메인 소켓을 열고 RPC 리스너 나사를 시작합니다.
4. 스크립트는 아이 프로세스에서 실행 — 도구는 소켓을 통해 이동 Hermes
5. 스크립트의 print() 출력은 LLM으로 반환됩니다. 중간 도구 결과는 컨텍스트 창을 입력하지 않습니다.

# The agent can write scripts like:
from hermes_tools import web_search, web_extract

results = web_search("Python 3.13 features", limit=5)
for r in results["data"]["web"]:
    content = web_extract([r["url"]])
    #... filter and process...
print(summary)

스크립스 내부 도구: web_search, web_extract, read_file, write_file, search_files, patch, terminal (foreground only).

에이전트 사용시 으로

에이전트 사용 execute_code 거기 있을 때:

• 3+ 도구 호출 그 사이에 논리 처리
• 대량 데이터 필터링 또는 조건부 지칭
• 결과의 반복

주요 이점: 중간 공구 결과는 문맥 창을 결코 입력하지 않았습니다 — 마지막 print() 산출은, 극적으로 토큰 사용법을 감소시킵니다.

Practical 예제

데이터 처리 Pipeline

from hermes_tools import search_files, read_file
import json

# Find all config files and extract database settings
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))

Multi-Step 웹 연구

from hermes_tools import web_search, web_extract
import json

# Search, extract, and summarize in one turn
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))

대량 파일 Refactoring

from hermes_tools import search_files, read_file, patch

# Find all Python files using deprecated API and fix them
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")

구축 및 테스트 파이프라인

from hermes_tools import terminal, read_file
import json

# Run tests, parse results, and report
result = terminal("cd /project && python -m pytest --tb=short -q 2>&1", timeout=120)
output = result.get("output", "")

# Parse test output
passed = output.count(" passed")
failed = output.count(" failed")
errors = output.count(" error")

report = {
    "passed": passed,
    "failed": failed,
    "errors": errors,
    "exit_code": result.get("exit_code", -1),
    "summary": output[-500:] if len(output) > 500 else output
}

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

실행 모드

execute_code에는 code_execution.mode가 ~/.hermes/config.yaml에 의해 제어된 두 가지 실행 모드가 있습니다

주요 특징	작업 디렉토리	Python 해석기
project (기본값)	세션의 작업 디렉토리 (terminal()와 동일)	Active VIRTUAL_ENV / CONDA_PREFIX python, Hermes의 자신의 python에 다시 떨어지는
strict	사용자의 프로젝트에서 고립 된 임시 직원	sys.executable (Hermes의 자신의 python)

project: 당신은 import pandas, from my_project import foo, 또는 open(".env")와 같은 상대 경로가 terminal()에서 행하는 동일한 방법을 작동하려면. 이것은 당신이 원하는 거의 항상입니다.

strict: 당신은 최대 재현성이 필요합니다. 사용자는 활성화된 venv에 관계없이 모든 세션을 동일한 해석기를 원하고, 프로젝트 트리 (사실적인 경로를 통해 실수로 판독 프로젝트 파일의 위험)에서 분기된 스크립트를 원합니다.

# ~/.hermes/config.yaml
code_execution:
  mode: project   # or "strict"
``project` 모드의 Fallback 동작: `VIRTUAL_ENV` / `CONDA_PREFIX`가 설정되지 않은 경우, 끊어지거나, 또는 3.8 이상 파이썬에서 포인트는, 해결자는 `sys.executable`로 다시 깨끗하게 떨어졌다 — 작업 해석기 없이 에이전트를 결코 나타낸다.

Security-critical invariants는 두 가지 모드와 동일합니다

- 환경 스크럽 (API 키, 토큰, 자격 줄무늬)
- 도구 화이트리스트 (scripts can call `...` 반복적으로, `delegate_task` 또는 MCP 도구)
- 자원 제한 (timeout, stdout 모자, 도구 통화 캡)

스크립트가 실행되고 해석자가 실행되는 경우, 그들이 호출 할 수있는 도구 또는 볼 수 있는지 여부를 변경합니다.

## 자원 제한 \{#resource-limits}

| 회사연혁 | 지원하다 | 지원하다 |
|----------|-------|-------|
| **시간** | 5 분 (300s) | 스크립트는 SIGTERM과 함께 죽고, 5s 은혜 후 SIGKILL |
| **주택 ** | 50 KB | `[output truncated at ]` 공지로 출력 |
| **스터** | 10 KB | 디버깅을 위한 non-zero 출구에 출력 포함 |
| **도구 호출** | 실행 당 50 | 제한이 도달 할 때 오류가 반환됩니다 |

모든 제한은 `config.yaml`을 통해 구성할 수 있습니다

```yaml
# In ~/.hermes/config.yaml
code_execution:
  mode: project      # project (default) | strict
  timeout: 300       # Max seconds per script (default: 300)
  max_tool_calls: 50 # Max tool calls per execution (default: 50)

도구가 내부 스크립트를 호출하는 방법

스크립트가 같은 함수를 호출할 때 ...:

1. 호출은 JSON으로 일련되고 유닉스 도메인 소켓을 부모 프로세스로 보냈습니다
2. 표준 handle_function_call 핸들러를 통해 부모 파견
3. 결과는 소켓에 뒤에 보내집니다
4. 함수는 parsed 결과를 반환합니다

이 도구는 정상적인 도구 호출과 동일하게 동작한다 - 동일한 속도 제한, 동일한 오류 처리, 동일한 기능. 유일한 제한은 terminal()는 전경 전용입니다 (background 또는 pty 매개변수 없음).

오류 처리

스크립트가 실패하면, 에이전트는 구조 오류 정보를받습니다

• Non-zero 종료 코드: stderr는 출력에 포함되어 있으므로 에이전트는 전체 추적을 볼 수
• 시간: 스크립트가 죽고 에이전트가 "Script timed out after 300s and was killed."를 참조하십시오
• Interruption: 사용자가 실행 중에 새로운 메시지를 보낼 경우, 스크립트가 종료되고 에이전트는 [execution interrupted — user sent a new message]를 참조하십시오
• **Tool 통화 제한 **: 50call 제한이 히트되면, 이후 도구는 오류 메시지를 반환

응답은 항상 status (success/error/timeout/interrupted)를 포함합니다, output, tool_calls_made, duration_seconds.

보안 보안

Security Model

어린이 과정은 ** 소수 환경 **로 실행됩니다. API 키, 토큰 및 자격은 기본적으로 줄무늬입니다. RPC 채널을 통해 독점적으로 스크립트 액세스 도구 - 명시적으로 허용되지 않는 환경 변수에서 비밀을 읽을 수 없습니다.

환경 변수 포함 KEY, TOKEN, SECRET, PASSWORD, CREDENTIAL, PASSWD, 또는 AUTH는 제외됩니다. 안전한 시스템 변수만 (PATH, HOME, LANG, SHELL, PYTHONPATH, VIRTUAL_ENV 등)가 통과됩니다.

기술 환경 변수 Passthrough

기술을 선언할 때 required_environment_variables 의 frontmatter, 그 변수는** 자동으로 전달됩니다** 를 통해 execute_code 와 terminal 의 기술이 로드된 후. 이 기술은 임의 코드에 대한 보안 자세를 약화하지 않고 선언 된 API 키를 사용합니다.

non-skill 사용 사례의 경우 config.yaml의 변수를 명시적으로 허용할 수 있습니다

terminal:
  env_passthrough:
    - MY_CUSTOM_KEY
    - ANOTHER_TOKEN

Security guide 를 전체 세부 사항을 참조하세요.

Hermes는 실행할 스크립트와 자동 생성된 hermes_tools.py RPC 스텁을 임시 staging 디렉터리에 기록하고, 실행이 끝나면 정리합니다. strict 모드에서는 스크립트도 그 디렉터리에서 실행됩니다. project 모드에서는 세션의 작업 디렉터리에서 실행되며, staging 디렉터리는 PYTHONPATH에 남아 import가 계속 동작합니다. 자식 프로세스는 별도 프로세스 그룹에서 실행되므로 timeout이나 interrupt 때 깨끗하게 종료할 수 있습니다.

execute_code 대 터미널

사용 사례	execute_code	terminal
Multi-step 워크플로우와 도구 호출	✅	❌
간단한 쉘 명령	❌	✅
필터링/처리 대형 공구 출력	✅	❌
빌드 또는 테스트 스위트 실행	❌	✅
검색 결과에 대한 반복	✅	❌
Interactive/background 프로세스	❌	✅
환경의 API 키 필요	· passthrough를 통해서만	✅ (최대 패스)

기준: Hermes 도구를 프로그래밍 방식으로 호출하고 호출 사이에 로직이 필요하면 execute_code를 사용하세요. 셸 명령, 빌드, 장기 실행 프로세스는 terminal이 더 적합합니다.

플랫폼 지원

코드 실행은 Unix domain socket이 필요하므로 Linux와 macOS에서만 사용할 수 있습니다. Windows에서는 자동으로 비활성화되며, 에이전트는 일반적인 순차 도구 호출 방식으로 돌아갑니다.