Thực thi mã (Gọi công cụ lập trình)

Công cụ execute_code cho phép tổng đài viên viết các tập lệnh Python gọi các công cụ Hermes theo chương trình, thu gọn quy trình làm việc nhiều bước thành một lượt LLM duy nhất. Tập lệnh chạy trong một quy trình con được đóng hộp cát trên máy chủ tác nhân, giao tiếp qua RPC ổ cắm tên miền Unix.

Nó hoạt động như thế nào

Tác nhân viết tập lệnh Python bằng from hermes_tools import ...
Hermes tạo mô-đun sơ khai hermes_tools.py với các chức năng RPC
Hermes mở ổ cắm tên miền Unix và khởi động chuỗi trình nghe RPC
Tập lệnh chạy trong một tiến trình con — các lệnh gọi công cụ sẽ di chuyển qua socket trở lại Hermes
Chỉ đầu ra print() của tập lệnh được trả về LLM; kết quả công cụ trung gian không bao giờ vào cửa sổ ngữ cảnh

# 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)

Các công cụ có sẵn trong hộp cát: web_search , web_extract , read_file , write_file , search_files , patch , terminal (chỉ ở nền trước).

Khi đại lý sử dụng cái này

Tác nhân sử dụng execute_code khi có:

3+ lệnh gọi công cụ với logic xử lý giữa chúng
Lọc dữ liệu hàng loạt hoặc phân nhánh có điều kiện
Vòng lặp kết quả

Lợi ích chính: kết quả của công cụ trung gian không bao giờ nhập vào cửa sổ ngữ cảnh — chỉ kết quả đầu ra print() cuối cùng quay lại, làm giảm đáng kể việc sử dụng mã thông báo.

Ví dụ thực tế

Đường ống xử lý dữ liệu

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))

Nghiên cứu web nhiều bước

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))

Tái cấu trúc tệp hàng loạt

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")

Xây dựng và thử nghiệm đường ống

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))

Giới hạn tài nguyên

Tài nguyên	Giới hạn	Ghi chú
Hết thời gian	5 phút (300 giây)	Tập lệnh bị tắt bằng SIGTERM, sau đó là SIGKILL sau 5 giây
Standout	50 KB	Đầu ra bị cắt bớt với thông báo `[output truncated at 50KB]`
Stderr	10 KB	Được bao gồm trong đầu ra khi thoát khác 0 để gỡ lỗi
Cuộc gọi công cụ	50 mỗi lần thực hiện	Lỗi trả về khi đạt đến giới hạn

Tất cả các giới hạn đều có thể định cấu hình thông qua config.yaml :

# In ~/.hermes/config.yaml
code_execution:
  timeout: 300       

# Max seconds per script (default: 300)
  max_tool_calls: 50 

# Max tool calls per execution (default: 50)

Cách gọi công cụ hoạt động bên trong tập lệnh

Khi tập lệnh của bạn gọi một hàm như web_search("query") :

Cuộc gọi được tuần tự hóa thành JSON và được gửi qua ổ cắm tên miền Unix tới quy trình gốc
Cha mẹ gửi đi thông qua trình xử lý handle_function_call tiêu chuẩn
Kết quả được gửi lại qua socket
Hàm trả về kết quả đã phân tích

Điều này có nghĩa là lệnh gọi công cụ bên trong tập lệnh hoạt động giống hệt với lệnh gọi công cụ thông thường — cùng giới hạn tốc độ, xử lý lỗi giống nhau, khả năng giống nhau. Hạn chế duy nhất là terminal() chỉ ở nền trước (không có tham số background , pty hoặc check_interval ).

Xử lý lỗi

Khi tập lệnh bị lỗi, tác nhân sẽ nhận được thông tin lỗi có cấu trúc:- Mã thoát khác 0: stderr được bao gồm trong đầu ra để tác nhân nhìn thấy toàn bộ dấu vết

Hết thời gian: Tập lệnh bị hủy và nhân viên hỗ trợ nhìn thấy "Script timed out after 300s and was killed."
Gián đoạn: Nếu người dùng gửi tin nhắn mới trong khi thực thi, tập lệnh sẽ bị chấm dứt và tổng đài viên sẽ thấy [execution interrupted — user sent a new message]
Giới hạn lệnh gọi công cụ: Khi đạt đến giới hạn 50 lệnh gọi, các lệnh gọi công cụ tiếp theo sẽ trả về thông báo lỗi

Phản hồi luôn bao gồm status (thành công/lỗi/hết thời gian/bị gián đoạn), output , tool_calls_made và duration_seconds .

Bảo mật

:::mô hình bảo mật nguy hiểm Tiến trình con chạy trong môi trường tối thiểu. Khóa API, mã thông báo và thông tin xác thực bị loại bỏ theo mặc định. Tập lệnh truy cập các công cụ độc quyền thông qua kênh RPC - nó không thể đọc các bí mật từ các biến môi trường trừ khi được cho phép rõ ràng.

:::

Các biến môi trường chứa KEY , TOKEN , SECRET , PASSWORD , CREDENTIAL , PASSWD hoặc AUTH trong tên của chúng đều bị loại trừ. Chỉ các biến hệ thống an toàn ( PATH , HOME , LANG , SHELL , PYTHONPATH , VIRTUAL_ENV , v.v.) mới được chuyển qua.

Truyền qua biến môi trường kỹ năng

Khi một kỹ năng khai báo required_environment_variables trong phần đầu của nó, các biến đó sẽ tự động được chuyển qua tới cả hai hộp cát execute_code và terminal sau khi kỹ năng được tải. Điều này cho phép các kỹ năng sử dụng khóa API đã khai báo mà không làm suy yếu mức độ bảo mật đối với mã tùy ý.

Đối với các trường hợp sử dụng không cần kỹ năng, bạn có thể đưa các biến vào danh sách cho phép một cách rõ ràng trong config.yaml :

terminal:
  env_passthrough:
    - MY_CUSTOM_KEY
    - ANOTHER_TOKEN

Xem Hướng dẫn bảo mật để biết chi tiết đầy đủ.

Tập lệnh chạy trong một thư mục tạm thời được dọn sạch sau khi thực thi. Quá trình con chạy trong nhóm quy trình riêng của nó nên nó có thể bị tiêu diệt hoàn toàn khi hết thời gian chờ hoặc bị gián đoạn.

mã thực thi so với terminal

Trường hợp sử dụng	thực thi_code	terminal
Quy trình công việc gồm nhiều bước với các lệnh gọi công cụ giữa	✅	❌
Lệnh shell đơn giản	❌	✅
Lọc/xử lý đầu ra công cụ lớn	✅	❌
Chạy bộ xây dựng hoặc thử nghiệm	❌	✅
Lặp lại kết quả tìm kiếm	✅	❌
Quá trình tương tác/nền	❌	✅
Cần khóa API trong môi trường	⚠️ Chỉ qua passthrough	✅ (đi qua nhiều nhất)

Quy tắc chung: Sử dụng execute_code khi bạn cần gọi các công cụ Hermes theo lập trình với tính logic giữa các lệnh gọi. Sử dụng terminal để chạy các lệnh shell, bản dựng và quy trình.

Hỗ trợ nền tảng

Việc thực thi mã yêu cầu ổ cắm miền Unix và chỉ khả dụng trên Linux và macOS. Nó tự động bị vô hiệu hóa trên Windows - tác nhân quay trở lại các lệnh gọi công cụ tuần tự thông thường.