How to Connect Hermes Agent to the GPTZero API

When GPTZero marks a prediction with high confidence, official developer guidance states error rates are below 1%. That single threshold is why authenticity checks keep showing up in agent pipelines: teams want machine-scored text before content ships to a classroom, a hiring queue, or a client portal. The GPTZero API lets applications score text for AI generation probability at document and sentence level so agents can automate those checks instead of pasting into a dashboard.

Search demand for the integration surface is real but still early. DataForSEO US estimates for "gptzero api" sit near 140 monthly searches, keyword difficulty 4 of 100, and CPC about $7.88. Most public posts still answer with a lone curl against https://api.gptzero.me/v2/predict/text. They rarely show how an autonomous agent loads the call as a reusable skill, wires secrets safely, and stores the JSON report where a human can audit it.

Nous Research Hermes Agent is an open-source (MIT) autonomous agent, not a hosted SaaS copilot. Official docs describe MCP for external tools and a skills system compatible with the agentskills.io standard. Skills live under ~/.hermes/skills/ with progressive disclosure so the agent loads full procedures only when needed. MCP servers are declared in ~/.hermes/config.yaml under mcp_servers, with stdio and HTTP transports, env isolation for subprocesses, and optional per-server tool filters. That is the natural place to hang a GPTZero AI detector API call.

The rest of this article walks a five-step connect path (API key, environment, skill or MCP, test call, store report), then covers response fields, report handoff, and production edge cases. Fast.io enters only as one durable workspace option for the report handoff layer, after local disk and object storage.

Follow these five steps in order. You can stop after a successful test call if you only need local CLI validation; production pipelines should complete step 5 so reports outlive the agent session.

1. Create a GPTZero API key

Open the GPTZero developer flow at gptzero.me/developers and issue a key from the app API settings. GPTZero documents the primary text endpoint as a POST to https://api.gptzero.me/v2/predict/text with JSON body fields document and optional version, plus headers Accept, Content-Type, and x-api-key. Treat the key like any production secret: one environment per stage, rotate on staff change, never commit it to a skill file or git history.

Official API privacy notes matter for policy reviews: GPTZero states it does not store or collect documents passed into API calls. Dashboard traffic is a different path; do not mix the two when you write data-handling notes for legal or education stakeholders.

2. Put the key in Hermes environment config

Hermes skills can declare required environment variables and prompt for them on first load in the local CLI. Messaging gateways will not ask for secrets in chat; they tell you to use local setup or ~/.hermes/.env. For GPTZero, store something like:

Example entry for ~/.hermes/.env (keep this file out of git):

GPTZERO_API_KEY=your_key_here

Declared skill env vars pass through to execute_code and terminal sandboxes when the skill loads. That is cleaner than baking the key into a shell one-liner the model can echo later. If you also use Fast.io MCP or other servers, keep their tokens as separate env names so blast radius stays small.

3. Wire a skill or an MCP-facing wrapper

You have two practical shapes. Most teams start with a skill because GPTZero is a simple REST POST, not a packaged MCP product.

Skill path (recommended first). Create a folder under the skills root and author a SKILL.md that follows Hermes frontmatter rules (short description, when-to-use, procedure, pitfalls, verification). Example skeleton:

---
name: gptzero-detect
description: Score text with the GPTZero AI detector API and return classification JSON.
version: 1.0.0
platforms: [macos, linux]
metadata:
  hermes:
    tags: [gptzero, ai-detector, authenticity]
    category: quality
---

When to Use:
Score drafts, submissions, or agent-written prose before publish or human review.

Procedure:
1. Read the target text or file path from the user.
2. POST to https://api.gptzero.me/v2/predict/text with x-api-key.
3. Return document_classification, class_probabilities, confidence_category, and sentence highlights.
4. Write a timestamped JSON report to the agreed output path.

Pitfalls:
- Short samples score less reliably than longer prose.
- Treat MIXED as review-needed, not automatic rejection.
- Never print the API key in chat transcripts.

Verification:
A known human sample should not force AI_ONLY with high confidence on ordinary prose.

Put a small Python helper beside the skill if you want deterministic HTTP handling:

import json
import os
import sys
import urllib.request

def predict(document: str) -> dict:
    key = os.environ.get("GPTZERO_API_KEY")
    if not key:
        raise RuntimeError("GPTZERO_API_KEY is not set")
    body = json.dumps({"document": document}).encode("utf-8")
    req = urllib.request.Request(
        "https://api.gptzero.me/v2/predict/text",
        data=body,
        headers={
            "Accept": "application/json",
            "Content-Type": "application/json",
            "x-api-key": key,
        },
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=60) as resp:
        return json.loads(resp.read().decode("utf-8"))

if __name__ == "__main__":
    path = sys.argv[1]
    with open(path, "r", encoding="utf-8") as f:
        print(json.dumps(predict(f.read()), indent=2))

Hermes can also turn a working chat procedure into a skill with /learn after you walk through one successful call. Keep write-approval gates on if you do not want the agent to edit skills without review.

