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

Sử dụng Hermes làm Thư viện Python

Hermes không chỉ là một công cụ CLI. Bạn có thể nhập trực tiếp AIAgent và sử dụng nó theo chương trình trong tập lệnh Python, ứng dụng web hoặc quy trình tự động hóa của riêng bạn. Hướng dẫn này chỉ cho bạn cách thực hiện.

Cài đặt

Cài đặt Hermes trực tiếp từ kho lưu trữ:

pip install git+https://github.com/NousResearch/hermes-agent.git

Hoặc với uv:

uv pip install git+https://github.com/NousResearch/hermes-agent.git

Bạn cũng có thể ghim nó vào requirements.txt :

hermes-agent @ git+https://github.com/NousResearch/hermes-agent.git

mẹo

Các biến môi trường tương tự được CLI sử dụng là bắt buộc khi sử dụng Hermes làm thư viện. Ở mức tối thiểu, hãy đặt OPENROUTER_API_KEY (hoặc OPENAI_API_KEY / ANTHROPIC_API_KEY nếu sử dụng quyền truy cập trực tiếp của nhà cung cấp).

Cách sử dụng cơ bản

Cách đơn giản nhất để sử dụng Hermes là phương thức chat() — chuyển tin nhắn, nhận lại một chuỗi:

from run_agent import AIAgent

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
)
response = agent.chat("What is the capital of France?")
print(response)

chat() xử lý toàn bộ vòng hội thoại nội bộ — gọi công cụ, thử lại, mọi thứ — và chỉ trả về phản hồi văn bản cuối cùng.

cảnh báo

Luôn đặt quiet_mode=True khi nhúng Hermes vào mã của riêng bạn. Nếu không có nó, tác nhân sẽ in các vòng quay CLI, chỉ báo tiến trình và đầu ra đầu cuối khác sẽ làm lộn xộn đầu ra của ứng dụng của bạn.

Kiểm soát toàn bộ cuộc hội thoại

Để kiểm soát tốt hơn cuộc trò chuyện, hãy sử dụng trực tiếp run_conversation(). Nó trả về một từ điển có đầy đủ phản hồi, lịch sử tin nhắn và siêu dữ liệu:

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
)

result = agent.run_conversation(
    user_message="Search for recent Python 3.13 features",
    task_id="my-task-1",
)

print(result["final_response"])
print(f"Messages exchanged: {len(result['messages'])}")

Từ điển được trả về chứa:

  • ** final_response ** — Tin nhắn trả lời cuối cùng của tổng đài viên
  • ** messages ** — Lịch sử tin nhắn đầy đủ (các lệnh gọi hệ thống, người dùng, trợ lý, công cụ)
  • ** task_id ** — Mã định danh tác vụ được sử dụng để cách ly VM

Bạn cũng có thể chuyển thông báo hệ thống tùy chỉnh ghi đè lời nhắc hệ thống tạm thời cho cuộc gọi đó:

result = agent.run_conversation(
    user_message="Explain quicksort",
    system_message="You are a computer science tutor. Use simple analogies.",
)

Công cụ cấu hình

Kiểm soát bộ công cụ nào mà tác nhân có quyền truy cập bằng cách sử dụng enabled_toolsets hoặc disabled_toolsets :

# Only enable web tools (browsing, search)
agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    enabled_toolsets=["web"],
    quiet_mode=True,
)

# Enable everything except terminal access
agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    disabled_toolsets=["terminal"],
    quiet_mode=True,
)

mẹo

Sử dụng enabled_toolsets khi bạn muốn một tác nhân tối thiểu, bị khóa (ví dụ: chỉ tìm kiếm trên web cho bot nghiên cứu). Sử dụng disabled_toolsets khi bạn muốn có hầu hết các khả năng nhưng cần hạn chế những khả năng cụ thể (ví dụ: không có quyền truy cập terminal trong môi trường dùng chung).

Cuộc trò chuyện nhiều lượt

Duy trì trạng thái hội thoại qua nhiều lượt bằng cách chuyển lại lịch sử tin nhắn:

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
)

# First turn
result1 = agent.run_conversation("My name is Alice")
history = result1["messages"]

# Second turn — agent remembers the context
result2 = agent.run_conversation(
    "What's my name?",
    conversation_history=history,
)
print(result2["final_response"])  

# "Your name is Alice."

Tham số conversation_history chấp nhận danh sách messages từ kết quả trước đó. Tác nhân sao chép nó trong nội bộ nên danh sách ban đầu của bạn không bao giờ bị thay đổi.

Lưu quỹ đạo

Bật tính năng lưu quỹ đạo để ghi lại các cuộc hội thoại ở định dạng ShareGPT — hữu ích cho việc tạo dữ liệu đào tạo hoặc gỡ lỗi:

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    save_trajectories=True,
    quiet_mode=True,
)

agent.chat("Write a Python function to sort a list")
# Saves to trajectory_samples.jsonl in ShareGPT format

Mỗi cuộc hội thoại được thêm dưới dạng một dòng JSONL duy nhất, giúp dễ dàng thu thập tập dữ liệu từ các lần chạy tự động.

Lời nhắc hệ thống tùy chỉnh

Sử dụng ephemeral_system_prompt để đặt lời nhắc hệ thống tùy chỉnh hướng dẫn hành vi của tổng đài viên nhưng không được lưu vào tệp quỹ đạo (giữ cho dữ liệu đào tạo của bạn luôn sạch sẽ):

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    ephemeral_system_prompt="You are a SQL expert. Only answer database questions.",
    quiet_mode=True,
)

response = agent.chat("How do I write a JOIN query?")
print(response)

