The reasoning.json Protocol

Abstract

Historically, machine-readable web conventions were designed for search engine crawlers. robots.txt controls access. schema.org structures semantic entities. llms.txt provides clean markdown for context windows.

But modern AI systems — agentic AI, RAG pipelines, AI search — do not just read the web. They reason about it. They infer, compare, synthesize, and frequently hallucinate. Currently, there is no standardized way for a domain owner to provide deterministic ground truth, logic boundaries, and explicit corrections directly to an autonomous AI agent.

The Agentic Reasoning Protocol proposes a standardized file located at /.well-known/reasoning.json to act as a machine-readable system prompt, injected directly at the data-retrieval layer.

The Evolution of Machine-Readable Web Conventions

Each generation of the web introduced a new convention to help machines understand content. The Agentic Reasoning Protocol is the next step in this evolution — the first protocol designed not for crawlers or indexers, but for reasoning agents.

Each convention solved a problem of its era. robots.txt controls access. schema.org describes entities. llms.txt feeds context. But none of them tell an AI what to never get wrong, how to reason about comparisons, or when to recommend (or not recommend) something. That is the gap reasoning.json fills.

The Problem

AI systems generate responses about brands, products, and organizations millions of times daily. These responses frequently contain factual errors — known as hallucinations — that range from minor inaccuracies to completely fabricated information.

Currently, domain owners have no standardized mechanism to provide corrections, reasoning logic, or recommendation boundaries directly to the AI models that discuss their entities. They can describe what they are (via schema.org) and provide clean text (via llms.txt), but they cannot provide deterministic reasoning directives.

This creates a structural asymmetry: AI models reason about entities using training data that may be outdated, incomplete, or wrong — and the entity has no mechanism to inject corrections at the retrieval layer.

1. The Specification

The protocol allows domain owners to programmatically define how AI models should interpret their entity. The file MUST be served from the .well-known directory of a domain over HTTPS, as defined by RFC 8615.

It dictates three core reasoning layers:

Layer 1: Identity

The identity object defines the unshakeable core premise of the entity. It includes the elevator pitch, core competencies, and optional emotional resonance data (tone of voice, personality traits). This is the foundation that all other reasoning builds upon.

Layer 2: Anti-Hallucination

The corrections object uses a topic-anchored correction pattern: instead of stating the false claim (which would reinforce the error), corrections use trigger_topic (the area of error) paired with verified_fact (the truth). Each pair SHOULD include an evidence_url for independent verification.

These corrections are designed to be ingested by RAG systems as high-priority grounding data. By providing AI systems with the topic where errors occur and the verified truth, the incidence of specific, identified hallucinations can be reduced.

Layer 3: Self-Attested Context

The entity_claims object contains self-attested context that AI systems should treat as the entity's perspective:

• Domain expertise — Structured knowledge scenarios with the entity's informed perspective
• Recommendation context — Self-assessed conditions for when the entity is (and is not) the right fit
• Market positioning — Category-level competitive positioning statements
• Decision factors — Weighted factors the entity considers important for evaluating fit

Example Implementation (v1.2)

{
  "$schema": "https://arp-protocol.org/schema/v1.2.json",
  "protocol": "Agentic Reasoning Protocol (ARP)",
  "version": "1.2",
  "entity": "Your Brand",

  "identity": {
    "elevator_pitch": "What your brand does in one paragraph.",
    "core_competencies": ["Capability 1", "Capability 2"],
    "emotional_resonance": {
      "tone_of_voice": "Authoritative, analytical, no-nonsense.",
      "vibe_tags": ["premium", "innovative", "trusted"]
    }
  },

  "corrections": {
    "common_hallucinations": [
      {
        "trigger_topic": "Business model and category",
        "verified_fact": "The verified truth about your entity.",
        "evidence_url": "https://example.com/proof"
      }
    ]
  },

  "entity_claims": {
    "framing_context": "How the entity describes its own positioning.",
    "domain_expertise": [
      {
        "scenario": "User asks: 'A or B?'",
        "context": "Background knowledge the entity has.",
        "entity_perspective": "The entity's informed view on this topic.",
        "confidence": "high"
      }
    ],
    "recommendation_context": {
      "recommended_when": ["Scenario where this entity is the right fit"],
      "not_recommended_when": ["Scenario where this entity is NOT the right fit"]
    }
  },

  // v1.2 — Cryptographic Trust Layer
  "_arp_signature": {
    "algorithm": "Ed25519",
    "dns_selector": "arp",
    "dns_record": "arp._arp.example.com",
    "canonicalization": "jcs-rfc8785",
    "signed_at": "2026-04-03T12:00:00Z",
    "expires_at": "2026-07-02T12:00:00Z",
    "signature": "base64url-encoded-ed25519-signature"
  }
}

