Hermes Agent Chat

A Dify tool plugin that connects Dify to a self-hosted Hermes Agent API Server through Hermes' OpenAI-compatible HTTP API. It supports text chat, conversation-level and user-level context retention, Dify uploaded image inputs, and interaction with Hermes Agent skills and tools.

Simplified Chinese documentation is provided through Dify Marketplace multilingual README support.

Version Information

• Current Version: v0.0.1
• Release Date: 2026-05-11
• Compatibility: Dify Plugin Framework
• Python Version: 3.12
• License: Apache License 2.0

Version History

• v0.0.1 (2026-05-11):
  • Added Hermes API Server provider credential validation through GET /v1/models
  • Added Hermes /v1/responses tool invocation
  • Added two context strategies: conversation-level and user-level
  • Added Dify uploaded image support through base64 input_image
  • Added Hermes API Server configuration documentation and Docker networking guidance
  • Added explicit limitation that remote image URLs and document URLs are not supported in this version

Quick Start

1. Edit ~/.hermes/.env and add or merge the following API Server configuration. Replace YOUR_HERMES_API_SERVER_KEY with your own token:

   API_SERVER_ENABLED=true
   API_SERVER_KEY=YOUR_HERMES_API_SERVER_KEY
   
   # Optional. Keep loopback when Dify and Hermes run in the same host process environment.
   API_SERVER_HOST=127.0.0.1
   API_SERVER_PORT=8642
   

2. Start Hermes Gateway:

   hermes gateway
   

   You should see a message similar to:

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

3. Install the plugin package in Dify.

4. Configure provider credentials in Dify:

   • Base URL: Hermes API Server base URL 【default http://127.0.0.1:8642/v1，or http://host.docker.internal:8642/v1】
   • API Key: Hermes API_SERVER_KEY
   • Model: Hermes API Server model name, usually hermes-agent
   • Timeout: optional request timeout, default 600

5. Choose a tool:

   • hermes_chat: conversation-level context
   • hermes_user_chat: user-level context

6. Send text, optionally with Dify uploaded image files.

Key Features

• Hermes API Server Integration: Uses POST /v1/responses to interact with Hermes Agent.
• Credential Validation: Verifies Hermes connectivity and model availability through GET /v1/models.
• Two Context Strategies: Supports both per-conversation and per-user Hermes conversations.
• Direct Dify Image Uploads: Accepts Dify files image objects and forwards them as base64 input_image inputs.
• Safe Session Routing: Does not expose session_key, conversation_id, or user_id as LLM-controllable tool parameters.
• Scoped Input Surface: Remote image URLs, document URLs, and non-image uploads are intentionally not exposed in this version.

Core Features

1) Hermes Chat (hermes_chat)

Conversation-level Hermes context retention.

• Required: message
• Optional: upload_files for images only
• Context scope: Dify conversation/session metadata plus Dify user id when available
• Best for: normal multi-turn chat where each Dify conversation should stay isolated

2) Hermes User Chat (hermes_user_chat)

User-level Hermes context retention across Dify conversations.

• Required: message
• Optional: upload_files for images only
• Context scope: Dify user id only
• Best for: scenarios where the same Dify user should share one Hermes context across multiple Dify conversations
• Note: this tool fails clearly if Dify does not provide a user id

Shared Input Support

• Text: sent as Hermes Responses API input_text
• Uploaded images: sent as base64 input_image
• Remote image URLs: not supported in this version
• Uploaded documents / document URLs: not supported in this version

Hermes API Server Configuration

Before using this plugin, enable Hermes Agent API Server.

Required endpoint:

• POST /v1/responses

Required endpoint for Dify credential validation:

• GET /v1/models

Optional compatibility endpoint, not used by this plugin:

• POST /v1/chat/completions

Recommended .env for Docker Desktop or controlled private-network access:

API_SERVER_ENABLED=true
API_SERVER_KEY=YOUR_HERMES_API_SERVER_KEY
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8642

If Dify and Hermes run in the same host process environment, loopback is enough:

API_SERVER_ENABLED=true
API_SERVER_KEY=YOUR_HERMES_API_SERVER_KEY
API_SERVER_HOST=127.0.0.1
API_SERVER_PORT=8642

Bind Address Notes

Use API_SERVER_HOST=127.0.0.1 when only local access is needed.

