How to Intersect Turnitin AI Detection Checker with Hermes Agent Workflows

Over 15,000 institutions use Turnitin worldwide to enforce academic and editorial integrity, and the company claims over 98% confidence in detecting AI-generated text [Turnitin AI Writing Detection Page]. However, integrating this enterprise check into automated document pipelines remains a major challenge for developers because Turnitin does not provide an open, unauthenticated API for third-party scripts. Most online guides focus on students attempting to bypass AI detection. This article addresses developers who want to build automated validation agents using Nous Research Hermes Agent.

A Turnitin AI detection checker workflow integrates Turnitin's similarity and AI detection flags into automated document pipelines, often utilizing custom wrappers or scripts. Nous Research Hermes Agent is an open-source, MIT-licensed agentic framework that executes complex, multi-step workflows on local or remote servers. The official NousResearch/hermes-agent repository and documentation do not feature any integrations, skills, or instructions for connecting to Turnitin's enterprise API or automating Turnitin checks. You can learn more about deploying agent configurations by visiting the Nous Research Hermes Agent GitHub repository. To bridge this gap, developers must implement custom document processing pipelines that pass draft content to Turnitin, extract the results, and store the verified text. This setup establishes an automated verification loop, protecting content quality before publication.

While other general-purpose tools like Grammarly's AI Detector offer public access for simple ChatGPT and Gemini verification [Grammarly AI Detector Page], Turnitin remains the standard for institutional verification. Developers building workflows for universities or enterprise publishers must integrate with Turnitin's ecosystem.

To connect Hermes Agent to Turnitin, you must create a custom skill that conforms to the agentskills.io standard. Custom skills are self-contained folders that contain a configuration markdown file and a scripts directory. The agent scans these external directories at startup to register new capabilities. Since Turnitin does not support built-in connections in the Hermes framework, defining this custom skill is the only way to establish a programmatic link.

By defining a dedicated skill, you isolate the integration logic from the agent's core code. The agent can now call the python runner script whenever it needs to scan a document. This separation of concerns allows developers to update the Turnitin API parameters or browser-automation selectors without modifying the core Hermes logic. It also ensures that other subagents can reuse the verification capabilities across different workspaces.

~/.hermes/skills/
└── turnitin-detector/
    ├── SKILL.md
    └── scripts/
        └── turnitin_api_check.py

---
name: turnitin_detector
description: Runs draft text through Turnitin's AI detection checker using API calls or browser automation.
version: 1.0.0
---

### Turnitin AI Detector Integration

Use this skill when you need to analyze a draft's AI probability score before committing it to a workspace.

### Usage Instructions

1. Pipe the content draft into the Python helper script:
   python scripts/turnitin_api_check.py draft.txt

2. The script returns a JSON response containing the status and the ai_score.

3. Parse the ai_score percentage:
   - If the score is below twenty percent, the content is ready for upload.
   - If the score is twenty percent or higher, trigger the rewriting routine to humanize the draft.

skills:
  external_dirs:
    - "~/.hermes/skills/turnitin-detector"
  auto_load: true

TURNITIN_API_KEY="your_enterprise_api_key_here"
TURNITIN_BASE_URL="https://api.turnitin.com/v1"

Turnitin supports two primary integration paths for developers: the Learning Tools Interoperability (LTI) standard for Learning Management Systems (LMS) and the Turnitin Core API for custom Similarity and Originality products. While the Turnitin Core API provides programmatic endpoints to submit documents and retrieve scores, organizations without an enterprise API license must use a browser-automation fallback to submit drafts.

A developer can handle these two paths using a structured, five-step integration loop:

1. Submission: The script uploads the document to the Turnitin Core API similarity endpoint. If the enterprise API is unavailable, the script triggers a browser-automation fallback using Playwright to upload the file.

2. Polling: The script enters a polling loop, checking the report status endpoint every thirty seconds until the analysis finishes.

3. Extraction: The script parses the returned report data to retrieve the similarity score and the AI writing indicator score.

4. Threshold check: The script compares the AI score against your organization's quality threshold, typically set to twenty percent.

5. Actionable output: If the AI score is below the threshold, the script returns a success status. If the score is higher, it returns the flagged text blocks to the agent's context window for iterative rewriting.

The following Python script illustrates how to implement this integration loop:

"""Turnitin integration script for Hermes Agent workflows"""
import os
import sys
import json
import time
import requests
from playwright.sync_api import sync_playwright

def submit_to_turnitin_api(file_path, api_key, base_url):
    """Submit document to Turnitin Core API similarity endpoint"""
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    payload = {
        "title": os.path.basename(file_path),
        "submission_type": "file"
    }
    try:
        response = requests.post(
            f"{base_url}/submissions",
            headers=headers,
            json=payload,
            timeout=30
        )
        if response.status_code == 201:
            submission_id = response.json().get("id")
            ### Upload the physical file
            upload_url = response.json().get("upload_url")
            with open(file_path, "rb") as f:
                upload_resp = requests.put(upload_url, data=f, timeout=60)
            if upload_resp.status_code == 200:
                return submission_id
        return None
    except requests.RequestException:
        return None

