Hermes как Python-библиотека

· 7 мин чтения · admin

Установка

Для использования Hermes как Python-библиотеки установите пакет через pip:

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

Или с помощью uv:

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

Можно также указать в requirements.txt:

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

Переменные окружения. Как и CLI, библиотека требует API-ключи. Как минимум задайте OPENROUTER_API_KEY (или OPENAI_API_KEY / ANTHROPIC_API_KEY при прямом доступе к провайдеру).

Быстрый старт

Минимальный пример — метод chat() принимает текстовый запрос и возвращает строку-ответ. Внутри агент выполняет полный цикл: вызовы инструментов, повторы, обработку ошибок.

from run_agent import AIAgent

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
)
response = agent.chat("Объясни квантовую физику простыми словами.")
print(response)

Важно: Всегда задавайте quiet_mode=True при встраивании Hermes в свой код. Без этого агент печатает спиннеры, индикаторы прогресса и другой служебный вывод в консоль.

Полный контроль разговора

Для расширенного управления используйте run_conversation() напрямую. Он возвращает словарь с полной историей сообщений и метаданными:

from run_agent import AIAgent

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

result = agent.run_conversation(
    "Напиши функцию сортировки слиянием на Python."
)

print(result["final_response"])       # текст ответа
print(len(result["messages"]))        # количество сообщений в истории

Можно передать кастомный system message:

result = agent.run_conversation(
    "Проверь этот код на уязвимости.",
    system_message="Ты — эксперт по безопасности Python-кода. Отвечай кратко."
)

Многораундовые диалоги

Поддерживайте контекст между запросами, передавая историю сообщений обратно:

from run_agent import AIAgent

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

# Первый запрос
result1 = agent.run_conversation("Что такое REST API?")
history = result1["messages"]

# Второй запрос — с контекстом первого
result2 = agent.run_conversation(
    "Приведи пример на FastAPI.",
    conversation_history=history,
)
print(result2["final_response"])

Параметр conversation_history принимает список messages из предыдущего результата. Агент копирует его внутренне — ваш оригинальный список не мутируется.

Настройка инструментов

Управляйте доступными инструментами через enabled_toolsets (белый список) или disabled_toolsets (чёрный список):

# Только веб-поиск (минимальный агент-исследователь)
agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
    enabled_toolsets=["web", "file"],
)

# Все инструменты кроме терминала (безопасный режим)
agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
    disabled_toolsets=["terminal", "browser"],
)

enabled_toolsets — когда нужен минимальный набор (исследовательский бот, API-эндпоинт). disabled_toolsets — когда нужны почти все возможности, но нужно ограничить конкретные (например, без терминала в общем окружении).

Сохранение траекторий

Включите save_trajectories=True для записи диалогов в формате ShareGPT (JSONL) — полезно для генерации тренировочных данных или отладки:

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

Каждый разговор дописывается как одна строка JSONL, что удобно для сбора датасетов из автоматических запусков.

Кастомный системный промпт

Используйте ephemeral_system_prompt для задания специализированного поведения агента. Промпт не сохраняется в файлы траекторий — тренировочные данные остаются чистыми:

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
    ephemeral_system_prompt="Ты — ревьювер Python-кода. Оценивай код по PEP 8, находи баги, предлагай улучшения.",
)

Это идеально для создания специализированных агентов — ревьювера кода, документационного ассистента, SQL-помощника — на единой инструментальной базе.

Пакетная обработка

Для параллельного выполнения нескольких запросов используйте batch_runner.py. Он управляет конкурентными экземплярами AIAgent с изоляцией ресурсов:

from batch_runner import BatchRunner

runner = BatchRunner(model="anthropic/claude-sonnet-4")
results = runner.run([
    "Что такое Docker?",
    "Объясни Kubernetes.",
    "Что такое CI/CD?",
])

Для кастомной логики можно создавать экземпляры напрямую:

import threading
from run_agent import AIAgent

