본문으로 건너뛰기

Hermes를 Python 라이브러리로 사용

Hermes는 단순한 CLI 도구가 아닙니다. AIAgent을 직접 가져와서 Python 스크립트, 웹 애플리케이션 또는 자동화 파이프라인에서 프로그래밍 방식으로 사용할 수 있습니다. 이 가이드에서는 방법을 보여줍니다.

설치​

저장소에서 Hermes를 직접 설치하세요.

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

또는 uv를 사용하면 다음과 같습니다.

uv pip install git+https://github.com/NousResearch/hermes-agent.git
``requirements.txt`에 고정할 수도 있습니다.

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

Hermes를 라이브러리로 사용할 때는 CLI에서 사용하는 것과 동일한 환경 변수가 필요합니다. 최소한 OPENROUTER_API_KEY(또는 직접 공급자 액세스를 사용하는 경우 OPENAI_API_KEY / ANTHROPIC_API_KEY)을 설정하세요.

기본 사용법​

Hermes를 사용하는 가장 간단한 방법은 chat() 메서드입니다. 메시지를 전달하고 문자열을 다시 가져옵니다.

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()`은 도구 호출, 재시도 등 모든 대화 루프를 내부적으로 처리하고 최종 텍스트 응답만 반환합니다.

:::warning
자신의 코드에 Hermes를 삽입할 때는 항상 `quiet_mode=True`을 설정하세요. 이것이 없으면 에이전트는 애플리케이션 출력을 복잡하게 만드는 CLI 스피너, 진행률 표시기 및 기타 터미널 출력을 인쇄합니다.

:::
---

## 완전한 대화 제어 \{#basic-usage}

대화를 더 효과적으로 제어하려면 `run_conversation()`을 직접 사용하세요. 전체 응답, 메시지 기록 및 메타데이터가 포함된 사전을 반환합니다.

```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: {len(result['messages'])}")

반환된 사전에는 다음이 포함됩니다.

  • final_response — 에이전트의 최종 문자 응답
  • messages — 전체 메시지 기록(시스템, 사용자, 보조자, 도구 호출)

(전달한 task_id은 VM 격리를 위해 에이전트 인스턴스에 저장되지만 반환 사전에는 다시 에코되지 않습니다.)

해당 호출에 대한 임시 시스템 프롬프트를 재정의하는 사용자 지정 시스템 메시지를 전달할 수도 있습니다.

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

도구 구성​

enabled_toolsets 또는 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,
)
팁

최소한의 잠긴 에이전트를 원할 때(예: 연구 봇에 대한 웹 검색만) enabled_toolsets을 사용하세요. 대부분의 기능을 원하지만 특정 기능을 제한해야 하는 경우(예: 공유 환경에서 터미널 액세스 없음) disabled_toolsets을 사용하세요.

여러 차례 대화​

메시지 기록을 다시 전달하여 여러 차례에 걸쳐 대화 상태를 유지합니다.

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."
``conversation_history` 매개변수는 이전 결과의 `messages` 목록을 허용합니다. 에이전트는 이를 내부적으로 복사하므로 원본 목록이 변경되지 않습니다.

---

## 궤적 저장 \{#saving-trajectories}

ShareGPT 형식으로 대화를 캡처하려면 궤적 저장을 활성화하세요. 훈련 데이터 생성이나 디버깅에 유용합니다.

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

각 대화는 단일 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):
    # 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")
경고

항상 스레드 또는 작업별로 새 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_컨텍스트_files=True,
        skip_memory=True,
    )
    response = agent.chat(request.message)
    return {"response": response}

디스코드 봇​

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_컨텍스트_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 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_컨텍스트_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)

주요 생성자 매개변수​

매개변수유형기본값설명
modelstr"anthropic/claude-opus-4.6"OpenRouter 형식의 모델
quiet_modeboolFalseCLI 출력 억제
enabled_toolsetsList[str]None화이트리스트 특정 도구 세트
disabled_toolsetsList[str]None블랙리스트 관련 도구 세트
save_trajectoriesboolFalse대화를 JSONL에 저장
ephemeral_system_promptstrNone사용자 정의 시스템 프롬프트(궤적에 저장되지 않음)
max_iterationsint90대화당 최대 도구 호출 반복
skip_context_filesboolFalseAGENTS.md 파일 로드 건너뛰기
skip_memoryboolFalse영구 메모리 읽기/쓰기 비활성화
api_keystrNoneAPI 키(env var로 대체)
base_urlstrNone사용자 정의 API 엔드포인트 URL
platformstrNone플랫폼 힌트("discord", "telegram" 등)

중요 사항​

팁
  • 작업 디렉터리의 AGENTS.md 파일을 시스템 프롬프트에 로드하지 않으려면 **skip_context_files=True**을 설정하세요.
  • 에이전트가 영구 메모리를 읽거나 쓰지 못하도록 **skip_memory=True**을 설정합니다. 상태 비저장 API 엔드포인트에 권장됩니다.
  • platform 매개변수(예: "discord", "telegram")는 에이전트가 출력 스타일을 조정할 수 있도록 플랫폼별 형식 지정 힌트를 삽입합니다.
경고
  • 스레드 안전성: 스레드 또는 작업당 하나의 AIAgent을 만듭니다. 동시 호출 간에 인스턴스를 공유하지 마십시오.
  • 리소스 정리: 에이전트는 대화가 끝나면 자동으로 리소스(터미널 세션, 브라우저 인스턴스)를 정리합니다. 장기 프로세스에서 실행 중인 경우 각 대화가 정상적으로 완료되는지 확인하세요.
  • 반복 제한: 기본값 max_iterations=90은 넉넉합니다. 간단한 Q&A 사용 사례의 경우 도구 호출 루프 폭주를 방지하고 비용을 제어하려면 이를 낮추는 것이 좋습니다(예: max_iterations=10).