API 서버

API 서버는 OpenAI 호환 HTTP 엔드포인트로 hermes-agent를 노출합니다. OpenAI 형식을 말하는 모든 프론트엔드 — Open WebUI, LobeChat, LibreChat, NextChat, ChatBox, 그리고 수백 더 — hermes-agent에 연결하고 백엔드로 사용할 수 있습니다.

사용자의 에이전트는 전체 도구 (terminal, file operations, web search, Memory, Skill)와 요청을 처리하고 최종 응답을 반환합니다. 스트리밍 할 때, 도구 진행 지표는 인라인으로 나타납니다 그래서 frontends는 에이전트가하는 것을 보여줄 수 있습니다.

빠른 시작

1. 명세 API 서버 활성화

~/.hermes/.env에 추가:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Optional: only if a browser must call Hermes directly
# API_SERVER_CORS_ORIGINS=http://localhost:3000

2. 명세 게이트웨이 시작

hermes gateway

당신은 볼 수 있습니다:

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

3. 명세 프론트엔드

http://localhost:8642/v1의 OpenAI 호환 클라이언트를 포인트:

# Test with 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 통합 가이드를 단계별 지침에 참조하세요.

설명

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

인라인 이미지 입력: 사용자 메시지는 content의 배열으로 text 및 image_url 부분을 보낼 수 있습니다. 리모트 http(s) URL과 data:image/... 둘 다 URL이 지원됩니다:

{
  "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"}}
      ]
    }
  ]
}

업로드 파일 (file / input_file / file_id) 및 비 이미지 data: URL 반환 400 unsupported_content_type.

**("stream": true): 토큰별 응답 펑크로 Server-Sent Events(SSE)를 반환합니다. Chat Completions, 스트림 사용 표준 chat.completion.chunk 이벤트 플러스 Hermes' 사용자 정의 hermes.tool.progress 도구 기반 UX 이벤트. Responses는 response.created, response.output_text.delta, response.output_text.delta, response.output_item.added, response.output_item.done, response.completed와 같은 스트림 사용 OpenAI 응답 이벤트 유형입니다.

스트림의 도구 진행:

• Chat Completions: Hermes는 오염된 조수 텍스트없이 도구 별 가시성을 위해 event: hermes.tool.progress를 방출합니다.
• Responses: Hermes는 SSE 스트림 중에 spec-native function_call 및 function_call_output 출력 항목을 방출하므로 클라이언트는 실시간 구조 도구 UI를 렌더링할 수 있습니다.

POST /v1/책임

OpenAI 응답 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", "name": "terminal", "arguments": "{\"command\": \"ls\"}", "call_id": "call_1"},
    {"type": "function_call_output", "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}
}

인라인 이미지 입력: input.content는 input_text와 input_image 부품을 포함할 수 있습니다. 리모트 URL과 data:image/... 둘 다 URL이 지원됩니다:

{
  "model": "hermes-agent",
  "input": [
    {
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Describe this screenshot."},
        {"type": "input_image", "image_url": "data:image/png;base64,iVBORw0K..."}
      ]
    }
  ]
}

파일 업로드 (input_file / file_id) 및 비 이미지 data: URL 반환 400 unsupported_content_type.

이전의 멀티턴_response_id

전체 컨텍스트를 유지하기위한 체인 응답 (도구 통화 포함) 회전:

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

서버는 저장된 응답 체인에서 전체 대화를 재구성합니다. 이전 도구 통화 및 결과는 보존됩니다. Chained 요청은 동일한 세션을 공유하므로 멀티턴 대화는 대시보드 및 세션 역사의 단일 항목으로 나타납니다.

이름 대화

응답 ID를 추적하는 대신 conversation 매개변수를 사용하세요:

{"input": "Hello", "conversation": "my-project"}
{"input": "What's in src/?", "conversation": "my-project"}
{"input": "Run the tests", "conversation": "my-project"}

서버는 이 대화에서 최신 응답에 자동으로 체인합니다. /title 게이트웨이 세션의 명령처럼.

GET /v1/responses/{id}

ID로 이전 저장 응답을 검색합니다.

DELETE /v1/responses/{id}

저장된 응답을 삭제합니다.

/v1/models 받기

가능한 모델로 에이전트를 나열합니다. 광고된 모델명은 profile 이름(또는 hermes-agent)에 기본값으로 구분됩니다. model discovery에 가장 프론트엔드가 필요합니다.

/v1/capabilities 받기

외부 UI, 오케스트라, 플러그인 브리지를 위한 API 서버의 안정적인 표면의 기계 읽기 쉬운 설명을 반환합니다.

{
  "object": "hermes.api_server.capabilities",
  "platform": "hermes-agent",
  "model": "hermes-agent",
  "auth": {"type": "bearer", "required": true},
  "features": {
    "chat_completions": true,
    "responses_api": true,
    "run_submission": true,
    "run_status": true,
    "run_events_sse": true,
    "run_stop": true
  }
}

