How to Connect Nous Research Hermes Agent to the ZeroGPT API

According to official product documentation, ZeroGPT detects AI-generated content with up to 98% accuracy when analyzing structured prose [ZeroGPT Documentation 2026]. This detection rate makes the API a standard choice for teams that need to validate content quality before publication. However, developers deploying autonomous agents face a significant verification challenge. Most developer guides focus on GPTZero or Copyleaks, skipping ZeroGPT API parameters entirely. The Nous Research Hermes Agent supports custom SKILL.md files for extending agent capabilities, but no official documentation provides built-in tool integrations for this detection endpoint [Nous Research Hermes Agent Documentation]. This article explains how to build a custom Python skill to connect a Hermes Agent to the ZeroGPT API, establishing an automated content verification pipeline.

The Nous Research Hermes Agent is an open-source, MIT-licensed agentic framework. Unlike closed-source, hosted software-as-a-service agent platforms, the Hermes Agent runs in user-controlled environments such as local machines, remote virtual private servers, Docker containers, or serverless infrastructure like Modal. The agent maintains persistent memory across different conversations. This allows it to learn from experience and build a deepening model of the user. Because the agent is highly extensible, developers can add custom tools to its setup using standard markdown instruction files.

When the agent executes content generation tasks, it must write text that sounds natural and human. The agent can use an external AI detector to verify its output before presenting it. By integrating the ZeroGPT API directly, the agent can check the generated text for AI signatures in real time. If the detector flags the text as machine-generated, the agent can edit the content to improve its quality. This automated verification cycle ensures that the output is polished before it reaches human review, reducing manual editing times.

Automating the verification step prevents the agent from publishing low-quality or repetitive text. If the agent operates without an external feedback loop, it cannot assess the quality of its own outputs. Connecting the agent to a dedicated detection endpoint resolves this limitation, providing a reliable metrics-driven framework for content quality control. In addition, developers can build multi-agent workflows where a primary agent delegates writing tasks and a subagent runs the verification checks, keeping the primary agent context focused.

To initialize the connection, you must first obtain an API key from the ZeroGPT developer dashboard. The API key authorizes your HTTP requests. The Hermes Agent reads credentials from its local environment configuration. The agent stores environment variables in its root configuration directory.

To connect the agent, follow these configuration steps:

1. Obtain your API key by creating an account on the ZeroGPT developer dashboard.
2. Add the key to the local environment file by opening ~/.hermes/.env and adding the variable:

   ZEROGPT_API_KEY="your_api_key_here"
  

3. Initialize the HTTP request headers in your connection script. The header key is ApiKey and the value is your secret token.
4. Set the HTTP request method to POST and the endpoint URL to:

   https://api.zerogpt.com/api/v1/detectText
  

5. Structure the JSON request body containing the input_text field, which holds the text to analyze.
6. Post the JSON payload to the endpoint and capture the JSON response.

The ZeroGPT API requires a text sample of at least 100 words to provide an accurate probability score.

Here is the JSON request body structure:

{
  "input_text": "The text content generated by the agent that needs to be analyzed for AI signatures goes here."
}

The server returns a JSON response containing the detection results. The response includes the following fields:

• success: A boolean indicating if the request succeeded.
• is_human_written: A percentage representing the likelihood that the text was written by a human.
• is_gpt_generated: A percentage indicating the probability that the text was generated by AI.
• feedback_message: A text description summarizing the analysis results.

Here is an example response payload from the API:

{
  "success": true,
  "data": {
    "is_gpt_generated": 85.5,
    "is_human_written": 14.5,
    "feedback_message": "Your text is AI generated/Written by AI"
  }
}

By extracting these fields, the agent can read the AI probability score. If the is_gpt_generated percentage exceeds a configured threshold, the agent can trigger editing steps to rewrite the text.

The Hermes Agent uses the agentskills.io standard to define custom skills. A skill is a directory containing a SKILL.md file and associated scripts. The SKILL.md file provides instructions that teach the agent when and how to use the skill. The frontmatter of the markdown file contains the name and description of the skill.

Create a directory named zero-gpt-detector inside ~/.hermes/skills/ to hold the configuration. Inside this directory, create the SKILL.md file.

Here is the structure for the SKILL.md file:

---
name: zero-gpt-detector
description: Analyzes text using the ZeroGPT API to determine the probability of AI generation.
version: 1.0.0
requires:
  - requests
---

### ZeroGPT AI Detector Skill

Use this skill to verify if text was written by an AI model.

**Instructions:**

1. Retrieve the text to be analyzed from the agent workflow.
2. Run the detection script, passing the text as an argument.
3. Read the output JSON to check the AI probability percentage.
4. Report the results to the user.

To execute the request, write a Python script named detector.py in the same directory. The script reads the API key from the environment and sends the text to the endpoint.

Here is the complete Python implementation:

import os
import sys
import requests

