Thêm công cụ

Trước khi viết một công cụ, hãy tự hỏi: thay vào đó, đây có phải là skill không?

Built-in Core Tools Only

Trang này dùng để thêm công cụ Hermes tích hợp vào chính kho lưu trữ. Nếu bạn muốn một công cụ cá nhân, dự án cục bộ hoặc công cụ tùy chỉnh khác mà không cần sửa đổi lõi Hermes, thay vào đó hãy sử dụng lộ trình plugin:

Mặc định là plugin để tạo hầu hết các công cụ tùy chỉnh. Chỉ theo dõi trang này khi bạn rõ ràng muốn gửi một công cụ tích hợp mới trong tools/ và `toolsets.py

Biến nó thành Kỹ năng khi khả năng có thể được thể hiện dưới dạng hướng dẫn + lệnh shell + công cụ hiện có (tìm kiếm arXiv, quy trình làm việc git, quản lý Docker, xử lý PDF).

Biến nó thành Công cụ khi nó yêu cầu tích hợp từ đầu đến cuối với khóa API, logic xử lý tùy chỉnh, xử lý dữ liệu nhị phân hoặc phát trực tuyến (tự động hóa trình duyệt, TTS, phân tích tầm nhìn).

Tổng quan

Thêm công cụ chạm vào 2 tệp:

** `tools/your_tool.py

** — trình xử lý, lược đồ, hàm kiểm tra, lệnh gọi `registry.register()

** `toolsets.py

** — thêm tên công cụ vào _Hermes_CORE_TOOLS (hoặc một bộ công cụ cụ thể)

