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](https://docs.astral.sh/uv/):

`bash
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:

`text
Hermes-agent @ git+https://GitHub.com/NousResearch/Hermes-agent.git

`

:::tip
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 pháp 
`chat()

 - gửi tin nhắn, nhận lại một chuỗi:

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

:::warning
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 nhiều 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:

``` python
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: \&#123;len(result['messages'])&#125;")

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

- **
`final_response

** — Tin nhắn trả lời cuối cùng của đại lý
- **
`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à bạn chuyển vào được lưu trữ trên phiên bản tác nhân để cách ly VM nhưng không được phản hồi trong lệnh trả về.)

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 đó:

``` python
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 
`enabled_toolsets
` hoặc 
`disabled_toolsets

:

`Python

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

`

:::tip
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:

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

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

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

`bash
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 bằng cách sử dụng trực tiếp 
`AIAgent

:

`Python
 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: \&#123;prompt&#125;\nA: \&#123;result&#125;\n")

`

:::warning
Luôn tạo **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

``` python
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 \&#123;"response": response&#125;

`

### Bot discord

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

`Python
#!/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\&#123;diff&#125;"
)
print(review)

`

---

## Tham số chính của hàm tạo| Tham số | Loại | Mặc định | Mô tả |
|----------|------|----------|-------------|
| 
`model
` | 
`str
` | 

"Anthropic/Claude-opus-4.6"
` | Mô hình ở định dạng OpenRouter |
| 
`quiet_mode
` | 
`bool
` | 
`False
` | Ngăn chặn đầu ra CLI |
| 
`enabled_toolsets
` | 
`List[str]
` | 
`None
` | Bộ công cụ cụ thể trong danh sách trắng |
| 
`disabled_toolsets
` | 
`List[str]
` | 
`None
` | Danh sách đen bộ công cụ cụ thể |
| 
`save_trajectories
` | 
`bool
` | 
`False
` | Lưu cuộc hội thoại vào JSONL |
| 
`ephemeral_system_prompt
` | 
`str
` | 
`None
` | 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 |
| 
`skip_context_files
` | 
`bool
` | 
`False
` | Bỏ qua việc tải tập tin AGENTS.md |
| 
`skip_memory
` | 
`bool
` | 
`False
` | Vô hiệu hóa việc đọc/ghi bộ nhớ liên tục |
| 
`API_key
` | 
`str
` | 
`None
` | Khóa API (quay lại env vars) |
| 
`base_url
` | 
`str
` | 
`None
` | URL điểm cuối API tùy chỉnh |
| 
`platform
` | 
`str
` | 
`None
` | Gợi ý nền tảng (

"Discord"

, 

"Telegram"

, v.v.) |

---

## Lưu ý quan trọng

:::tip

- Đặ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ó.
:::

:::warning
- **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 mức 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í.
:::
Cài đặt​

Cài đặt