def analyze_text(text):
    api_key = os.getenv("ZEROGPT_API_KEY")
    if not api_key:
        print('{"error": "API key not found in environment."}')
        sys.exit(1)
        
    url = "https://api.zerogpt.com/api/v1/detectText"
    headers = {
        "ApiKey": api_key,
        "Content-Type": "application/json"
    }
    payload = {
        "input_text": text
    }
    
    try:
        response = requests.post(url, json=payload, headers=headers, timeout=15)
        response.raise_for_status()
        data = response.json()
        if data.get("success"):
            results = data.get("data", {})
            return {
                "success": True,
                "is_gpt_generated": results.get("is_gpt_generated", 0.0),
                "is_human_written": results.get("is_human_written", 0.0),
                "feedback_message": results.get("feedback_message", "")
            }
        else:
            return {"error": "API returned success false."}
    except requests.exceptions.RequestException as e:
        return {"error": str(e)}

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print('{"error": "No input text provided."}')
        sys.exit(1)
    
    input_text = sys.argv[1]
    import json
    print(json.dumps(analyze_text(input_text)))

When the script runs, it outputs a JSON string. The Hermes Agent parses this JSON to read the values. If the is_gpt_generated percentage is high, the agent can rewrite the text. Developers can test the script by running:

python detector.py "Insert your text here to test the detector."

If the execution fails due to a missing requests package, install it in your local environment. This custom tool allows the agent to run the detector programmatically during any writing task.

Persist Hermes Agent outputs in intelligent workspaces

Provide your Hermes Agent with persistent workspace storage, per-file version history, and direct MCP tool connections. Retrieve files via semantic search and build automated pipelines. Start your 14-day free trial today.

Start 14-Day Trial

When deploying autonomous agents, managing the files they read and write is a primary challenge. Storing files locally isolates them on a single machine, preventing collaboration. Using AWS S3 buckets provides durability but requires complex integration code and lacks a user-friendly interface. Google Drive offers shared access but lacks native agent automation features and does not support real-time co-editing for software agents.

Fastio provides a shared workspace environment where humans and software agents collaborate on the same files, shares, and workflows. Instead of buying individual seats, organizations use usage-based credits. This makes it affordable to run agents that perform high-volume file operations. Plans include Starter at $29 monthly, Business at $99 monthly, and Growth at $299 monthly. Every organization starts with a 14-day free trial that requires a credit card. An agent can sign up free, then hands off to a human who creates or joins an org and starts the trial.

By using Fastio as the persistent storage layer for your Hermes Agent, you gain several capabilities:

File Version History: Fastio tracks the full version history for every file. If the agent writes an incorrect draft or code version, team members can inspect the changes and restore previous versions.

Subagent File Isolation: When the agent launches subagents for complex workflows, you can isolate their file systems. Creating dedicated folder permissions inside the workspace keeps their file activities organized.

Intelligence Mode: When Intelligence Mode is enabled, Fastio automatically indexes all workspace files. The agent and human team members can run Hybrid Search, combining full-text matching with semantic retrieval to find specific documents.

Messaging Gateway Handoff: The agent can write its analysis reports directly to the workspace, generate sharing links, and send them to humans via Telegram or email.

To configure your agent to read and write files in Fastio, use the Fastio MCP server. The server exposes a consolidated MCP toolset that allows agents to interact with folders, read files, and trigger workflows. For detailed setup guides, consult the Fastio Developer Storage page.

Deploying workspace environments for client delivery requires a clean handoff process. Traditional file sharing methods require manual folder permissions and email invitations. This makes it difficult to transfer the complete ownership of the file context and associated agent tools.

Fastio resolves this through ownership transfer. An agent can register a free account, build the workspaces, and configure the folders. Once the setup is complete, the agent generates a claim link to transfer the organization to a human. When the human accepts the link, they select a plan to start their 14-day free trial that requires a credit card. Billing then transitions to the human owner, while the agent retains its scoped programmatic access.

If you encounter errors during the integration, check these troubleshooting points:

Stdio Server Connection Errors: If the Hermes Agent log displays connection failures, verify that the local python environment has the mcp package installed. Inject the package into your hermes-agent installation by running:

pipx inject hermes-agent mcp

API Key Validation Issues: If the ZeroGPT API returns authentication errors, check that your ~/.hermes/.env file is formatted correctly. Verify that the variable name is ZEROGPT_API_KEY and that the value matches the key in your developer dashboard.

Payload Size and Rate Limits: The ZeroGPT API has rate limits and text length boundaries. If the agent attempts to analyze a text sample that is too long, the API may return an error. Build a text-splitting routine in your python script to divide long documents into smaller chunks before posting them.

Fastio provides the visual workflow engine to build automated pipelines. For example, a workflow can trigger the ZeroGPT API skill whenever a new document is uploaded to the workspace, creating a verified chain of custody. For details on how to build these automations, read the Fastio Workflows Page.