def run_browser_fallback(file_path, email, password):
    """Fallback flow using Playwright browser automation"""
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        context = browser.new_context()
        page = context.new_page()
        try:
            page.goto("https://www.turnitin.com/login_page.asp", timeout=30000)
            page.fill("input[name='email']", email)
            page.fill("input[name='password']", password)
            page.click("input[type='submit']")
            page.wait_for_selector(".assignment-list", timeout=15000)
            ### Submit file
            page.click("text=Submit File")
            page.fill("input[name='title']", os.path.basename(file_path))
            page.set_input_files("input[type='file']", file_path)
            page.click("input[type='submit']")
            page.wait_for_selector(".report-score", timeout=30000)
            score_element = page.query_selector(".report-score")
            score_text = score_element.text_content() if score_element else "0%"
            return {"status": "success", "ai_score": score_text.strip()}
        except Exception as e:
            return {"status": "error", "message": str(e)}
        finally:
            browser.close()

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print(json.dumps({"status": "error", "message": "Missing file path"}))
        sys.exit(1)
        
    target_file = sys.argv[1]
    api_token = os.environ.get("TURNITIN_API_KEY")
    api_url = os.environ.get("TURNITIN_BASE_URL")
    
    sub_id = None
    if api_token and api_url:
        sub_id = submit_to_turnitin_api(target_file, api_token, api_url)
        
    if sub_id:
        ### Poll for results
        headers = {"Authorization": f"Bearer {api_token}"}
        for _ in range(20):
            time.sleep(30)
            resp = requests.get(f"{api_url}/submissions/{sub_id}", headers=headers, timeout=10)
            if resp.status_code == 200:
                data = resp.json()
                if data.get("status") == "COMPLETE":
                    ai_score = data.get("ai_writing_score", "0%")
                    print(json.dumps({"status": "success", "ai_score": ai_score}))
                    sys.exit(0)
        print(json.dumps({"status": "error", "message": "Polling timed out"}))
    else:
        ### Fallback to browser automation
        login_email = os.environ.get("TURNITIN_EMAIL")
        login_pass = os.environ.get("TURNITIN_PASSWORD")
        if login_email and login_pass:
            result = run_browser_fallback(target_file, login_email, login_pass)
            print(json.dumps(result))
        else:
            print(json.dumps({"status": "error", "message": "No API keys or fallback login credentials found"}))

This script ensures that the agent receives structured JSON output containing the AI score, regardless of whether the enterprise API or a browser automation fallback is used. The agent then reads this score to decide whether to proceed or refine the text.

Build a turnitin ai detection checker workflow

Deploy an intelligent workspace on Fast.io to secure your automated document verification pipelines, check drafts against Turnitin, and store versioned files. Starts with a 14-day free trial.

Start 14-Day Trial

When running automated document verification pipelines, saving drafts and reports on local disk storage is unreliable because local disks are ephemeral. If your Hermes Agent runs inside serverless containers on platforms like Modal, all files are lost when the instance reboots. Storing reports in Amazon S3 buckets provides durability but requires complex API configurations and lacks real-time co-editing interfaces. Storing documents in Google Drive offers cloud storage but lacks semantic search APIs and version history views for agents.

Fast.io provides a collaborative workspace layer designed for humans and agents. When the Hermes Agent finishes checking a document against the Turnitin AI detection checker, it uploads the draft and the verification report to a Fast.io workspace. For developers seeking to design custom file management flows, the Fast.io Storage for Agents page outlines the full system requirements.

This shared environment provides several benefits for developer workflows:

Per-File Version History: Fast.io preserves the complete version history for every file. If an agent edits a draft during the rewriting loop, human team members can inspect the changes and restore previous versions.

Intelligence Mode: When Intelligence Mode is enabled, the workspace automatically indexes all files. This allows the agent and human team members to use hybrid search to query documents by meaning, in addition to using exact full-text matching.

Metadata Views: Through Metadata Views, developers can transform unstructured document folders into a live database. You describe the columns you want to extract in natural language, and Fast.io designs a schema using fields like Text, Integer, Decimal, Boolean, URL, JSON, and Date & Time. No manual templates or OCR rules are required. Developers can use Metadata Views to parse verification reports, extract AI detection percentages, and organize them into a queryable table. To learn more about setting up structured databases from your files, visit the Metadata Views product page.

By storing files in a shared workspace, you establish an audit trail that makes the content generation process clear and verifiable.

Once you configure your verification pipeline, you can hand off the workspace to a human client or manager using Fast.io ownership transfer. Fast.io has no permanent free plan and no free agent tier. The agent signs up for a free user account, creates the organization, and configures the workspaces. Once the setup is complete, the agent generates a claim link to transfer the organization to a human client.

The human client starts their 14-day free trial, which requires a credit card to activate. Fast.io offers three paid plans:

Starter Plan: For individual developers at $29 per month ($24 per month when billed annually), providing 1 TB of storage and 300,000 usage credits.

Business Plan: For collaborative teams at $99 per month ($83 per month when billed annually), supporting up to 20 seats and providing 10 TB of storage with 1.2 million credits.

Growth Plan: For large deployments at $299 per month ($249 per month when billed annually), supporting up to 50 seats and providing 50 TB of storage with 4.5 million credits.

To compare plans and configure billing limits, visit the Fast.io Pricing page. If you encounter errors during implementation, verify the following configuration settings:

StdioServerParameters Error: If the Hermes Agent log displays a StdioServerParameters name error, the environment is missing the mcp package. Resolve this by injecting the package into your hermes-agent installation:

pipx inject hermes-agent mcp

YAML Syntax Issues: Use a yaml validator or run the config check CLI command to ensure that your API keys and configuration files are correctly formatted:

hermes config check

Network Timeout Errors: If the Playwright script fails to load the login page, verify your proxy settings and ensure that your user-agent string is configured correctly to avoid bot detection systems. For details on standard LLM metadata formats, refer to the fast.io/llms.txt configuration guide.

By checking these settings, you ensure that your automated content verification pipeline runs reliably without manual interruptions.