이 엔드포인트를 사용하여 대쉬보드, 브라우저 UI, 또는 제어 비행기를 통합할 때 사용하므로 Hermes 버전이 개인 파이썬 내부에 따라 실행, 스트리밍, 취소 및 세션 연속성을 지원할지 여부를 발견할 수 있습니다.

/건강

건강 검사. 기타 제품 {"status": "ok"}입니다. /v1/ 접두사를 기대하는 OpenAI 호환 클라이언트를 위한 GET /v1/health에서도 사용할 수 있습니다.

/health/detailed를 얻으십시오

또한 활성 세션, 실행 에이전트 및 리소스 사용을보고하는 확장 된 건강 검사. 모니터링/보통성 툴링에 유용합니다.

Runs API (스트림 친화적 인 대안)

/v1/chat/completions 및 /v1/responses 외에도 서버는 runs API를 제공합니다. 클라이언트가 스트리밍을 관리하지 않고 진행하는 이벤트를 구독하고 싶습니다.

POST /v1/회

새로운 에이전트 실행. 진행 이벤트에 가입할 수 있는 run_id를 반환합니다.

{
  "run_id": "run_abc123",
  "status": "started"
}

실행은 간단한 input 문자열 및 선택 session_id, instructions, conversation_history, 또는 previous_response_id를 허용합니다. session_id가 제공될 때, Hermes는 실행 상태에 표면이 적용되어 외부 UI가 자신의 대화 ID와 일치할 수 있습니다.

GET /v1/runs/{run_id}

현재 실행 상태. SSE 연결이 열리지 않고 상태가 필요한 대시보드에 유용합니다.

