Chuyển tới nội dung chính

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

Công cụ execute_code cho phép tác nhâ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 tiến trình con trên máy chủ đại lý, liên lạc với Hermes qua RPC ổ cắm tên miền Unix.

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

  1. Tác nhân viết tập lệnh Python bằng `from Hermes_tools import ...

  2. Hermes tạo mô-đun sơ khai Hermes_tools.py với các chức năng RPC

  3. Hermes mở ổ cắm tên miền Unix và khởi động chuỗi trình nghe RPC

  4. 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

  5. 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 bên trong tập lệnh:** 
`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

Đại lý 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ỉ đầu ra 
`print()
` cuối cùng mới quay lại, 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

``` python
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

`Python
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

`Python
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

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

`

## Chế độ thực thi``execute_code
` có hai chế độ thực thi được điều khiển bởi 
`code_execution.mode
` trong 

~/.Hermes/config.yaml

:

| Chế độ | Thư mục làm việc | Trình thông dịch Python |
|------|-------------------|----------------------|
| **
`project

`
** (mặc định) | Thư mục làm việc của phiên (giống như 
`terminal()

) | Trăn 
`VIRTUAL_ENV

/
`CONDA_PREFIX
` đang hoạt động, quay lại với con trăn của chính Hermes |
| 
`strict
` | Thư mục dàn dựng tạm thời được tách biệt khỏi dự án của người dùng |

sys.executable
` (con trăn của Hermes) |`**Khi nào nên để nó trên 
`project

:** bạn muốn 
`import pandas

, 
`from my_project import foo
` hoặc các đường dẫn tương đối như 
`open(".env")
` hoạt động giống như cách chúng hoạt động trong 
`terminal()

. Đây gần như luôn luôn là những gì bạn muốn.

**Khi nào chuyển sang 
`strict

:** bạn cần khả năng tái tạo tối đa — bạn muốn có cùng một trình thông dịch trong mọi phiên bất kể người dùng đã kích hoạt venv nào và bạn muốn cách ly các tập lệnh khỏi cây dự án (không có nguy cơ vô tình đọc các tệp dự án thông qua một đường dẫn tương đối).

``` yaml

# ~/.Hermes/config.yaml
code_execution:
  mode: project   # or "strict"

`
``Hành vi dự phòng trong chế độ 
`project

: nếu 
`VIRTUAL_ENV
` / 
`CONDA_PREFIX
` không được đặt, bị hỏng hoặc trỏ vào một Python cũ hơn 3,8, thì trình phân giải sẽ hoàn toàn quay trở lại 
`sys.executable
` — nó sẽ không bao giờ rời khỏi tác nhân nếu không có trình thông dịch đang hoạt động.

Các bất biến quan trọng về bảo mật giống hệt nhau trên cả hai chế độ:
- lọc môi trường (khóa API, mã thông báo, thông tin xác thực bị xóa)
- danh sách trắng công cụ (tập lệnh không thể gọi các công cụ 
`execute_code
` theo cách đệ quy, 
`delegate_task
` hoặc MCP)
- giới hạn tài nguyên (thời gian chờ, giới hạn xuất chuẩn, giới hạn lệnh gọi công cụ)

Chế độ chuyển đổi thay đổi nơi tập lệnh chạy và trình thông dịch nào chạy chúng, chứ không phải thông tin xác thực nào họ có thể xem hoặc công cụ nào họ có thể gọi.

## 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ể được cấu hình thông qua 
`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)

`

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

:
1. 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
2. Phụ huynh gửi đi thông qua trình xử lý 
`handle_function_call
` tiêu chuẩn
3. Kết quả được gửi lại qua socket
4. 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
` hoặc 
`pty

).## 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à tác 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ác nhâ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

:::danger[Security Model]
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 sẽ 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 tiến trình con 
`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ể liệt kê rõ ràng các biến trong 
`config.yaml

:

``` yaml
terminal:
  env_passthrough:

    - MY_CUSTOM_KEY
    - ANOTHER_TOKEN

`
``Xem [Security guide](/docs/user-guide/security#environment-variable-passthrough) để biết chi tiết đầy đủ.

Hermes luôn viết tập lệnh và sơ khai RPC 
`Hermes_tools.py
` được tạo tự động vào một thư mục dàn dựng tạm thời được dọn sạch sau khi thực thi. Trong chế độ 
`strict
` tập lệnh cũng *chạy* ở đó; ở chế độ 
`project

, nó chạy trong thư mục làm việc của phiên (thư mục dàn dựng vẫn nằm trên 
`PythonPATH
` nên quá trình nhập vẫn được giải quyết). 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](/docs/user-guide/security#environment-variable-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, bản dựng và quy trình shell.

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