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
  • Added Hermes tool invocation
  • Added two context strategies: conversation-level and user-level
  • Added Dify uploaded image support through base64
  • 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 and add or merge the following API Server configuration. Replace with your own token:

2. Start Hermes Gateway:

   You should see a message similar to:

3. Install the plugin package in Dify.

4. Configure provider credentials in Dify:

   • : Hermes API Server base URL 【default ，or 】
   • : Hermes
   • : Hermes API Server model name, usually
   • : optional request timeout, default

5. Choose a tool:

   • : conversation-level context
   • : user-level context

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

Key Features

• Hermes API Server Integration: Uses to interact with Hermes Agent.
• Credential Validation: Verifies Hermes connectivity and model availability through .
• Two Context Strategies: Supports both per-conversation and per-user Hermes conversations.
• Direct Dify Image Uploads: Accepts Dify image objects and forwards them as base64 inputs.
• Safe Session Routing: Does not expose , , or 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 ()

Conversation-level Hermes context retention.

• Required:
• Optional: 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 ()

User-level Hermes context retention across Dify conversations.

• Required:
• Optional: 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
• Uploaded images: sent as base64
• 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:

Required endpoint for Dify credential validation:

Optional compatibility endpoint, not used by this plugin:

Recommended for Docker Desktop or controlled private-network access:

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

Bind Address Notes

Use when only local access is needed.

Use 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 and private networking.

Dify Provider Configuration

Base URL examples by deployment:

If Dify reports , , or provider validation timeout, the Dify plugin runtime cannot reach the configured . The most common cause is using inside Docker while Hermes is running on the host loopback address.

Tool Parameters

Both tools expose the same parameters.

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 field with .

Supported File Types

Supported uploaded image MIME types:

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 uploaded images per tool call.
• Rejects images larger than .
• Rejects the whole upload set when raw uploaded image bytes exceed .
• Rejects unsupported uploaded image MIME types.
• Does not expose URL fetch inputs to avoid SSRF and DNS rebinding risks.

Usage Examples

Text:

Direct Dify image upload:

Requirements

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

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 through the Responses API.
• Uploaded images are sent as base64, increasing request size by about one third.

Developer Information

• Author:
• Email: [email protected]
• License: Apache License 2.0
• Source Code:
• Support: Through Dify platform and GitHub Issues

License Notice

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

---

Ready to connect Dify with Hermes Agent?