[Hermes] Module 6: Tools & MCP Servers

I. Mục tiêu bài học

Sau khi hoàn thành module này, bạn sẽ có thể:

  • Phân biệt được ba khái niệm: Skills, Tools và MCP Servers.
  • Hiểu cấu trúc của một tool trong Hermes: hàm Python, schema mô tả và cơ chế đăng ký.
  • Kiểm soát bề mặt tool bằng tool sets, chế độ an toàn (safe mode) và sandboxing.
  • Kết nối Hermes với MCP Server bên ngoài (ví dụ: Blender) để mở rộng khả năng.
  • Xuất Hermes như một MCP Server để các ứng dụng khác (VS Code) có thể gọi.
  • Tự viết một tool tùy chỉnh (lấy giá cổ phiếu từ Finnhub) và đăng ký vào Hermes.
  • Video link: https://www.youtube.com/watch?v=U140gP-1bEI

II. Nội dung chính

1. Tool là gì? Vai trò của Tool trong Agent

“Mô hình không có tool chỉ là chatbot văn bản. Tool là đôi tay của agent.”

  • Tool là một hàm Python có thể gọi được, cho phép agent thực hiện hành động thực tế: đọc/ghi file, gọi API, duyệt web, điều khiển trình duyệt, phân tích ảnh, v.v.

  • Ba thành phần của một tool:

    1. Hàm xử lý (Handler): mã Python thực hiện công việc cụ thể.
    2. Mô tả và schema: được mô hình (LLM) đọc để quyết định khi nào gọi tool. Schema định nghĩa tên, tham số, kiểu dữ liệu.
    3. Đăng ký (Registry): liên kết schema và handler để Hermes biết đến tool.
  • Luồng gọi tool:

    • LLM phát sinh một yêu cầu có cấu trúc: { "tool_name": "...", "arguments": {...} }.
    • Hermes nhận yêu cầu, gọi hàm handler tương ứng.
    • Hàm trả về kết quả (chuỗi JSON) và đưa vào ngữ cảnh.
    • LLM đọc kết quả và quyết định bước tiếp theo.

Lưu ý quan trọng: Tool thất bại không được làm sập toàn bộ lượt gọi. Handler nên trả về thông báo lỗi rõ ràng để LLM có thể phục hồi hoặc chọn tool khác.


2. Phân biệt Skills – Tools – MCP Servers

Thành phần Định nghĩa Ví dụ
Skills Hướng dẫn, quy trình làm việc (workflow) mà agent có thể tải từ file SKILL.md “Cách viết báo cáo theo phong cách công ty”
Tools Hàm Python có thể gọi, thực thi mã thực tế read_file, web_search, stock_price
MCP Servers Lớp kết nối (adapter) giúp Hermes giao tiếp với hệ thống bên ngoài qua STDIO hoặc HTTP mà không cần sửa mã nguồn lõi Blender, Stripe, Linear, Notion
  • Khi nào dùng gì?
    • Nếu chỉ cần hướng dẫn → Skills.
    • Nếu cần chức năng mới, có thể viết mã Python → Tool.
    • Nếu muốn tích hợp dịch vụ bên thứ ba mà không viết lại core → MCP Server.

3. Bộ công cụ có sẵn (Built-in Tool Catalog)

Hermes đi kèm khoảng 70 tools, được tổ chức thành ~30 tool sets (bộ công cụ). Mỗi tool set là một nhóm logic:

  • Core tool sets: File, Terminal, Web, Vision, Media, Orchestration, Memory.
  • Composite tool sets: Kết hợp nhiều tool set cho tình huống cụ thể (vd: debugging bao gồm file, terminal, web).
  • Platform tool sets: Cấu hình theo nền tảng (CLI, IDE, ACP).
  • Dynamic tool sets: Được tạo khi chạy (MCP server, plugin).