MCP path. Hermes MCP docs show HTTP servers under mcp_servers with url and headers, and stdio servers with command, args, and env. There is no official GPTZero-hosted MCP catalog entry in the Hermes docs as of this writing. If your team already runs an internal MCP that wraps vendor HTTP APIs, point Hermes at that server and whitelist only the predict tool. Example shape for a your wrapper (not a GPTZero product):

mcp_servers:
  authenticity:
    url: "https://mcp.internal.example.com/gptzero"
    headers:
      Authorization: "Bearer ${INTERNAL_MCP_TOKEN}"
    tools:
      include: [predict_text]

Hermes registers MCP tools as mcp_<server>_<tool>. After config changes, reload MCP from the running session with /reload-mcp as documented.

4. Run a test call from Hermes

Start a chat session and ask for a narrow task:

Load the gptzero-detect skill. Score the file ./samples/human-blog.txt
and print only document_classification, confidence_category, and class_probabilities.

Confirm the response includes document_classification with one of HUMAN_ONLY, MIXED, or AI_ONLY. Official FAQ text also describes class_probabilities keys human, ai, and mixed, plus confidence_category of high, medium, or low. Sentence-level highlighting is available to API users via highlight_sentence_for_ai. Keep a golden set: one human sample, one clearly AI sample, one deliberately mixed sample.

5. Store the report for human review

Do not leave scores only in the agent transcript. Write a JSON file named with source id, UTC timestamp, and classification, for example reports/2026-07-16T14-22Z_essay-42_MIXED.json. Persist that file somewhere reviewers already open: a team folder on disk, an S3 prefix, Google Drive, or a shared intelligent workspace. The next section covers how to read the fields so the report is actionable, not just archived.

Keep GPTZero reports where reviewers can open them

Give Hermes Agent a shared Fast.io workspace for detection JSON, source drafts, and human approvals, with MCP access and version history. Every org starts with a 14-day free trial.

Start 14-Day Trial

Most integration bugs are interpretation bugs. Teams wire the POST correctly, then overreact to a single label.

Document classification. GPTZero documents three document_classification values: HUMAN_ONLY, MIXED, and AI_ONLY. MIXED means the model treats the piece as part human and part AI-like writing, not "definitely cheating." Official FAQ guidance for API consumers is explicit that sentence highlights show where AI-like writing contributed when the document is MIXED or AI_ONLY. Sentence-level labels alone should not be the only signal that an entire essay is AI-generated.

Class probabilities. The class_probabilities object holds scores for human, ai, and mixed. The probability tied to the predicted class is the detector's estimate of how often it is correct on similar documents. A 0.90 on the winning class is a confidence statement about the classifier, not a word-count of AI text.

Confidence category. confidence_category is high, medium, or low. GPTZero's developer FAQ states that when confidence is high, error rates are below 1%. FAQ documentation also describes tuned high-confidence behavior where the large majority of human articles stay classified human and the large majority of AI articles stay classified AI. Use medium and low confidence as automatic "send to human review" flags in Hermes workflows.

Sentence highlights. highlight_sentence_for_ai helps reviewers jump to suspect spans. In an agent pipeline, store both the document label and the highlight list. Reviewers open the report, open the source draft, and compare. That is more defensible than a chat message that only says "AI detected."

Accuracy context for product owners. GPTZero's developer materials cite independent and internal benchmarking that outperforms competitors on mixed documents at 96.5% accuracy, with a false positive rate under 1% in their published positioning. Still treat detection as evidence for a conversation, not an automated punishment system. That stance matches GPTZero's own educator guidance and keeps your Hermes automation on safer policy ground.

Practical Hermes policy table you can encode in the skill:

• HUMAN_ONLY + high → allow publish path or mark green
• MIXED (any confidence) → open a review task, attach highlights
• AI_ONLY + high → block auto-publish, require human decision
• any low confidence → human review even if the label looks clean

Once the basic call works, skill design decides whether the integration survives real traffic.

Input contracts. Decide whether the skill accepts raw text, a local path, a workspace URL, or all three. Cap payload size in the skill procedure so Hermes does not try to score a 200-page PDF as one string. For long documents, chunk by section, score each chunk, and store a rollup plus per-chunk classifications. GPTZero notes accuracy improves with longer text; very short snippets are noisier.

Idempotency. Hash the input text and store content_sha256 next to the score. If the same hash already has a report less than N days old, reuse it. That cuts API spend when agents reprocess the same draft across retries.

Failure modes. Network timeouts, 401 invalid keys, 429 rate limits, and empty documents all need structured errors. Return JSON like {"ok": false, "error": "http_429", "retry_after_seconds": 30} so a parent agent or cron can back off without inventing a narrative.

Subagent isolation. Hermes can spawn isolated subagents for parallel work. A common pattern: parent agent drafts content, a child agent runs only the GPTZero skill with a narrow toolset, then returns the report. Keep the API key available to the child through Hermes env passthrough rather than pasting it into the parent prompt.

