API 서버 — 서비스로서의 Hermes | Easy Understand Hermes Agent

API 서버 — 서비스로서의 Hermes

이런 상황을 상상해 보세요. 여러분이 Hermes로 멋진 AI 에이전트를 만들었습니다. 터미널 명령어를 실행하고, 웹을 검색하고, 파일을 관리하고, 기억도 할 수 있죠. 하지만 그 에이전트는 터미널 안에만 갇혀 있습니다. 만약 이 에이전트를 Open WebUI나 LobeChat 같은 예쁜 채팅 인터페이스에 연결할 수 있다면 어떨까요? 바로 그걸 가능하게 해주는 것이 API 서버입니다.

API 서버를 일종의 만능 번역기라고 생각하면 됩니다. API 서버는 Hermes를 OpenAI 호환 HTTP 엔드포인트로 노출합니다. 즉, “OpenAI 언어”를 사용하는 프론트엔드라면 — 그런 도구가 수백 개나 됩니다 — 모두 Hermes에 연결해서 강력한 백엔드로 활용할 수 있다는 뜻입니다. 에이전트의 모든 도구 세트는 그대로 유지되고, 프론트엔드는 그저 예쁜 얼굴 역할만 하면 됩니다.

가장 좋은 점은? 응답을 스트리밍하면 도구 진행 표시기가 인라인으로 나타난다는 것입니다. 사용자가 에이전트가 명령어를 실행하거나 웹을 검색하는 모습을 실제로 볼 수 있고, 깜빡이는 커서만 바라보지 않아도 됩니다.

하나의 백엔드, 완전한 성능

본격적으로 시작하기 전에, 빠른 팁 하나 드리겠습니다. Hermes가 유용하려면 구성된 프로바이더와 도구 백엔드가 필요합니다. Nous Portal 구독 하나로 두 가지를 모두 해결할 수 있습니다 — Tool Gateway를 통해 300개 이상의 모델과 웹, 이미지, TTS, 브라우저 도구에 접근할 수 있습니다.

hermes setup --portal을 한 번 실행하면, 어떤 프론트엔드에든 완전한 도구를 갖춘 백엔드를 제공할 준비가 끝납니다. 시작하기에 가장 쉬운 방법입니다.

빠른 시작: 세 단계

1. API 서버 활성화

~/.hermes/.env 파일을 열고 다음 줄을 추가하세요:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# 선택 사항: 브라우저가 Hermes를 직접 호출해야 하는 경우에만
# API_SERVER_CORS_ORIGINS=http://localhost:3000

API_SERVER_KEY는 비밀번호입니다. 안전한 값으로 변경하세요!

2. 게이트웨이 시작

다음 명령어를 실행하세요:

hermes gateway

다음과 같은 메시지가 표시됩니다:

[API Server] API server listening on http://127.0.0.1:8642

끝입니다. 이제 여러분의 에이전트가 서비스가 되었습니다.

3. 프론트엔드 연결

OpenAI 호환 클라이언트를 http://localhost:8642/v1에 연결하세요. curl로 테스트해 봅시다:

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer change-me-local-dev" \
  -H "Content-Type: application/json" \
  -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'

또는 Open WebUI, LobeChat, 다른 프론트엔드를 연결해도 됩니다. 단계별 지침은 Open WebUI 통합 가이드를 확인하세요.

엔드포인트: 두 가지 대화 방식

API 서버는 두 가지 주요 엔드포인트를 제공합니다.

POST /v1/chat/completions

이것은 표준 OpenAI Chat Completions 형식입니다. 상태를 저장하지 않습니다(stateless) — 각 요청에 messages 배열을 통해 전체 대화 기록을 보내야 합니다.

간단한 요청 예시입니다:

{
  "model": "hermes-agent",
  "messages": [
    {"role": "system", "content": "You are a Python expert."},
    {"role": "user", "content": "Write a fibonacci function"}
  ],
  "stream": false
}

그리고 응답:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "hermes-agent",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Here's a fibonacci function..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250}
}

인라인 이미지가 지원됩니다. 메시지 콘텐츠의 일부로 이미지를 보낼 수 있습니다:

{
  "model": "hermes-agent",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/cat.png", "detail": "high"}}
      ]
    }
  ]
}

원격 URL과 data:image/... URL 모두 작동합니다. 업로드된 파일과 이미지가 아닌 데이터 URL은 400 unsupported_content_type 오류를 반환한다는 점에 유의하세요.

스트리밍이 바로 마법이 일어나는 부분입니다. "stream": true로 설정하면 SSE(Server-Sent Events)로 토큰 단위 응답을 받게 됩니다. Chat Completions에서는 표준 chat.completion.chunk 이벤트와 함께 커스텀 hermes.tool.progress 이벤트도 볼 수 있습니다. 이를 통해 프론트엔드는 최종 어시스턴트 텍스트를 오염시키지 않으면서 도구 활동을 표시할 수 있습니다.

POST /v1/responses

이것은 최신 OpenAI Responses API 형식입니다. 가장 큰 차이점은? previous_response_id를 통한 서버 측 대화 상태 저장을 지원한다는 것입니다. 서버가 도구 호출과 결과를 포함한 전체 대화 기록을 저장하므로, 클라이언트가 관리하지 않아도 다중 턴 컨텍스트가 유지됩니다.

요청 예시:

{
  "model": "hermes-agent",
  "input": "What files are in my project?",
  "instructions": "You are a helpful coding assistant.",
  "store": true
}

응답에는 이미 실행된 도구 호출이 표시됩니다:

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "hermes-agent",
  "output": [
    {"type": "function_call", "status": "completed", "name": "terminal", "arguments": "{\"command\": \"ls\"}", "call_id": "call_1"},
    {"type": "function_call_output", "status": "completed", "call_id": "call_1", "output": "README.md src/ tests/"},
    {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Your project has..."}]}
  ],
  "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}

도구 호출에 "status": "completed"가 붙어 있는 것을 확인하세요. Hermes가 이미 서버 측에서 실행했습니다. 클라이언트는 구조화된 도구 UI를 렌더링하기만 하면 됩니다.

다중 턴은 쉽습니다. 응답을 연결하기만 하면 됩니다:

{
  "input": "Now show me the README",
  "previous_response_id": "resp_abc123"
}

서버가 모든 도구 호출을 포함한 전체 대화를 재구성하고, 중단했던 지점부터 계속 진행합니다.

서비스할 준비가 되셨나요?

API 서버는 Hermes를 로컬 도구에서 완전한 서비스로 변신시킵니다. Chat Completions의 단순함을 선호하든, Responses의 상태 저장 기능을 선호하든, 이제 OpenAI 호환 프론트엔드를 위한 범용 백엔드를 갖추게 되었습니다. 한번 시도해 보세요 — 여러분의 에이전트가 서비스를 시작할 준비가 되었습니다.