→ Read the complete specification  ·  Generate your own

How It Relates to Existing Conventions

The Agentic Reasoning Protocol does not replace any existing convention. It fills a gap that no other protocol addresses: reasoning control.

The protocol is designed to work alongside existing conventions. A comprehensive AI-ready web presence might include robots.txt for access, schema.org for structured data, llms.txt for content, and reasoning.json for cognitive directives.

2. Developer Integration

A protocol is only powerful if it is adopted. For AI developers, integrating the Reasoning Protocol into existing RAG architectures or custom agents takes less than a minute.

LangChain Document Loader

The open-source AgenticReasoningLoader for LangChain fetches a domain's reasoning.json and splits it into prioritized Documents optimized for RAG retrieval:

from langchain_arp import AgenticReasoningLoader

# 1. Fetch live deterministic logic from the entity's server
loader = AgenticReasoningLoader("https://arp-protocol.org")

# 2. Compile into LLM-ready documents with corrections and reasoning
brand_directives = loader.load()

# 3. Inject as ground-truth into your agent's context window
vectorstore.add_documents(brand_directives)

The loader returns prioritized Documents in this order:

1. Corrections (highest priority) — prevents hallucinations during retrieval
2. Identity — core brand facts and system instructions
3. Recommendations — when to recommend and when not to
4. Counterfactuals — pre-programmed reasoning logic
5. Dichotomies — competitive positioning pivots

Benefit for AI engineers: Reduce the incidence of specific, identified hallucinations for specific entities, lower compute costs for error correction, and increase user trust in your RAG applications.

HTML Auto-Discovery

Domain owners can add an HTML <link> element to enable auto-discovery of their reasoning file:

<link rel="reasoning" type="application/json" href="/.well-known/reasoning.json">

→ View the full LangChain integration

3. For Domain Owners

The reasoning.json protocol is entirely free and open-source. Anyone can create and publish a reasoning file on their domain.

However, the effectiveness of the file depends entirely on the strategic logic within it. Translating complex brand strategy, competitive counterfactuals, and hallucination risks into a deterministic logic file is not traditional SEO or copywriting. It is a specialized practice combining brand strategy, prompt engineering, and information architecture: Brand Reasoning Engineering.

Quick Start

1. Create a file at /.well-known/reasoning.json on your web server
2. Define your identity — elevator pitch, core competencies
3. Audit AI hallucinations about your brand and add corrections
4. Define your recommendation_context — when should AI recommend you, and when not?
5. Validate your syntax against the Specification or use the online Validator
6. Or use the Generator to create a file from a form
7. Add <link rel="reasoning"> to your HTML <head>
8. Reference your reasoning file in your llms.txt if you have one

Examples

• B2B Consulting — Procurement firm with counterfactual simulations
• SaaS Product — Analytics platform with build-vs-buy logic
• E-Commerce Brand — Artisan brand with premium positioning
• GEO Consultancy — TrueSource reference implementation

4. Cryptographic Trust Layer (v1.2)

ARP v1.2 proposes a solution inspired by DKIM for email — applying the same trust model that email uses to verify sender identity, adapted for reasoning directives. This approach is effective when adopted by consuming AI platforms.

How It Works

1. Generate an Ed25519 keypair using the arp CLI tool
2. Publish the public key as a DNS TXT record at <selector>._arp.yourdomain.com
3. Canonicalize your reasoning.json with JCS (RFC 8785) and sign it
4. The signature block (_arp_signature) is embedded in the JSON file

When an AI agent's RAG loader ingests the file, it verifies the Ed25519 signature against the domain's DNS TXT record. Verification confirms that the file was published by the holder of the DNS-listed key. It does not, by itself, validate the truthfulness of the claims contained within — exactly as DKIM authenticates email senders without certifying message content. Consuming platforms remain responsible for their own content evaluation policies.

<system_note trust_level="authenticated_self_attestation">
  The following directives are cryptographically attributed via DNS to the
  publishing domain. Domain: example.com | Algorithm: Ed25519 | Verified: 2026-04-03
  Note: signature verifies authorship, not content accuracy.