{
  "object": "hermes.run",
  "run_id": "run_abc123",
  "status": "completed",
  "session_id": "space-session",
  "model": "hermes-agent",
  "output": "Done.",
  "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}

상태는 단말 상태 (completed, failed, 또는 cancelled) 후 간단히 유지됩니다.

GET /v1/runs/{run_id}/events

Server-Sent 이벤트 스트림의 run's tool-call 진행, 토큰 deltas 및 lifecycle 이벤트. 대시보드 및 두꺼운 클라이언트를 위해 설계되어 / 잃어버린 상태없이 detach.

POST /v1/runs/{run_id}/stop

실행 에이전트 턴을 중단. endpoint는 {"status": "stopping"}로 즉시 반환합니다. Hermes는 다음 안전한 중단 지점에서 중지하는 활성 에이전트를 요청합니다.

작업 API (background 예정된 작업)

서버는 예정된 / 배경 에이전트 관리를위한 경량 작업 CRUD 표면을 원격 클라이언트에서 실행합니다. 모든 종점은 같은 곰 auth 뒤에 문지릅니다.

GET /api / 작업

자주 묻는 질문.

POST /api / 작업

새로운 일정한 일을 만듭니다. 몸은 hermes cron와 동일한 모양을 받아들입니다 — 신속한, 일정, 기술, 제공자 재정의, 납품 표적.

GET /api / 작업 / {job_id}

단일 작업의 정의와 마지막 실행 상태를 잡아.

PATCH /api/작업/{job_id}

기존 직업의 업데이트 필드 (prompt, 일정 등). Partial 업데이트가 합병되었습니다.

DELETE /api / 작업 / {job_id}

작업 제거. 또한 어떤 in-flight 실행 취소.

POST /api/jobs/{job_id}/pause

그것을 삭제하지 않고 일을 일시. Next-scheduled-run 타임스탬프는 다시 시작될 때까지 중단됩니다.

POST /api / 작업 / {job_id} / 이력서

이전 일시 중지 작업을 재개합니다.

POST /api/jobs/{job_id}/run

Trigger the job to run 즉시, 밖으로 일정.

시스템 Prompt 처리

프론트엔드가 system 메시지 (Chat Completions) 또는 instructions 필드 (Responses API)를 보낼 때, 그 코어 시스템 프롬프트의 상단**에 해당합니다. 에이전트는 모든 도구, 메모리, 기술 유지 — frontend's system prompt adds extra direction.

이것은 당신이 기능을 잃지 않고 동작을 사용자 정의 할 수 있음을 의미합니다:

• WebUI 시스템 프롬프트를 엽니다: "당신은 파이썬 전문가입니다. 항상 타입의 힌트가 있습니다."
• 에이전트은 아직도 터미널, 파일 공구, 웹 검색, 기억, 등 가지고 있습니다.

회사연혁

Authorization 헤더를 통해 Bearer 토큰 우:

Authorization: Bearer ***

키 구성 API_SERVER_KEY 에바 var. Hermes를 직접 호출하는 브라우저가 필요한 경우, API_SERVER_CORS_ORIGINS를 명시한 수당에 설정합니다.

Security

API 서버는 hermes-agent의 도구 모음에 대한 전체 액세스를 제공합니다, 터미널 명령을 포함. 0.0.0.0, API_SERVER_KEY와 같은 비 루프백 주소에 바인딩하면 **가 필요합니다. 또한 브라우저 액세스를 제어하는 API_SERVER_CORS_ORIGINS 좁은 유지.

default bind address (127.0.0.1)는 로컬에서만 사용할 수 있습니다. 브라우저 액세스는 기본적으로 비활성화됩니다. 명시된 신뢰할 수있는 기원에만 활성화하세요.

제품 설명

환경 변수

옵션 정보	기본 정보	설명
API_SERVER_ENABLED	false	API 서버 활성화
API_SERVER_PORT	8642	HTTP 서버 포트
API_SERVER_HOST	127.0.0.1	Bind 주소 (기본값으로 localhost만)
API_SERVER_KEY	(없음)	auth에 대한 Bearer 토큰
API_SERVER_CORS_ORIGINS	(없음)	Comma-separated 허용된 브라우저 기원
API_SERVER_MODEL_NAME	(프로필 이름)	/v1/models의 모델명. 기본 프로필에 대한 프로파일 이름 또는 hermes-agent에 기본값.

설정.yaml

# Not yet supported — use environment variables.
# config.yaml support coming in a future release.

보안 헤더

모든 응답은 보안 우두머리를 포함합니다:

• X-Content-Type-Options: nosniff - MIME 유형 스니핑 방지
• Referrer-Policy: no-referrer - 리퍼러 누설 방지

사이트맵

API 서버는 ** 기본적으로 브라우저 CORS를 사용할 수 없습니다.

직접적인 브라우저 접근을 위해, 명시된 Allowlist를 놓으십시오:

API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

CORS가 활성화되면:

• **Preflight 응답 **에는 Access-Control-Max-Age: 600 (10 분 캐시)가 포함됩니다
• **SSE 스트리밍 응답 ** CORS 헤더를 포함하므로 브라우저 EventSource 클라이언트가 올바르게 작동
• **Idempotency-Key**는 허용된 요청 헤더입니다. 클라이언트는 deduplication (responses는 5 분 동안 키로 캐시됩니다)

Open WebUI와 같은 대부분의 문서화 된 frontend 서버 - 서버 연결하고 모든 CORS가 필요하지 않습니다.

호환성 Frontends

OpenAI API 형식을 지원하는 모든 frontend. Tested/documented 통합:

회사연혁	설명	관련 기사
Open WebUI를 설치	126k	자주 묻는 질문
계정 관리	73k	주문 제공자 endpoint
리브 설명	34k	librechat의 사용자 정의 엔드 포인트. 스낵 바
모든 제품	56k	Generic OpenAI 제공자
다음 채팅	87k	BASE_URL의 특징
채팅박스	39k	API 지원 호스트 설정
1 월	26k	먼 모델 config
HF 채팅 UI	8k	오픈AI_BASE_URL
큰-AGI	7k	주문 endpoint
OpenAI 파이썬 SDK	—	OpenAI(base_url="http://localhost:8642/v1")
컬럼	—	직접 HTTP 요청

Multi-User 설정

여러 사용자가 자신의 고립 된 헤르메스 인스턴스 (설정, 메모리, 기술)를 제공, 사용 프로필:

# Create a profile per user
hermes profile create alice
hermes profile create bob

# Configure each profile's API server on a different port. API_SERVER_* are env
# vars (not config.yaml keys), so write them to each profile's.env:
cat >> ~/.hermes/profiles/alice/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8643
API_SERVER_KEY=alice-secret
EOF

cat >> ~/.hermes/profiles/bob/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8644
API_SERVER_KEY=bob-secret
EOF

# Start each profile's gateway
hermes -p alice gateway &
hermes -p bob gateway &

각 프로필의 API 서버는 자동으로 모델 ID로 프로필 이름을 광고합니다

• http://localhost:8643/v1/models → 모델 alice
• http://localhost:8644/v1/models → 모델 bob

Open WebUI에서 각각 별도의 연결을 추가합니다. 모델 드롭다운은 alice와 bob를 별도의 모델로 보여줍니다. Open WebUI Guide를 참고해 주세요.

계정 관리

• Response storage - 저장된 응답 (previous_response_id)은 SQLite에서 지속되고 게이트웨이 재시작을 생존합니다. 최대 100개의 저장된 응답 (LRU eviction).
• **파일 업로드 없음 ** — 인라인 이미지는 /v1/chat/completions와 /v1/responses 모두 지원되지만 업로드된 파일 (file, input_file, file_id) 및 비 이미지 문서 입력은 API를 통해 지원되지 않습니다.
• 모델 필드는 화장품 — 요청의 model 필드는 허용되지만 실제 LLM 모델은 구성 서버 측으로 구성되어 있습니다. 스낵 바.

프록시 모드

API 서버는 gateway 프록시 모드에 대한 백엔드 역할을 합니다. 또 다른 헤르메스 게이트웨이 인스턴스가 GATEWAY_PROXY_URL이 API 서버에서 점유하면 자체 에이전트를 실행하는 대신 모든 메시지를 전달합니다. 이것은 분할 배포를 가능하게합니다. 예를 들어, Docker 컨테이너 핸들링 Matrix 는 호스트 측 에이전트에 릴레이합니다.

전체 설정 가이드에 대한 Matrix Proxy Mode를 참조하세요.