Python 라이브러리로 Hermes 사용

기준일: 2026-07-26
난이도: 중급
공식 기준: Python 라이브러리

개요

Hermes는 CLI만이 아닙니다. AIAgent를 직접 import해 파이썬 스크립트, 웹 앱, 자동화 파이프라인에서 사용할 수 있습니다.

핵심 개념

API	용도
chat()	메시지 in → 최종 텍스트 out (툴 루프 내부 처리)
run_conversation()	전체 응답 dict (final_response, messages)
enabled_toolsets / disabled_toolsets	도구 최소/제외 집합
conversation_history	멀티턴 히스토리 재주입
save_trajectories	ShareGPT JSONL 궤적 저장
ephemeral_system_prompt	궤적에 안 남기는 시스템 프롬프트
quiet_mode=True	임베딩 시 CLI 스피너 억제 필수

상세

설치

지원되는 경로는 저장소 클론 + editable 개발 환경입니다. PyPI wheel/requirements.txt 단독 설치는 공식 지원 대상이 아닙니다.

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
uv sync
uv run python your_app.py

CLI와 동일한 환경 변수가 필요합니다. 최소 OPENROUTER_API_KEY 또는 직접 프로바이더 키.

기본 사용

from run_agent import AIAgent

agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    quiet_mode=True,
)
response = agent.chat("What is the capital of France?")
print(response)

전체 대화 제어

result = agent.run_conversation(
    user_message="Search for recent Python 3.13 features",
    task_id="my-task-1",
)
print(result["final_response"])
print(len(result["messages"]))

system_message로 해당 호출의 임시 시스템 프롬프트를 덮을 수 있습니다. task_id는 VM 격리용으로 에이전트 인스턴스에 저장되며 반환 dict에 echo되지 않습니다.

도구 설정

# 웹만
AIAgent(model="...", enabled_toolsets=["web"], quiet_mode=True)
# 터미널 제외
AIAgent(model="...", disabled_toolsets=["terminal"], quiet_mode=True)

최소 권한 봇은 enabled_toolsets, 대부분 허용·특정 차단은 disabled_toolsets.

멀티턴

result1 = agent.run_conversation("My name is Alice")
history = result1["messages"]
result2 = agent.run_conversation(
    "What's my name?",
    conversation_history=history,
)

히스토리는 내부 복사 — 원본 리스트는 변이되지 않습니다.

궤적 저장

agent = AIAgent(model="...", save_trajectories=True, quiet_mode=True)
agent.chat("Write a Python function to sort a list")
# trajectory_samples.jsonl (ShareGPT)

커스텀 시스템 프롬프트

ephemeral_system_prompt는 동작을 유도하되 궤적 파일에는 저장하지 않아 학습 데이터를 깨끗이 유지합니다.

실전 팁

• 항상 quiet_mode=True
• 장시간 배치에서는 모델/툴셋/재시도 정책을 명시
• 시크릿은 코드에 하드코딩하지 말고 env
• FAQ의 Python 예시는 요약용 — 전체 API는 이 가이드·원문 기준

체크리스트

• 공식 원문과 명령·설정 키를 대조했다
• 로컬/config.yaml/.env에서 재현 경로를 확인했다
• 권한·allowlist·시크릿 노출을 점검했다
• 실패 시 롤백·비활성화 방법을 알고 있다

다음 단계

• 공식 문서: Python 라이브러리
• Hermes Agent 소개
• 메시징 게이트웨이

---

기준일: 2026-07-26 — 공식 문서 동기화 코퍼스