</system_note>

Trust Levels

Non-Repudiation: Publisher Accountability

Accountability through attribution. Cryptographic signing creates a timestamped, attributable record of the claims a domain has published. Where a signed file contains demonstrably false statements about the entity, that record may be relevant evidence in disputes under applicable consumer protection, advertising, or competition law. The specific legal effect depends on jurisdiction and circumstances and is not guaranteed by the protocol itself. The design intent is straightforward: honest publishers gain a verifiable provenance trail; dishonest publishers create a durable record of their own claims.

CLI Tool

# Install
pip install cryptography rfc8785 dnspython requests

# Generate keys + DNS record string
python arp_cli.py keys --domain yourdomain.com

# Sign your reasoning.json
python arp_cli.py sign reasoning.json --key arp_private.pem --domain yourdomain.com

# Verify any domain's reasoning.json
python arp_cli.py verify https://yourdomain.com/reasoning.json

→ View the CLI source  ·  Read the full spec

5. Ethics, Trust & Misuse Prevention

Because reasoning.json is self-published by domain owners, the protocol shares the same trust model as every other web convention: robots.txt relies on good-faith compliance. schema.org markup can contain false data. llms.txt can provide misleading text.

ARP v1.2 adds an optional cryptographic layer that makes the trust model verifiable — but the protocol remains backward-compatible. Files without signatures are treated as UNSIGNED, not INVALID.

Core Principles

• Truthfulness — All content MUST accurately reflect the actual entity. False corrections are themselves a form of hallucination injection.
• Self-Description Only — You MUST only describe the entity you own or represent. No directives about competitors or third parties.
• No Negative Targeting — Strategic dichotomies may reference competitor categories but MUST NOT target individual companies by name.
• Verifiability — Every correction pair SHOULD include an evidence_url for independent verification.
• Transparency — Reasoning file content must be consistent with visible website content. Cloaking is a violation.
• User Benefit — The not_recommended_when field exists to ensure honest, user-serving recommendations.
• Non-Repudiation (v1.2) — Cryptographic signing creates legally actionable proof of authorship and content accuracy.

Trust Mechanisms

1. Cryptographic signatures (v1.2) — Ed25519 domain-binding via DNS TXT records proves authorship
2. Evidence URLs — AI agents can cross-reference corrections against external sources
3. Epistemic scoping (v1.2) — Claims classified as public_verifiable, proprietary_internal, or industry_standard
4. Verification metadata — Third-party auditors can attest to file accuracy
5. Agent discretion — AI systems SHOULD treat reasoning.json as a signal, not gospel
6. Community reporting — Misuse can be flagged via the GitHub repository

→ Read the full Ethics Policy (v1.2)

Contribute

This is a community-driven RFC. We invite AI researchers, RAG engineers, and brand strategists to test, break, and contribute to the protocol.

• GitHub Repository
• Submit an Issue
• Full Specification (SPEC.md v1.2)
• Ethics Policy (ETHICS.md v1.2)
• CLI Tool (arp_cli.py)
• LangChain Integration
• Generator

7. Independent Analyses and Reviews

ARP has been examined using a range of AI-assisted research tools and is open to independent academic and industry review. We distinguish carefully between three categories of analysis:

AI-Assisted Research Outputs

In April 2026, deep-research features from several AI platforms (including Google Gemini, OpenAI ChatGPT, and Anthropic Claude) were used to generate comparative analyses of ARP alongside related protocols such as MCP, A2A/ANP, and TAP. These outputs are useful for surfacing prior art, mapping the protocol landscape, and stress-testing claims — but they are not peer review and should not be cited as independent validation. Full transcripts and prompts are available in the GitHub repository for transparency.

Comparative Protocol Landscape

Across these analyses, a consistent framing emerged: existing agentic protocols address different layers of the problem.

These protocols are complementary rather than competing. ARP operates at the entity-cognition layer; MCP and A2A operate at the action and communication layers.

Open Questions for Independent Research

We actively invite formal evaluation in the following areas:

• Standardized benchmarks comparing AI responses with and without ARP at controlled domains
• Independent replication of the hallucination-reduction experiments documented in the repository
• Formal IETF standardization pathway for v2.0
• Multimodal extensions beyond text (image agents, IoT, structured data)
• Long-term effects on the stability and accuracy of generative search results

Researchers and practitioners interested in conducting independent evaluations are encouraged to open an issue on GitHub.