Use API_SERVER_HOST=0.0.0.0 or a private interface address only when Docker, LAN, VPN, tailnet, or another private ingress needs to reach Hermes.

Do not expose Hermes API Server directly to the public internet. The API server can access the agent's tools, so protect it with a strong API_SERVER_KEY and private networking.

Dify Provider Configuration

Field	Required	Example	Description
Base URL	Yes	http://127.0.0.1:8642/v1	Hermes API Server base URL. It may include /v1; the plugin normalizes it internally.
API Key	Yes	YOUR_HERMES_API_SERVER_KEY	Hermes API Server bearer token configured as API_SERVER_KEY.
Model	Yes	hermes-agent	Hermes API Server model name returned by /v1/models.
Timeout	No	600	Request timeout in seconds. Valid range is 1-600; invalid values fall back to 600.

Base URL examples by deployment:

Deployment	Dify Base URL	Required Hermes API Server bind
Same host, no Docker	http://127.0.0.1:8642/v1	API_SERVER_HOST=127.0.0.1
Dify in Docker Desktop, Hermes on host	http://host.docker.internal:8642/v1	API_SERVER_HOST=0.0.0.0 or host LAN/private address
Dify on another LAN machine	http://<Hermes-host-LAN-IP>:8642/v1	API_SERVER_HOST=0.0.0.0 or Hermes host LAN IP
VPN / tailnet private deployment	http://<Hermes-private-name-or-IP>:8642/v1	Hermes VPN/tailnet bind or reachable private address
SSH tunnel or reverse proxy	tunnel/proxy URL, for example http://127.0.0.1:<local-port>/v1	Hermes can remain on API_SERVER_HOST=127.0.0.1

If Dify reports Failed to establish a new connection, Connection refused, or provider validation timeout, the Dify plugin runtime cannot reach the configured Base URL. The most common cause is using http://127.0.0.1:8642/v1 inside Docker while Hermes is running on the host loopback address.

Tool Parameters

Both tools expose the same parameters.

Parameter	Required	Form	Example	Description
message	Yes	llm	Summarize this project.	Current user message sent to Hermes.
upload_files	No	llm	Dify uploaded image file objects	Uploaded images. The plugin sends them as base64 input_image Responses parts.

The plugin does not expose session routing parameters as tool inputs. Hermes conversation keys are derived from Dify runtime metadata and sent through the Hermes Responses API conversation field with store=true.

Supported File Types

Supported uploaded image MIME types:

• image/jpeg
• image/png
• image/gif
• image/webp
• image/heic
• image/heif

Unsupported in this version:

• Remote image URLs
• Uploaded non-image documents
• Document URLs

Safety Limits

Uploaded image validation before forwarding to Hermes:

• Accepts at most 8 uploaded images per tool call.
• Rejects images larger than 10MB.
• Rejects the whole upload set when raw uploaded image bytes exceed 12MB.
• Rejects unsupported uploaded image MIME types.
• Does not expose URL fetch inputs to avoid SSRF and DNS rebinding risks.

Usage Examples

Text:

message: Summarize what you can do in this Hermes workspace.

Direct Dify image upload:

message: Analyze the uploaded screenshot and list action items.
upload_files: <Dify uploaded image files>

Requirements

• Python 3.12
• Dify Platform access
• Running Hermes Agent Gateway with API Server enabled
• Required Python packages installed through requirements.txt

Notes

• Hermes API Server is an operator-level agent surface. Keep it on loopback, VPN, tailnet, Docker host networking, or private ingress.
• HTTP sends the bearer token in plaintext. Use it only on trusted private networks, or terminate HTTPS at a trusted reverse proxy.
• The plugin currently exposes Dify tools, not a native Dify model provider.
• Native Dify streaming is not exposed yet; Hermes is called with stream=false through the Responses API.
• Uploaded images are sent as base64, increasing request size by about one third.

Developer Information

• Author: https://github.com/sawyer-shi
• Email: sawyer36@foxmail.com
• License: Apache License 2.0
• Source Code: https://github.com/sawyer-shi/dify-plugins-hermes_agent_chat
• Support: Through Dify platform and GitHub Issues

License Notice

This project is licensed under Apache License 2.0. See LICENSE file for full license text.

---

Ready to connect Dify with Hermes Agent?