Slash command habit. Installed skills surface as slash commands. After the skill is named gptzero-detect, operators can run /gptzero-detect score ./draft.md in CLI or messaging gateways Hermes already supports. Stack skills when useful, for example a lint skill plus detection in one message, without exceeding Hermes' documented multi-skill limit.

Security. Prefer skill-declared env vars over free-form secrets in chat. For MCP wrappers you control, whitelist tools and set tools.prompts: false and tools.resources: false if those surfaces are unused. Hermes MCP security notes emphasize that stdio servers only receive explicitly configured env plus a safe baseline, which reduces accidental secret leakage compared to inheriting a full shell.

Detection without durable storage is a demo. Detection with a report path is an audit trail.

Local disk works for a single operator on a laptop or VPS. Write under a project reports/ directory and back it up with your normal host strategy. This breaks when Hermes runs on disposable Docker, Modal, or Singularity backends and the container goes away.

Object storage (S3, GCS, Azure Blob) is the classic scale path. Hermes can upload via CLI tools if your runtime has credentials. You get durability and lifecycle policies. You do not automatically get human-friendly review UI, semantic search over report text, or agent-to-human ownership transfer.

Shared cloud drives (Drive, Dropbox, OneDrive, Box) help non-technical reviewers open files. Agents often struggle with OAuth and path drift unless you standardize a folder and naming scheme.

Fast.io as the review workspace. For agentic teams, Fast.io workspaces sit between raw object storage and consumer drives. Agents and humans share the same org-owned workspace. Every file keeps version history. Permissions can sit at org, workspace, folder, or file level. An append-only audit log records activity without relying on chat memory. Intelligence Mode indexes files for hybrid search and citation-backed chat once enabled, so a reviewer can ask "which MIXED reports from this week mention the admissions essay" without grepping JSON by hand.

A practical handoff loop:

1. Hermes scores the draft via the GPTZero skill.
2. Hermes writes source.md plus report.json into a workspace folder such as authenticity/inbox/.
3. Optionally create a Metadata View that extracts fields like document_classification, confidence_category, source_id, and scored_at into a filterable grid.
4. Open a task or approval for human review when classification is MIXED or AI_ONLY, or confidence is not high.
5. After decision, move files to authenticity/resolved/ so inbox stays empty.

Connect Hermes to Fast.io the same way you connect other remote MCP servers: Streamable HTTP at /mcp and legacy SSE at /sse, documented under storage for agents. Keep GPTZero and Fast.io credentials separate. An agent can create an account, then hand the organization to a human who starts the 14-day free trial (credit card required). Plans start at Solo $29/mo, Business $99/mo, and Growth $299/mo. Real workspace work always runs on a paid org subscription after the trial.

If you already standardize on S3 for cold storage, you can still use Fast.io for the human review surface: agent uploads the report to the workspace for collaboration, then archives a copy to S3 for long retention.

Ship the integration only after you can answer these operational questions.

Rate limits and batching. GPTZero product packaging ties API access to paid plans rather than a freestanding unlimited tier. Budget word volume, queue submissions, and avoid scoring every keystroke. Batch on document save or pull-request open, not on every agent thought.

Language and domain fit. GPTZero FAQ guidance stresses stronger performance on longer English prose and lower reliability on short, heavily edited, or highly procedural text. If Hermes scores code comments, JSON configs, or five-sentence tweets, expect noisier labels. Gate the skill so it only runs on eligible content types.

False positives and ESL risk. GPTZero publishes work on reducing ESL false positives and positions high-confidence error rates as low. Still, your Hermes skill should never auto-punish. Route ambiguous cases to humans with the full report attached.

Key rotation. When staff leave, rotate GPTZERO_API_KEY in ~/.hermes/.env and any CI secrets. Restart or reload sessions so children pick up the new value.

MCP tools missing. If you used an MCP wrapper and tools do not appear, Hermes docs list common causes: connect failure, discovery failure, include/exclude filters, enabled: false, or utility capabilities the server does not support. Run /reload-mcp after config edits.

Skill not loading. Confirm the skill lives under ~/.hermes/skills/ (or a configured external dir), frontmatter name and description are valid, and platform filters match the host OS. Use progressive disclosure checks: list skills, then view the GPTZero skill before calling it.

Empty or malformed responses. Log HTTP status and a truncated body (never log the full API key header). Retry once on 5xx with backoff. On 4xx, fail closed and ask a human.

End-to-end acceptance test. Before production:

1. Human sample → expect not AI_ONLY with high confidence on ordinary prose.
2. Synthetic AI sample → often AI_ONLY or MIXED depending on length and editing.
3. Mixed sample → MIXED with non-empty highlights when the API returns them.
4. Report file appears in the chosen store with hash, timestamp, and classification.
5. Reviewer can open the report without SSH into the agent host.

When those five pass, the Hermes Agent GPTZero path is ready for scheduled or event-driven use. Pair it with webhooks or cron only after the skill is boringly reliable on the golden set.