Tool có cấu trúc rõ ràng – Hermes cung cấp các tool như read_file, search_files, patch thay vì bắt agent dùng shell (cat, grep, sed) để tăng độ an toàn và dễ phục hồi.


4. Kiểm soát bề mặt tool (Scoping & Sandboxing)

Scoping – hạn chế những tool mà agent có thể dùng:

  • Tại CLI: hermes chat --tool-sets web (chỉ bật web).
  • Trong TUI: dùng lệnh /tools để liệt kê, bật/tắt tool.
  • Trong Web Dashboard: bật/tắt và cấu hình từng tool set.
  • Trong file cấu hình: thiết lập tool sets mặc định cho profile.

Safe mode (Tool set safe): chỉ cho phép các thao tác đọc (web search, web extract, phân tích ảnh, sinh ảnh) – không ghi file, không terminal, không thực thi mã. Thích hợp cho môi trường không tin cậy hoặc công khai.

Sandboxing – nơi thực thi:

  • Local (máy tính của bạn).
  • Docker (thiết lập trong module 2).
  • SSH/VPS (dùng Tailscale để kết nối).
  • Mỗi backend đảm bảo các tool chạy trong môi trường cô lập.

Approval gates: các mô hình phụ trợ (auxiliary models) phân loại hành động rủi ro và yêu cầu xác nhận trước khi thực thi tool.


5. Sử dụng MCP Server (Hermes là MCP Client)

MCP (Model Context Protocol) là giao thức cho phép kết nối không cần sửa mã nguồn.

  • Hai kiểu kết nối:

    • STDIO: chạy tiến trình con cục bộ (ví dụ: uvx blender-mcp).
    • HTTP: gọi endpoint từ xa (ví dụ: Stripe với bearer token).
  • Cách thêm MCP Server:

    • Dùng lệnh hermes mcp install <tên> hoặc qua Web Dashboard.
    • Cấu hình trong config.yaml với các tham số command, arguments, endpoint.
    • Sau khi thêm, các tool từ MCP Server được đăng ký vào registry với tiền tố mcp_<tên_server>.
  • Lọc tool của MCP Server: dùng include / exclude trong config để chỉ cho phép một số tool nhất định.

  • Bảo mật:

    • OAuth 2.1 PKCE cho HTTP servers – token được làm mới tự động, không lưu bí mật lâu dài.
    • Quét malware trước khi chạy npx hoặc uvx – Hermes kiểm tra api.osv.dev để chặn các gói đã biết là độc hại.

Ví dụ minh họa: Kết nối Hermes với Blender MCP Server.

  • Cài đặt server: uvx blender-mcp.
  • Kích hoạt add-on Blender.
  • Tạo mô hình 3D “Hermes Tower” chỉ bằng lời nhắc.
  • Blender MCP cung cấp 22 tool (get scene info, execute Blender code, download Poly Haven asset, …).

6. Xuất Hermes thành MCP Server

Hermes cũng có thể đóng vai trò là server MCP, cung cấp các tool cho client bên ngoài.

  • Lệnh: hermes mcp serve → khởi động server STDIO dùng FastMCP.
  • Exposes 10 tools liên quan đến hội thoại và tin nhắn (danh sách cuộc trò chuyện, lấy nội dung, gửi tin nhắn, v.v.).
  • Ứng dụng: tích hợp với VS Code GitHub Copilot – bạn có thể gọi các tool của Hermes ngay trong IDE.

7. Hướng dẫn tạo tool tùy chỉnh

Mục tiêu: Tạo tool lấy giá cổ phiếu hiện tại từ Finnhub.

Các bước thực hiện:

  1. Viết handler (hàm Python):

    • Sử dụng thư viện Finnhub (cần API key).
    • Hàm nhận tham số ticker (mã chứng khoán), trả về giá hiện tại.
  2. Định nghĩa schema:

    • Tên tool: stock_price
    • Mô tả: “Get the latest stock quote for a public company ticker using Finnhub.”
    • Tham số: ticker (string, bắt buộc).
  3. Đăng ký tool:

    • Dùng registry.register để liên kết schema và handler.
    • Thêm vào danh sách tool sets trong tool_sets.py.
  4. Sử dụng: Sau khi cấu hình, bạn có thể hỏi Hermes: “Giá Nvidia hiện tại là bao nhiêu?” và tool sẽ được gọi tự động.

