How to Integrate an AI Detector API with Hermes Agent

The commercial keyword "ai detector api" draws only about 50 monthly US searches, yet carries a CPC near $9.97 according to DataForSEO keyword data refreshed for this article. That pricing is the signal. Buyers are not shopping for another paste-box UI. They need programmatic classification they can drop into agent pipelines before publish, handoff, or client delivery.

An AI detector API exposes programmatic classification of text or code as human, AI, or mixed so automated agents can gate publishing and review workflows. That definition is simple. The hard part is what happens after the HTTP response lands. Vendor docs stop at authentication headers and a JSON payload. They rarely cover agent orchestration, subagent handoff, or where the detection report should live so a human can reopen it next week.

Nous Research Hermes Agent is open source (MIT) and runs on infrastructure you control: local machines, Docker, SSH hosts, and serverless backends such as Modal or Daytona. Official docs describe a broad built-in tool registry (web, terminal, browser, memory, delegation, and more), skill-driven procedures compatible with the agentskills.io standard, and MCP as the clean path for tools that live outside Hermes. There is no first-party "Hermes AI detector" product. Third-party AI detection APIs plug in as external tools or skill-driven HTTP calls, which is the correct integration surface.

This guide treats detector APIs as workflow infrastructure for Hermes Agent: choose capability-rich vendors, expose them through MCP or a thin skill, delegate high-volume checks to subagents, normalize scores so "0.82" means the same thing next quarter, and store durable reports where both agents and people can audit decisions. For workspace patterns around agent-readable files, see storage for agents and the Fast.io MCP skill.

Browser detectors optimize for a human scanning a single page. Agent workflows optimize for machine-readable structure, retries, and policy gates. Before you pick a vendor, score the API against the capabilities agents actually call.

Capabilities agents need

Document classification: A stable enum such as human, AI, or mixed (GPTZero returns HUMAN_ONLY, MIXED, and AI_ONLY with class probabilities).

• Confidence signal: A band or score the agent can map to allow, review, or block without inventing thresholds ad hoc.
• Sentence or span highlights: Offsets or sentence lists so reviewers jump to the risky passage instead of re-reading the whole draft.
• Batch or multi-document submit: One request path for a folder of drafts, not N serial round-trips for every file.
• Webhooks or async completion: For long documents and bulk jobs so the agent can park work and resume when results arrive.
• Stable error codes and rate limits: Enough detail for retry/backoff without parsing HTML error pages.
• Privacy posture: Clear storage rules for API traffic (GPTZero states it does not store documents submitted through its API).

How common vendors map

GPTZero's public developer docs show a POST to https://api.gptzero.me/v2/predict/text with an x-api-key header. Responses include document classification, class probabilities, a confidence category (high, medium, or low), and sentence-level highlights for AI spans. That surface is a strong fit for agent gates because the enum is explicit and spans support human review.

Copyleaks documents AI text detection responses with classification labels, probability-style fields, and section-level breakdowns, plus async flows that complete via webhook and export endpoints. That pattern fits bulk editorial pipelines more than single-shot CLI checks.

Originality.ai positions its API for content operations teams that also need plagiarism and related editorial checks alongside AI detection. It is a reasonable choice when detection is one step inside a broader originality workflow rather than a pure classification microservice.

Winston AI markets developer-facing AI content detection with API keys and credit-based usage. Treat any accuracy percentage on a marketing page as a vendor claim until you validate it on your own corpus.

None of these products is a built-in Hermes tool. Any of them can sit behind MCP or a skill if you keep secrets out of chat and normalize their JSON into one internal schema.

Official Hermes docs put MCP and skills at the center of external capability. MCP is the adapter layer: Hermes remains the agent, MCP servers contribute tools, Hermes discovers those tools at startup or reload, and you control how much of each server the model can see. Skills are on-demand procedure docs the agent loads when needed, following progressive disclosure so the full procedure is not always in context.

Preferred path: thin MCP server in front of the vendor

Build or adopt a small MCP server that wraps your chosen AI detector API. Hermes can attach it as a local stdio process or a remote HTTP MCP endpoint. A minimal stdio entry in ~/.hermes/config.yaml looks like this pattern from the official MCP guide (swap the command for your detector bridge):

mcp_servers:
  ai_detector:
    command: "npx"
    args: ["-y", "your-ai-detector-mcp"]
    env:
      DETECTOR_API_KEY: "${DETECTOR_API_KEY}"
    tools:
      include: [scan_text, scan_file]
      prompts: false
      resources: false

Hermes registers MCP tools with a server prefix, for example mcp_ai_detector_scan_text. After config changes, reload with /reload-mcp or restart the session so discovery runs again. Prefer an allowlist (tools.include) over exposing every mutating helper the bridge might later add.