Bất kỳ tệp tools/*.py nào có lệnh gọi registry.register() cấp cao nhất đều được tự động phát hiện khi khởi động - không yêu cầu danh sách nhập thủ công.

Bước 1: Tạo File công cụ tích hợp

Mọi tệp công cụ đều tuân theo cùng một cấu trúc:

# tools/weather_tool.py
"""Weather Tool -- look up current weather for a location."""`import JSON
 import os
 import logging`logger = logging.getLogger(__name__)

# --- Availability check ---

def check_weather_requirements() -> bool:
    """Return True if the tool's dependencies are available."""
    return bool(os.getenv("WEATHER_API_KEY"))

# --- Handler ---

def weather_tool(location: str, units: str = "metric") -> str:
    """Fetch weather for a location. Returns JSON string."""
    API_key = os.getenv("WEATHER_API_KEY")
    if not API_key:
        return JSON.dumps(\&#123;"error": "WEATHER_API_KEY not configured"&#125;)
    try:
        # ... call weather API ...
        return JSON.dumps(\&#123;"location": location, "temp": 22, "units": units&#125;)
    except Exception as e:
        return JSON.dumps(\&#123;"error": str(e)&#125;)

# --- Schema ---

WEATHER_SCHEMA = &#123;
    "name": "weather",
    "description": "Get current weather for a location.",
    "parameters": &#123;
        "type": "object",
        "properties": &#123;
            "location": &#123;
                "type": "string",
                "description": "City name or coordinates (e.g. 'London' or '51.5,-0.1')"
            &#125;,
            "units": &#123;
                "type": "string",
                "enum": ["metric", "imperial"],
                "description": "Temperature units (default: metric)",
                "default": "metric"
            &#125;
        &#125;,
        "required": ["location"]
    &#125;
&#125;

# --- Registration ---

from tools.registry import registry`registry.register(
    name="weather",
    toolset="weather",
    schema=WEATHER_SCHEMA,
    handler=lambda args, **kw: weather_tool(
        location=args.get("location", ""),
        units=args.get("units", "metric")),
    check_fn=check_weather_requirements,
    requires_env=["WEATHER_API_KEY"],
)

`

### Quy tắc chính

:::danger[Important]
- Trình xử lý **PHẢI** trả về chuỗi JSON (thông qua 
`JSON.dumps()

), không bao giờ là ký tự thô
- Các lỗi **PHẢI** được trả về dưới dạng 

\&#123;"error": "message"&#125;

, không bao giờ được đưa ra dưới dạng ngoại lệ
- 
`check_fn
` được gọi khi xây dựng định nghĩa công cụ - nếu nó trả về 
`False

, công cụ này sẽ bị loại trừ một cách âm thầm
- 
`handler
` nhận 

(args: dict, **kwargs)
` trong đó 
`args
` là đối số lệnh gọi công cụ của LLM
:::

## Bước 2: Thêm Công cụ tích hợp vào Bộ công cụ

Trong 
`toolsets.py

, thêm tên công cụ:

``` python

# If it should be available on all platforms (CLI + messaging):
_Hermes_CORE_TOOLS = [
    ...
    "weather",  # &lt;-- add here
]

# Or create a new standalone toolset:
"weather": &#123;
    "description": "Weather lookup tools",
    "tools": ["weather"],
    "includes": []
&#125;,

`

## ~~Bước 3: Thêm Discovery Import~~ (Không cần thiết nữa)

Các mô-đun công cụ có lệnh gọi 
`registry.register()
` cấp cao nhất được 
`discover_builtin_tools()
` tự động phát hiện trong 
`tools/registry.py

. Không cần duy trì danh sách nhập thủ công — chỉ cần tạo tệp của bạn trong 
`tools/
` và tệp sẽ được chọn khi khởi động.

## Trình xử lý không đồng bộ

Nếu trình xử lý của bạn cần mã không đồng bộ, hãy đánh dấu mã đó bằng 
`is_async=True

:

``` python
async def weather_tool_async(location: str) -> str:
    async with aiohttp.CLIentSession() as session:
        ...
    return JSON.dumps(result)

registry.register(
    name="weather",
    toolset="weather",
    schema=WEATHER_SCHEMA,
    handler=lambda args, **kw: weather_tool_async(args.get("location", "")),
    check_fn=check_weather_requirements,
    is_async=True,  # registry calls _run_async() automatically
)

`
``Cơ quan đăng ký xử lý việc bắc cầu không đồng bộ một cách minh bạch — bạn không bao giờ tự mình gọi 
`asyncio.run()

.

## Trình xử lý cần task_id

Các công cụ quản lý trạng thái mỗi phiên nhận 
`task_id
` qua 

`
**kwargs

:

``` python
def _handle_weather(args, **kw):
    task_id = kw.get("task_id")
    return weather_tool(args.get("location", ""), task_id=task_id)

registry.register(
    name="weather",
    ...
    handler=_handle_weather,
)

`

## Công cụ chặn vòng lặp tác nhân

Một số công cụ (
`todo

, 
`memory

, 
`session_search

, 
`delegate_task

) cần quyền truy cập vào trạng thái tác nhân mỗi phiên. Chúng bị 
`run_agent.py
` chặn trước khi đến cơ quan đăng ký. Cơ quan đăng ký vẫn giữ các lược đồ của chúng, nhưng 
`dispatch()
` trả về lỗi dự phòng nếu việc chặn bị bỏ qua.

## Tùy chọn: Tích hợp trình hướng dẫn cài đặt

Nếu công cụ của bạn yêu cầu khóa API, hãy thêm nó vào 
`Hermes_CLI/config.py

:

`Python
OPTIONAL_ENV_VARS = &#123;
    ...
    "WEATHER_API_KEY": &#123;
        "description": "Weather API key for weather lookup",
        "prompt": "Weather API key",
        "url": "https://weatherAPI.com/",
        "tools": ["weather"],
        "password": True,
    &#125;,
&#125;

`

## Danh sách kiểm tra
- [ ] Tệp công cụ được tạo bằng trình xử lý, lược đồ, chức năng kiểm tra và đăng ký

- [ ] Đã thêm vào bộ công cụ thích hợp trong 
`toolsets.py

- [ ] Đã xác nhận rằng đây thực sự phải là một công cụ cốt lõi/tích hợp sẵn chứ không phải một plugin
- [] Trình xử lý trả về chuỗi JSON, lỗi trả về dưới dạng 

\&#123;"error": "..."&#125;

- [ ] Tùy chọn: Khóa API được thêm vào 
`OPTIONAL_ENV_VARS
` trong 
`Hermes_CLI/config.py

- [ ] Tùy chọn: Đã thêm vào 
`toolset_distributions.py
` để xử lý hàng loạt
- [ ] Đã thử nghiệm với 
`Hermes chat -q "Use the weather tool for London"
`

Tổng quan​

Bước 1: Tạo File công cụ tích hợp​

Tổng quan

Bước 1: Tạo File công cụ tích hợp