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 các 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 của mình:
hermes-agent @ git+https://github.com/NousResearch/hermes-agent.git
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() — gửi 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.
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ênmessages— Lịch sử tin nhắn đầy đủ (hệ thống, người dùng, trợ lý, lệnh gọi 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 những bộ công cụ 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,
)
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 thiết bị đầu cuối 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 message 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 khả năng 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 riêng và môi trường biệt lập. Nếu bạn cần logic lô tùy chỉnh, bạn có thể tự xây dựng 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")
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ại | Mặc định | Mô tả |
|---|---|---|---|
người mẫu | str | "nhân chủng/claude-opus-4.6" | Mô hình ở định dạng OpenRouter |
chế độ yên tĩnh | bool | Sai | Ngăn chặn đầu ra CLI |
enable_toolsets | Danh sách[str] | Không có | Bộ công cụ cụ thể trong danh sách trắng |
disabled_toolsets | Danh sách[str] | Không có | Danh sách đen bộ công cụ cụ thể |
save_trajectories | bool | Sai | Lưu cuộc hội thoại vào JSONL |
phù du_system_prompt | str | Không có | Lời nhắc hệ thống tùy chỉnh (không được lưu vào quỹ đạo) |
max_iterations | int | 90 | Số lần lặp lại gọi công cụ tối đa cho mỗi cuộc hội thoại |
bỏ qua_context_files | bool | Sai | Bỏ qua việc tải tập tin AGENTS.md |
bỏ qua_bộ nhớ | bool | Sai | Vô hiệu hóa việc đọc/ghi bộ nhớ liên tục |
api_key | str | Không có | Khóa API (quay lại env vars) |
base_url | str | Không có | URL điểm cuối API tùy chỉnh |
nền tảng | str | Không có | Gợi ý nền tảng ("discord", "telegram"`, v.v.) |
Lưu ý quan trọng
- Đặt
skip_context_files=Truenếu bạn không muốn các tệpAGENTS.mdtừ 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ố
nền tảng(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ó.
- An toàn luồng: Tạo một
AIAgentcho 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=90mặc định là 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 việc giảm nó (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í.