For a remote bridge:

mcp_servers:
  ai_detector:
    url: "https://mcp.example.com/detector"
    headers:
      Authorization: "Bearer ${DETECTOR_MCP_TOKEN}"
    tools:
      include: [scan_text, get_report]

Keep API keys in ~/.hermes/.env, not in chat history. Official Hermes MCP security notes emphasize that stdio servers receive only configured env vars plus a safe baseline, which reduces accidental secret leakage.

Skill path: procedure without a permanent MCP process

When you do not want a long-lived MCP subprocess, encode the integration as a skill under ~/.hermes/skills/. Skills use a SKILL.md with frontmatter (name, description, optional required_environment_variables) and a procedure the agent follows. Declare the detector key so Hermes can prompt for it on local CLI load rather than pasting secrets into Telegram or Discord:

---
name: ai-detector-gate
description: Run AI detection before publish and write a normalized report
version: 1.0.0
required_environment_variables:
  - name: GPTZERO_API_KEY
    prompt: GPTZero API key
    help: Create a key in the GPTZero developer dashboard
    required_for: full functionality
---

# AI detector gate

## When to Use

Before publishing agent-written drafts, client deliverables, or share packages.

## Procedure
1. Read the target file from the workspace path provided by the user.
2. Call the detector HTTP API with the file text.
3. Normalize the response into the team report schema.
4. Write `detection-report.json` next to the draft.
5. If classification is AI_ONLY or MIXED with low confidence, open a review task instead of publishing.

You can author that skill by hand or with Hermes /learn pointed at vendor docs. Skills Hub scanning applies to third-party installs; keep detector skills you wrote yourself under local control and review any community skill that would exfiltrate document text.

Direct HTTP from a tool-capable session

For a quick prototype, Hermes can call the vendor with terminal or code-execution tooling. GPTZero's documented shape:

curl --request POST \
  --url https://api.gptzero.me/v2/predict/text \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "x-api-key: ${GPTZERO_API_KEY}" \
  --data '{"document":"Paste the draft text here"}'

Prototypes are fine. Production gates should still normalize the JSON and write a report file, not leave classification buried in a chat transcript.

Keep Hermes detector reports next to the draft

Use a shared Fast.io workspace for drafts, raw vendor JSON, and normalized detection reports your agents can write through MCP and your editors can approve in the same place. Start with a 14-day free trial.

Start 14-Day Trial

Hermes Agent supports delegate_task for child agents with isolated context, restricted toolsets, and their own terminal sessions. Only the child's final summary re-enters the parent context. That design is a natural fit for AI detection: the parent generates or edits content, a child runs the detector with a tight toolset, and the parent decides whether to publish based on a structured summary.

Recommended subagent pattern

Pass everything the child needs in goal and context. Subagents start with a blank conversation. They do not inherit prior chat.

delegate_task(
    goal="Run AI detection on the draft and return a normalized gate decision",
    context="""
Draft path: /workspace/releases/q3-launch-post.md
Detector: GPTZero text API via mcp_ai_detector_scan_text
Policy:
- HUMAN_ONLY + high confidence -> allow
- MIXED -> require human review
- AI_ONLY -> block publish, request rewrite
- medium/low confidence -> require human review
Write detection-report.json beside the draft with vendor, timestamps, raw scores, spans.
""",
    toolsets=["file", "mcp-ai_detector"]
)

Official delegation docs default to up to three concurrent children (configurable). Batch several drafts when you need parallel scans, and keep detector secrets available to the child process through the same env wiring the parent uses. Leaf subagents cannot call delegate_task, clarify, or write shared memory, which is desirable for a pure scan worker.

Should AI detection run as a Hermes subagent? For volume and context control, yes. Detection is a bounded classification job that benefits from isolation. Keep the parent free for drafting and human communication. Use the parent (or a human approval step) for final publish authority when confidence is not high.

Normalize scores across vendors

Vendors do not share a single score meaning. GPTZero emits class labels plus probabilities and a confidence category. Copyleaks exposes classification and probability-style fields that need careful reading because some UIs show "percent of document flagged" rather than "confidence the whole document is AI." Originality-style products may mix AI probability with plagiarism signals. If you switch vendors without a normalization layer, thresholds drift and historical reports become incomparable.

Map every vendor into one internal schema before any gate logic runs:

