🏠 Главная › guides › python library

Использование Hermes в качестве библиотеки Python

Hermes — это не просто CLI-инструмент. Вы можете импортировать AIAgent напрямую и использовать его программу в своих скриптах Python, веб-приложениях или процессах автоматизации. Это руководство покажет вам, как это сделать.

Установка

Установите Гермес непосредственно из репозитория:

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
```:::совет
При использовании Hermes в качестве библиотеки требуются те же переменные окружения, что и для CLI. Как минимум установите `OPENROUTER_API_KEY` (или `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` при прямом доступе к провайдеру).</div>
---

## Базовое использование

Самый простой способ использовать Hermes — метод `chat()`: передайте сообщение, введите текст в ответ:
```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() обрабатывает полный цикл диалога внутри себя — инструменты вызова, повторные попытки и всё остальное — и возвращает только итоговый текстовый ответ.:::предупреждение Всегда устанавливайте quiet_mode=True при встраивании Гермеса в свой код. Без этого агент будет выводить CLI-спиннеры, индикаторы прогресса и другой терминальный вывод, который засорит вывод вашего приложения.

Полный контроль над диалогом

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

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'])}")

Возвращаемый словарь содержит: - final_response — Итоговый текстовый ответ агента - messages — Полная история сообщений (системные, пользовательские, ассистента, инструменты вызова)

(Переданный task_id сохраняется в экземпляре агента для запуска машины, но не возвращается в словарь результата.)

Вы также можете передать пользовательское системное сообщение, которое переопределяет эфемерный системный запрос для этого вызова:

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

Инструменты для настройки

Управляйте тем, к каким наборам инструментов имеет доступ агент, с помощью enabled_toolsets или disabled_toolsets:

# Включить только веб-инструменты (просмотр, поиск)
agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    enabled_toolsets=["web"],
    quiet_mode=True,
)

# Включить всё, кроме доступа к терминалу
agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    disabled_toolsets=["terminal"],
    quiet_mode=True,
)
```:::совет
Используйте `enabled_toolsets`, когда вам нужен ограниченный агент (например, только веб-поиск для исследовательского бота). Используйте `disabled_toolsets`, когда вам нужны все возможности, но требуются конкретные конкретные вопросы (например, отсутствие доступа к терминалу в окружающей среде).</div>
---

## Многошаговые диалоги

Подождите состояние диалога в течение нескольких шагов, переведя историю сообщений обратно:
```python
agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
)

# Первый шаг
result1 = agent.run_conversation("My name is Alice")
history = result1["messages"]

# Второй шаг — агент помнит контекст
result2 = agent.run_conversation(
    "What's my name?",
    conversation_history=history,
)
print(result2["final_response"])  # "Ваше имя — Алиса."

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

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

Включите сохранение траекторий для захвата диалогов в формате ShareGPT — полезно для генерации обучающихся данных или отладок:

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

agent.chat("Write a Python function to sort a list")
# Сохраняется в trajectory_samples.jsonl в формате ShareGPT

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

Пользовательские системные промпты

Используйте ephemeral_system_prompt, чтобы задать пользовательский системный запрос, который управляет поведением агента, но не сохраняется в файлах траекторий (сохраняя ваши обучающие данные чистыми):

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)

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

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

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

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

Каждый получает запрос на свой собственный «task_id» и изолированную среду. Если вам нужна логика пакетной обработки устройства, вы можете создать ее с помощью 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):
    # Создаём новый агент для каждой задачи для потокобезопасности
    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")
```:::предупреждение
Всегда создавайте **новый экземпляр `AIAgent`** для каждого потока или задачи. Состояние агента по поддержке технологий (история диалога, инструменты сеансов, счетчики итераций), которые не являются потокобезопасными для совместного использования.</div>
---

## Примеры принятия

### 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 {"response": response}

Discord-бот

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")

Шаг CI/CD-пайплайна

#!/usr/bin/env python3
"""Шаг CI: автоматическое ревью diff PR."""
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)

Ключевые параметры конструктора

Параметр Тип По умолчанию Описание
модель ул "антропный/claude-opus-4.6" Модель в формате OpenRouter
тихий_режим бул Ложь Подавлять вывод CLI
enabled_toolsets Список[стр] Нет Белый список наборов инструментов
disabled_toolsets Список[стр] Нет Чёрный список наборов инструментов
save_trajectories бул Ложь Сохранять диалоги в JSONL
ephemeral_system_prompt ул Нет Пользовательский системный промпт (не сохраняется в траекториях)
max_iterations интервал 90 Максимальное количество итераций вызова инструментов для диалога
skip_context_files бул Ложь Пропустить загрузку файлов AGENTS.md
skip_memory бул Ложь Отключить чтение/запись постоянной памяти
api_key ул Нет Ключ API (использует переменные окружения, если не задано)
base_url ул Нет Пользовательский URL-адрес конечной точки API
платформа ул Нет Подсказка платформы (discord, telegram и т.д.)

Важные замечания:::совет