def process(prompt):
    agent = AIAgent(model="anthropic/claude-sonnet-4", quiet_mode=True)
    result = agent.chat(prompt)
    print(f"Q: {prompt}
A: {result}
")

threads = [threading.Thread(target=process, args=(q,)) for q in queries]
for t in threads:
    t.start()
for t in threads:
    t.join()

Всегда создавайте новый экземпляр AIAgent на каждый поток или задачу. Агент хранит внутреннее состояние (историю, сессии инструментов, счётчики итераций), которое не является потокобезопасным.

Параметры конструктора

Класс AIAgent поддерживает множество параметров для тонкой настройки:

Параметр Тип По умолчанию Описание
model str "" Модель в формате OpenRouter (по умолчанию берётся из конфига Hermes)
quiet_mode bool False Подавление вывода в консоль
enabled_toolsets List[str] None Белый список инструментов
disabled_toolsets List[str] None Чёрный список инструментов
max_iterations int 90 Максимум итераций вызова инструментов
skip_context_files bool False Пропуск загрузки файлов AGENTS.md
skip_memory bool False Отключение чтения/записи постоянной памяти
ephemeral_system_prompt str None Кастомный системный промпт (не сохраняется в траектории)
save_trajectories bool False Сохранение диалогов в формате ShareGPT (JSONL)
platform str None Подсказка платформы ("discord", "telegram" и т.д.)
api_key str None API-ключ (если не задан — берётся из переменных окружения)
base_url str None Кастомный URL API-эндпоинта
provider str None Провайдер (openrouter, anthropic, openai и др.)
max_tokens int None Максимальное количество токенов в ответе
fallback_model Dict None Резервная модель при ошибке основной
reasoning_config Dict None Конфигурация рассуждений (reasoning)

Встраивание в веб-приложения

AIAgent легко интегрируется в веб-фреймворки, например 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}

Для веб-серверов рекомендуется устанавливать skip_context_files=True и skip_memory=True, чтобы избежать побочных эффектов между запросами.

Встраивание в ботов и CI/CD

  • Discord-бот — создайте экземпляр AIAgent с platform="discord" и quiet_mode=True, обрабатывайте сообщения через agent.chat()
  • Ревью PR в CI/CD — получите diff через subprocess, отправьте его агенту с disabled_toolsets=["terminal", "browser"] для безопасного анализа
  • Пакетная обработка — обрабатывайте списки запросов, создавая отдельный экземпляр агента для каждого

hermes_tools — инструменты в песочнице

При использовании execute_code (песочница для выполнения Python) внутри агента доступен модуль hermes_tools с RPC-функциями для вызова инструментов из скрипта:

from hermes_tools import web_search, web_extract, read_file, write_file, search_files, patch, terminal

# Поиск в интернете
results = web_search("Python async patterns", limit=5)

# Извлечение контента из URL
content = web_extract(["https://example.com"], char_limit=10000)

# Работа с файлами
file_data = read_file("/path/to/file.py", offset=1, limit=100)
write_file("/path/to/output.txt", "содержимое")
matches = search_files("def main", target="content", path=".", file_glob="*.py")

# Патч файлов
patch(path="/path/to/file.py", old_string="old", new_string="new")

# Выполнение shell-команд
result = terminal("echo hello", timeout=30)

Эти функции работают через RPC (Unix domain socket для локального бэкенда, файловый обмен для удалённых) и позволяют скриптам в песочнице взаимодействовать с основным окружением агента.

Важные рекомендации

  • Потокобезопасность — создавайте отдельный экземпляр AIAgent для каждого потока или задачи. Никогда не передавайте один экземпляр между конкурентными вызовами.
  • Очистка ресурсов — агент автоматически освобождает ресурсы (сессии терминала, экземпляры браузера) по завершении разговора. Если вы работаете в долгоживущем процессе, убедитесь, что каждый разговор завершается нормально.
  • Лимиты итераций — для простых задач снижайте max_iterations (например, до 10) для экономии токенов и предотвращения бесконечных циклов.
  • Многораундовые диалоги — используйте run_conversation() с параметром conversation_history для поддержания контекста в рамках одной сессии.

Документация: hermes-agent.nousresearch.com