Điều này lý tưởng cho việc xây dựng các tác nhân chuyên biệt — người đánh giá mã, người viết tài liệu, trợ lý SQL — tất cả đều sử dụng cùng một công cụ cơ bản.

Xử lý hàng loạtĐể chạy song song nhiều lời nhắc, Hermes bao gồm batch_runner.py . Nó quản lý các phiên bản AIAgent đồng thời với sự cách ly tài nguyên thích hợp:

python batch_runner.py --input prompts.jsonl --output results.jsonl

Mỗi lời nhắc có task_id và môi trường biệt lập riêng. Nếu cần logic lô tùy chỉnh, bạn có thể tự tạo logic của riêng mình bằng cách sử dụng trực tiếp AIAgent:

import concurrent.futures
from run_agent import AIAgent

prompts = [
    "Explain recursion",
    "What is a hash table?",
    "How does garbage collection work?",
]

def process_prompt(prompt):
    

# Create a fresh agent per task for thread safety
    agent = AIAgent(
        model="anthropic/claude-sonnet-4",
        quiet_mode=True,
        skip_memory=True,
    )
    return agent.chat(prompt)

with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
    results = list(executor.map(process_prompt, prompts))

for prompt, result in zip(prompts, results):
    print(f"Q: {prompt}\nA: {result}\n")

cảnh báo

Luôn tạo một phiên bản AIAgent mới cho mỗi luồng hoặc tác vụ. Tác nhân duy trì trạng thái nội bộ (lịch sử hội thoại, phiên công cụ, bộ đếm số lần lặp) không an toàn theo luồng để chia sẻ.

Ví dụ về tích hợp

Điểm cuối FastAPI​

from fastapi import FastAPI
from pydantic import BaseModel
from run_agent import AIAgent

app = FastAPI()

class ChatRequest(BaseModel):
    message: str
    model: str = "anthropic/claude-sonnet-4"

@app.post("/chat")
async def chat(request: ChatRequest):
    agent = AIAgent(
        model=request.model,
        quiet_mode=True,
        skip_context_files=True,
        skip_memory=True,
    )
    response = agent.chat(request.message)
    return {"response": response}

Bot bất hòa​

import discord
from run_agent import AIAgent

client = discord.Client(intents=discord.Intents.default())

@client.event
async def on_message(message):
    if message.author == client.user:
        return
    if message.content.startswith("!hermes "):
        query = message.content[8:]
        agent = AIAgent(
            model="anthropic/claude-sonnet-4",
            quiet_mode=True,
            skip_context_files=True,
            skip_memory=True,
            platform="discord",
        )
        response = agent.chat(query)
        await message.channel.send(response[:2000])

client.run("YOUR_DISCORD_TOKEN")

Bước đường dẫn CI/CD​

#!/usr/bin/env python3
"""CI step: auto-review a PR diff."""
import subprocess
from run_agent import AIAgent

diff = subprocess.check_output(["git", "diff", "main...HEAD"]).decode()

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
    skip_context_files=True,
    skip_memory=True,
    disabled_toolsets=["terminal", "browser"],
)

review = agent.chat(
    f"Review this PR diff for bugs, security issues, and style problems:\n\n{diff}"
)
print(review)

Tham số chính của hàm tạo

Tham sốLoạiMặc địnhMô tả
modelstr"anthropic/claude-opus-4.6"Mô hình ở định dạng OpenRouter
quiet_modeboolFalseNgăn chặn đầu ra CLI
enabled_toolsetsList[str]NoneBộ công cụ cụ thể trong danh sách trắng
disabled_toolsetsList[str]NoneDanh sách đen bộ công cụ cụ thể
save_trajectoriesboolFalseLưu cuộc hội thoại vào JSONL
ephemeral_system_promptstrNoneLời nhắc hệ thống tùy chỉnh (không được lưu vào quỹ đạo)
max_iterationsint90Số lần lặp lại gọi công cụ tối đa cho mỗi cuộc hội thoại
skip_context_filesboolFalseBỏ qua việc tải tập tin AGENTS.md
skip_memoryboolFalseVô hiệu hóa việc đọc/ghi bộ nhớ liên tục
api_keystrNoneKhóa API (quay lại env vars)
base_urlstrNoneURL điểm cuối API tùy chỉnh
platformstrNoneGợi ý nền tảng ( "discord" , "telegram" , v.v.)

Lưu ý quan trọng

mẹo
  • Đặt ** skip_context_files=True ** nếu bạn không muốn các tệp AGENTS.md từ thư mục làm việc được tải vào dấu nhắc hệ thống.
  • Đặt ** skip_memory=True ** để ngăn tác nhân đọc hoặc ghi bộ nhớ liên tục — được khuyến nghị cho các điểm cuối API không trạng thái.
  • Tham số platform (ví dụ: "discord" , "telegram" ) đưa vào các gợi ý định dạng dành riêng cho nền tảng để tác nhân điều chỉnh kiểu đầu ra của nó.
cảnh báo
  • An toàn luồng: Tạo một AIAgent cho mỗi luồng hoặc tác vụ. Không bao giờ chia sẻ một phiên bản giữa các cuộc gọi đồng thời.
  • Dọn dẹp tài nguyên: Tác nhân tự động dọn sạch tài nguyên (phiên cuối, phiên bản trình duyệt) khi cuộc trò chuyện kết thúc. Nếu bạn đang chạy một quy trình kéo dài, hãy đảm bảo mỗi cuộc trò chuyện đều hoàn tất bình thường.
  • Giới hạn lặp lại: max_iterations=90 mặc định rất rộng rãi. Đối với các trường hợp sử dụng Hỏi & Đáp đơn giản, hãy cân nhắc giảm giá trị này (ví dụ: max_iterations=10 ) để tránh vòng lặp gọi công cụ quá nhanh và kiểm soát chi phí.