{
  "schema_version": "1.0",
  "vendor": "gptzero",
  "source_path": "releases/q3-launch-post.md",
  "scanned_at": "2026-07-16T12:00:00Z",
  "label": "mixed",
  "ai_probability": 0.61,
  "human_probability": 0.39,
  "confidence": "medium",
  "spans": [
    {"start": 420, "end": 780, "label": "ai", "score": 0.88}
  ],
  "gate": "review",
  "raw_ref": "detection-raw/gptzero-2026-07-16T12-00-00Z.json"
}

A simple normalization policy:

1. Store the vendor raw payload under raw_ref for audit.
2. Convert vendor enums to human | mixed | ai | unknown.
3. Prefer probability fields on a 0-1 scale; if a vendor only returns percent-of-document flagged, keep that in a separate field so it is never confused with confidence.
4. Derive gate only from the normalized fields: allow, review, or block.
5. Version the schema so you can re-interpret old reports after a vendor changes fields.

Policy examples that survive model upgrades

• Marketing blog posts: mixed with high confidence still goes to editor review.
• Client legal memos: any ai span longer than a fixed character threshold forces review, even if the document label is mixed.
• Internal release notes: human with medium confidence may auto-allow, with a weekly sample audit.
• Code comments and README drafts: run detection, but pair it with lint and secret scans rather than treating detection as the only quality gate.

Detectors are probabilistic. GPTZero itself describes detection as a conversation starter rather than a final verdict, and independent accuracy work across the industry routinely shows gaps between marketing claims and third-party benchmarks. Build gates that prefer false "review" over silent auto-publish when stakes are high.

API responses disappear when the process exits. Chat logs are a poor archive for compliance questions six months later. After each scan, write three artifacts next to the draft: the source file version, the vendor raw JSON, and the normalized report. Local disks and temporary containers work for demos. Object storage such as Amazon S3 or a team Drive folder works for bulk archives. Those options rarely give agents and humans the same searchable workspace with permissions, version history, and handoff.

Fast.io is a strong fit when the detection pipeline is part of an agentic content operation. Shared workspaces hold drafts and reports with per-file version history. Intelligence Mode can index reports for semantic search so a reviewer can ask which posts from last month were gated as mixed. Metadata Views on /product/document-data-extraction/ can extract fields such as vendor name, gate decision, AI probability, and review owner into a sortable grid without hand-built OCR rules. Approvals and tasks on /product/approvals/ and /product/tasks/ give humans a place to sign off before a branded share goes out. Agents reach the same files through the Fast.io MCP server (Streamable HTTP at /mcp, legacy SSE at /sse) using consolidated MCP tools rather than ad hoc S3 scripts.

A practical folder layout:

workspace/content-ops/
  drafts/
    q3-launch-post.md
  detection/
    q3-launch-post.report.json
    raw/
      q3-launch-post.gptzero.json
  published/

Workflow outline:

1. Hermes Agent (or a subagent) writes or imports the draft into the workspace.
2. Detector skill or MCP tool scans the draft and writes raw + normalized reports.
3. If gate is allow, continue publish automation.
4. If gate is review or block, create an approval or task, attach the report, and stop publish.
5. After human edit, re-scan and append a new report version instead of overwriting history.

Webhooks help when detector jobs are async. Configure the vendor to notify your service when a bulk scan finishes, then have Hermes or a small worker write the completed report into the workspace. Fast.io webhooks can also react when files change so downstream agents do not need to poll.

Ownership transfer matters for agency and freelance setups: an agent can assemble the workspace, detector wiring notes, and report history, then transfer the organization to a human client while keeping admin access for support. Production workspaces require a paid organization subscription. Every org starts with a 14-day free trial (credit card required) on Solo ($29/mo), Business ($99/mo), or Growth ($299/mo).

Troubleshooting the integration -

MCP tools missing after config edit: Confirm the server is not enabled: false, run /reload-mcp, and check that tools.include did not filter out the scan tool.

• Auth failures only on messaging platforms: Hermes will not solicit secrets over chat for skill env vars. Set keys in ~/.hermes/.env on the host, then reload.
• Subagent returns a vague summary: Put the full draft path, policy thresholds, and required output filenames in context. Subagents do not see parent history.
• Scores disagree across vendors: Expect that. Keep both raw payloads and only gate on the normalized schema after you calibrate on a held-out set of human and AI samples from your domain.
• False positives on ESL or technical writing: Lower auto-block sensitivity, raise human review, and sample-audit rather than treating any single detector as ground truth.
• Report files exist but nobody can find them: Put them in a shared workspace with hybrid search or Metadata Views, not only in the agent session transcript.

When the loop is healthy, Hermes Agent drafts, a detector API classifies, a subagent writes a durable report, and a human only intervenes when the gate demands it. That is the gap vendor API docs still leave open, and it is the workflow this integration is for.