Ví dụ code (rút gọn):

from tools.registry import registry

def stock_price_handler(ticker: str) -> str:
    # Gọi Finnhub API, xử lý lỗi
    return {"symbol": ticker, "price": 123.45}

stock_price_schema = {
    "name": "stock_price",
    "description": "Get latest stock quote for a ticker using Finnhub",
    "parameters": {
        "type": "object",
        "properties": {
            "ticker": {"type": "string", "description": "Stock symbol"}
        },
        "required": ["ticker"]
    }
}

registry.register(stock_price_schema, stock_price_handler)

III. Bảng tổng hợp các lệnh và giao diện điều khiển

Hành động Lệnh / Vị trí
Chạy chat với tool set cụ thể hermes chat --tool-sets web
Liệt kê tool sets đang bật /tool sets (trong TUI)
Bật/tắt tool trong TUI /tools enable <tên_tool>
Quản lý MCP Server hermes mcp install/list/remove
Khởi chạy Hermes MCP Server hermes mcp serve
Cấu hình tool sets trong dashboard Mục Skills → Tool Sets
Cấu hình MCP trong dashboard Mục MCP → Add Server

IV. Bài tập thực hành

  1. Bật chế độ Safe và yêu cầu Hermes viết một file progress.md. Quan sát phản hồi và giải thích vì sao không thể ghi file.

  2. Thêm MCP Server Blender (nếu có Blender) và yêu cầu tạo một vật thể 3D đơn giản (hình cầu, khối lập phương) bằng lời nhắc.

  3. Viết tool tùy chỉnh khác, ví dụ: lấy tỷ giá hối đoái từ API miễn phí (ExchangeRate-API) và đăng ký vào Hermes.

  4. Xuất Hermes MCP Server và kết nối với VS Code Copilot, thử liệt kê các cuộc trò chuyện hiện có.


V. Câu hỏi ôn tập

  1. Sự khác nhau cơ bản giữa Skill, Tool và MCP Server là gì? Cho ví dụ.
  2. Tại sao Hermes cung cấp các tool có cấu trúc như read_file thay vì để agent dùng shell?
  3. Làm thế nào để hạn chế một MCP Server chỉ sử dụng một số tool nhất định?
  4. Khi nào nên sử dụng tool set safe?
  5. Mô tả luồng gọi một tool từ lúc LLM yêu cầu đến khi kết quả được trả về.
  6. Hai kiểu vận chuyển (transport) của MCP Server là gì? Nêu ưu/nhược điểm của mỗi kiểu.
  7. Làm thế nào để bảo vệ khóa API khi cấu hình MCP Server HTTP?

VI. Tổng kết

Module 6 đã trang bị cho bạn kiến thức toàn diện về lớp Tools & MCP Servers – “đôi tay” của Hermes Agent. Bạn đã hiểu:

  • Cấu trúc và cách đăng ký tool.
  • Cách kiểm soát bề mặt tool để đảm bảo an toàn.
  • Cách mở rộng Hermes qua MCP Servers.
  • Cách xuất Hermes như một MCP Server để tích hợp ngược.
  • Cách tự viết tool tùy chỉnh cho nhu cầu riêng.

Tiếp theo, module 7 sẽ đưa bạn vào thế giới tự động hóa và Cron – nơi Hermes có thể thức dậy và làm việc theo lịch trình mà không cần bạn ở trong vòng lặp. Hãy sẵn sàng!


Tài liệu tham khảo:


Chúc bạn học tốt và sớm áp dụng những kiến thức này để xây dựng các agent mạnh mẽ, an toàn và linh hoạt!