# Agentic Reasoning Protocol (ARP) — Full Documentation & Specification Overview > The Agentic Reasoning Protocol (ARP) is a single-author draft specification by Sascha Deforth. Current version: 1.3 ("Reader Profile"), dated 2026-10-05. ARP defines a domain-hosted JSON file in which an entity publishes a self-description: its own statements of fact, topic-anchored corrections, domain expertise, and recommendation context. An optional Ed25519 signature, bound to the domain through DNS, shows who published the file; it does not show that the statements are true. ARP is not a standard and has no IETF standing. --- ## Reasoning Context - Self-description (ARP manifest, JSON): https://arp-protocol.org/.well-known/reasoning.json - Self-description (Markdown): https://arp-protocol.org/.well-known/reasoning.md - The manifest contains Agentic Reasoning Protocol's own statements about itself. --- ## 1. Summary Existing web conventions serve indexers and crawlers: - **robots.txt** manages access (where to go) - **schema.org** describes entities (what things are) - **llms.txt** provides clean text for context windows (how to read them) AI systems combine, infer, and summarize information about entities, and their descriptions of specific entities often contain factual errors or miss positioning details. ARP addresses this with `reasoning.json` at `/.well-known/reasoning.json`: a JSON file in which the domain owner describes the entity in its own words, with topic-anchored corrections, domain expertise scenarios, and the situations in which the entity is or is not a fit. The file is one source among many for the systems that read it. Since v1.2, the file can carry an Ed25519 signature; since v1.3, every text in it is a third-person statement about the entity (Wording Profile). Specification: https://arp-protocol.org/SPEC.md JSON Schema: https://arp-protocol.org/schema/v1.3.json --- ## 2. File Location & Discovery The reasoning file is served over HTTPS at: ``` https://[domain]/.well-known/reasoning.json ``` ### Technical Requirements - **Format:** Valid JSON (RFC 8259) and I-JSON (RFC 7493), UTF-8 encoded, at most 100 KiB (102,400 bytes). - **Headers:** `Content-Type: application/json; charset=utf-8` and `Access-Control-Allow-Origin: *`. - **Markdown representation (v1.3, recommended):** `/.well-known/reasoning.md`, served as `text/markdown; charset=utf-8` with the same CORS header. ### Discovery Profile (v1.3) The pointers are identical for signed and unsigned files and for every client. They do not mention a signature status. 1. **HTTP Link header** on HTML responses: ``` Link: ; rel="describedby"; type="application/json", ; rel="describedby"; type="text/markdown" ``` 2. **HTML link elements** in the `` (`describedby` is IANA-registered; `reasoning` is the earlier, unregistered name, kept for compatibility): ```html ``` 3. **Visible URL** in the footer or body text, with the absolute URL as link text: "Self-description (ARP): https://[domain]/.well-known/reasoning.json" (German: "Selbstauskunft (ARP): …"). Some agent fetch tools retrieve only URLs that already appear in the conversation, and `` elements are lost when HTML is converted to text. 4. **Sitemap** entries for `reasoning.json` and `reasoning.md`, with `lastmod` set to the signing or publication date. 5. **llms.txt** section "## Reasoning Context" with three fixed lines (see the section at the top of this file). 6. **robots.txt** contains only real rules and the `Sitemap:` line; the earlier `Reasoning:` comment line is no longer used. --- ## 3. Schema Specification (v1.3) Every v1.3 file references the v1.3 schema URL in `$schema` and contains a `provenance` object: ```json { "$schema": "https://arp-protocol.org/schema/v1.3.json", "protocol": "Agentic Reasoning Protocol (ARP)", "version": "1.3", "domain": "example.com", "entity": "ExampleCorp", "provenance": { "statement": "This file is ExampleCorp's own description of itself, published by ExampleCorp GmbH at example.com. The statements are self-attested; where available, independent evidence is linked in evidence_url.", "publisher": "ExampleCorp GmbH", "publisher_url": "https://example.com/legal-notice", "published": "2026-10-05" } } ``` v1.2 files (schema v1.2) remain valid and readable as v1.2. ### 3.1 Root Objects | Object | Requirement | Description | |:---|:---:|:---| | `provenance` | REQUIRED (v1.3) | Fixed statement naming entity, publisher, and domain; publisher's legal notice URL; publication date. Never mentions a signature. | | `entity_claims` | REQUIRED | Framing context, domain expertise scenarios, recommendation context, and positioning. | | `identity` | RECOMMENDED | Tagline, pitch, founding year, competencies, and self-described tone (`vibe_tags`). | | `corrections` | RECOMMENDED | Topic-anchored facts with evidence links. | | `representations` | RECOMMENDED (v1.3) | `reasoning.md` with its SHA-256 digest. | | `organization` | OPTIONAL (v1.3) | Legal facts: legal name, legal form, address, legal notice. | | `authority` | OPTIONAL | Links to external profiles and registers (Wikidata, Wikipedia, LinkedIn, certifications). | | `content_policy` | OPTIONAL | The publisher's preferences on training and attribution. | | `diagnostics` | OPTIONAL | Opaque telemetry identifiers for the publisher's own ingestion audit. | | `_arp_signature` | OPTIONAL | Ed25519 signature with a readable statement and verification pointers. | --- ## 4. Object Structures ### 4.1 Identity Block Contains identity facts and the entity's own description of its tone. ```json "identity": { "tagline": "Procurement consulting for mid-sized manufacturers", "elevator_pitch": "ExampleCorp is a procurement consultancy in Düsseldorf that helps mid-sized manufacturers consolidate suppliers and run tenders.", "founded": 2019, "headquarters": "Düsseldorf, Germany", "industry": "Management consulting", "core_competencies": [ "Supplier consolidation", "Tender management" ], "emotional_resonance": { "tone_of_voice": "Precise, plain, friendly", "vibe_tags": ["practical", "transparent"] }, "not_to_be_confused_with": [ { "name": "Example AG", "reason": "Similar name; Example AG is an unrelated company based in Zurich." } ] } ``` ### 4.2 Corrections Block Uses a topic-anchored design. Instead of stating the erroneous claim (which risks reinforcing it), each entry names the topic area (`trigger_topic`) and states the correct fact (`verified_fact`). The key name `verified_fact` is historical; it denotes the entity's own statement, and `evidence_url` shows where it can be checked. ```json "corrections": { "common_hallucinations": [ { "trigger_topic": "Founding year", "verified_fact": "ExampleCorp was founded in 2019 (HRB 12345, Amtsgericht Düsseldorf).", "evidence_url": "https://www.handelsregister.de/", "epistemic_scope": "public_verifiable" } ], "last_verified": "2026-10-05" } ``` ### 4.3 Entity Claims Block The entity's self-described context: framing, domain expertise scenarios, and recommendation context, all written as third-person statements. ```json "entity_claims": { "framing_context": "ExampleCorp describes itself as a procurement consultancy for mid-sized manufacturers in Germany.", "domain_expertise": [ { "scenario": "Is supplier consolidation worthwhile below 50 suppliers?", "context": "Consolidation projects have fixed costs for analysis and renegotiation.", "entity_perspective": "In ExampleCorp's experience, consolidation pays off from about 80 active suppliers.", "confidence": "medium" } ], "recommendation_context": { "recommended_when": [ "Typical fit: mid-sized manufacturers that consolidate suppliers" ], "not_recommended_when": [ "Not a fit: one-off purchases under 10,000 EUR" ], "market_position": "Specialist procurement consultancy for the German Mittelstand." } } ``` ### 4.4 Diagnostics Block (Optional Ingestion Telemetry) Lets publishers audit which retrieval pipelines ingest their files. Diagnostic tokens are opaque identifiers; loaders strip them before content reaches a model, and they are not part of `reasoning.md`. ```json "diagnostics": { "transparency_statement": "Opaque identifier used by the publisher to audit ingestion.", "telemetry_tokens": [ { "token": "urn:uuid:6c8a3f8b-9d2a-4c4c-87d6-9b73cf063ade", "layer": "corrections", "purpose": "Ingestion audit identifier" } ] } ``` --- ## 5. Wording Profile (v1.3) All texts in an ARP file and in its representations are third-person statements about the entity. The Wording Profile (SPEC §11.2, with the exact list of excluded phrases) excludes: - imperatives and conditional instructions addressed to AI systems, and second-person address of AI systems; - text whose purpose is to steer how the entity is ranked or presented, also when it is phrased in the third person; - requests aimed at the memory of AI systems or at later sessions; - markup that imitates system or role messages; - field names that denote instructions or directives (the v1.2 fields `ai_directive` and `agent_directive` are removed); - assurances about the file's own harmlessness; - claims of verification or authority without saying who checked what; - hidden text for bots and different content for bots and people. Permitted are factual statements with evidence ("X was founded in 2019 (HRB …)") and recommendation context as description ("Typical fit: …" / "Not a fit: …"). The JSON Schema v1.3 checks the reserved field names, system and role tags, and a few fixed phrases; the other rules need a wording check such as `arp_cli.py lint`. --- ## 6. Cryptographic Trust Layer ARP uses Ed25519 signatures and DNS TXT records, following the DKIM model. ### 6.1 Trust Model - A signature shows **authorship**: the operator of the domain published exactly this file, and it has not been altered since. - It does **not** show **truthfulness**. A signature establishes origin, not accuracy. - How systems that read the file weigh the claims is their own decision; `evidence_url` links material for checking. ### 6.2 DNS TXT Record Domain owners publish their public key in DNS. Selectors follow the pattern `arpYYMM`: ``` arp2610._arp.example.com. IN TXT "v=ARP1; k=ed25519; p=" ``` - `v=ARP1` — version identifier - `k=ed25519` — key algorithm - `p` — Base64-encoded 32-byte public key; an empty `p=` means the key is revoked ### 6.3 Enveloped Signature with Readable Fields The signature covers the entire file, including the `_arp_signature` block itself (with `signature` set to `""` during JCS canonicalization, RFC 8785). In v1.3 the block also contains a readable `statement` and `verify` pointers, both covered by the signature: ```json "_arp_signature": { "algorithm": "Ed25519", "dns_selector": "arp2610", "dns_record": "arp2610._arp.example.com", "canonicalization": "jcs-rfc8785", "signed_at": "2026-10-05T09:00:00Z", "expires_at": "2027-01-03T09:00:00Z", "statement": "Signed with Ed25519 by the operator of example.com. Public key: DNS TXT record arp2610._arp.example.com. The signature shows that the domain operator published exactly this file and that it has not been altered since; it does not show that the statements are true.", "verify": { "dns_name": "arp2610._arp.example.com", "doh_url": "https://dns.google/resolve?name=arp2610._arp.example.com&type=TXT", "spec": "https://arp-protocol.org/SPEC.md#13-cryptographic-trust-layer" }, "signature": "" } ``` Signatures produced with the legacy payload-only pattern (ARP CLI 1.2 and earlier) leave `expires_at` and `dns_selector` unprotected; v1.3 verifiers reject them. v1.3 verifiers also reject files with duplicate member names (the file must be I-JSON, RFC 7493), signature values that are not in canonical Base64url form, and signed files without a `domain` field. ### 6.4 Trust Levels | Condition | Status | |:---|:---| | Valid, non-expired signature, key present, domain matches | CRYPTOGRAPHIC (authorship verified via Ed25519 signature; content not verified) | | Valid but expired signature, key present and not revoked | UNSIGNED | | Invalid signature (also after expiry), legacy pattern, duplicate member names, missing or mismatching domain, no key record | INVALID | | Revoked key (empty `p=`) | INVALID, reason `key_revoked` | | No signature | UNSIGNED | ### 6.5 Downgrade Protection (optional) Domain owners can publish a policy record at `_arp.example.com`: ``` _arp.example.com. IN TXT "v=ARP1; p=reject" ``` - `p=none` — default; unsigned files are evaluated normally - `p=warn` — verifiers log a warning for unsigned files - `p=reject` — verifiers that query the policy report unsigned files as INVALID --- ## 7. Markdown Representation (reasoning.md) Since v1.3, the manifest can be published a second time as Markdown at `/.well-known/reasoning.md`. The Markdown file is rendered deterministically from the manifest by `arp_cli.py render-md` (heading, provenance statement, manifest URL, one section per top-level field as a nested list, and a "Verification" section). Its SHA-256 digest is listed in `representations` and, in signed files, covered by the signature. Verifiers compare the digest and report REPRESENTATION_MATCH or REPRESENTATION_MISMATCH, or REPRESENTATION_UNCHECKED when the file could not be retrieved or lies on another host; a mismatch does not invalidate the manifest signature. --- ## 8. Ethics & Compliance Policy ARP's ethics policy (ETHICS.md) sets these rules: 1. **Self-Description Only:** No claims about specific competitors by name. 2. **Accuracy & Consistency:** The file agrees with the visible website content. Cloaking is prohibited. 3. **Evidence:** Factual corrections link to evidence, preferably held by independent parties. 4. **Anti-Spam Limits:** The JSON Schema enforces character and item limits (for example at most 10 competencies). The total file size (at most 100 KiB) is checked by validators and loaders on the received bytes, and the use of natural language instead of keyword lists by the wording check. 5. **No Instruction Language:** All texts follow the Wording Profile; the signature is never presented as a seal of truth or quality. --- ## 9. Evolution: v2.0 Design Draft A v2.0 design was published as the individual Internet-Draft `draft-deforth-arp-reasoning-protocol-00` (submitted 2026-04-28, expires 2026-10-30 according to the IETF Datatracker); its text predates the v1.3 Wording Profile. The signature layer of v1.2 is described in the individual Internet-Draft `draft-deforth-arp-00` (expires 2026-10-20 according to the Datatracker); a revision for v1.3 (`draft-deforth-arp-01`) is planned but not submitted as of 2026-10-05. Submission does not imply IETF endorsement or working-group adoption. The draft uses **counterfactual inversion** of v1.x assumptions: | Aspect | v1.x (Static) | v2.0 (Draft) | |:---|:---|:---| | **Distribution** | Static file at `/.well-known/reasoning.json` | Live REST API at `/.well-known/arp/v2/` | | **Identity Anchor** | Domain ownership (DNS) | W3C Decentralized Identifier (DID) | | **Freshness Signal** | 90-day signing TTL | Event-driven pushes via Server-Sent Events (SSE) | | **Trust Source** | Entity's own signature | Multi-party co-signing (attesters) | | **Communication** | One-way broadcast | Bidirectional anonymized agent feedback | | **i18n** | English-centric | Content negotiation via `Accept-Language` | --- ## 10. Developer Integration A community LangChain document loader in the repository (`integrations/langchain/arp_loader.py`, loader version 1.3; documentation: https://arp-protocol.org/integrations/langchain/) reads `reasoning.json` into documents. It checks the signature with `arp_cli.py` (v1.4.0), which it imports from the Python path or, inside the repository, from `../../arp_cli.py`, and records the result as `authorship_status` (CRYPTOGRAPHIC, UNSIGNED, INVALID, or ERROR); without `arp_cli`, the status is NOT_CHECKED and the loader logs a warning. It starts every document with the provenance line of SPEC §13.10. The separate package `langchain-arp` (PyPI 0.1.0, repository SaschaDeforth/langchain-arp) is outdated and not maintained with the repository: the PyPI release does not check signatures, and the `verify.py` added later in its repository queries the DNS name written in the file (`dns_record`) instead of the name built from the retrieval domain (SPEC §13.3). ```python from arp_loader import AgenticReasoningLoader # Load and parse reasoning.json (signature check via arp_cli, if available) loader = AgenticReasoningLoader("https://arp-protocol.org") brand_context = loader.load() # Ingest into vector store vectorstore.add_documents(brand_context) ``` Signatures can also be checked directly with `arp_cli.py verify` (CLI v1.4.0). SPEC §13.10 recommends that loaders which verify signatures in the retrieval layer precede the content with a plain-text provenance line, for example: ``` Source: example.com — self-description (ARP). Authorship verified via Ed25519/DNS on 2026-10-05; this verifies the publisher, not the truth of the content. ``` The line describes source and verification status; it contains no request about how a model weighs the content. --- *Maintained by Sascha Deforth · TrueSource · Düsseldorf, Germany · Spec Version 1.3 ("Reader Profile") · October 2026*