IntentIO

Codename: The Reasoning Interface Version: 1.0 Status: Draft Strategic Alignment: Phase 2 (Logic & Reasoning) of the Machine-First Maturity Model.

1. Executive Summary

The Core Problem: Traditional APIs are designed for human developers, following the CRUD model (Create, Read, Update, Delete) which exposes data objects (e.g., GET /product/123). This works when a human controls the logic. However, AI agents do not "think" in objects; they think in goals, constraints, and actions. When an AI is forced to infer business rules from raw data objects, it often "guesses" the logic, leading to hallucinations (e.g., promising a refund that the policy forbids). The Solution: IntentIO is an Intent-Driven API Wrapper. It sits between legacy databases and AI agents, transforming data pipes into "Reasoning Surfaces". Instead of exposing state, it exposes capabilities and constraints. The Goal: To replace UX (optimizing for clicks) with RX (Reasoning Experience—optimizing for comprehension), ensuring the machine understands the world well enough to act without inventing it,.

2. User Personas

• The AI Systems Architect (Primary): Needs to expose the company’s services (booking, buying, scheduling) to external agents (e.g., ChatGPT, Amazon Rufus) without risking unsafe actions.

• The Partner Developer: Building an automated agent that needs to negotiate with the client's API without constant error handling.

• The Governance Lead: Wants to ensure that business rules (e.g., "No cancellations within 24 hours") are enforced at the API definition level, not just in the UI code.

3. Core Value Proposition

• From Objects to Intent: Shifts the API paradigm from "Here is a booking object" to "Determine whether this booking can be canceled".

• Impossible to Misunderstand: Eliminates the need for the AI to "infer" rules. Constraints are explicit. If an action is impossible, the API explains why before the attempt is made.

• Zero-Hallucination Logic: By providing the AI with a menu of "Valid Next Actions," we prevent it from attempting to execute invalid ones.

4. Functional Requirements

4.1. The Capability Endpoint (The "Menu")

• Requirement: The system must expose a GET /capabilities or OPTIONS endpoint that returns not just supported methods, but contextual valid actions based on the current state.

• Rationale: Machines need to know "What can I do next?".

• Output Example: Instead of just returning booking data, IntentIO returns: {"allowed_actions": ["modify_dates", "add_baggage"], "prohibited_actions": ["cancel"]}.

4.2. Constraint Publication

• Requirement: The API must publish Constraints as first-class citizens, not just return them as error messages after a failure.

• Rationale: UX allows users to try and fail. RX requires machines to know the failure modes before they act to avoid hallucinating success.

• Key Feature: Pre-computation of Constraints. (e.g., {"constraint": "cancellation_window_passed", "hard_stop": true}).

4.3. The Reasoning Surface (Querying Logic)

• Requirement: The system must support "Hypothetical" queries (Simulation Mode).

• Rationale: An AI needs to "think" before it commits. It needs to ask, "If I were to try X, would it work?" without actually doing X.

• Functionality: A /simulate endpoint that runs business logic against a proposed action and returns the predicted outcome and any triggered rules.

4.4. Justification & Explanation

• Requirement: When an action is refused or a query is answered, the API must return a structured Justification.

• Rationale: Machine judgment is "justificatory". If the AI is to explain to a user why they can't have a refund, the API must provide the reasoning (e.g., policy_ref: "Section 4.2"), not just a 403 Forbidden code.

5. Technical Architecture & Schema

IntentIO wraps legacy REST/GraphQL endpoints to create a Reasoning Envelope.

Target JSON Schema (The "RX" Response):

{
  "entity_id": "booking_999",
  "current_state": "confirmed",
  "intent_surface": {
    "can_cancel": false,
    "can_reschedule": true,
    "reasoning": {
      "cancellation_blocked_by": {
        "rule_id": "policy_24h_window",
        "description": "Cancellations strictly prohibited within 24h of departure."
      }
    }
  },
  "next_valid_actions": [
    {
      "intent": "reschedule_flight",
      "endpoint": "POST /bookings/999/reschedule",
      "required_params": ["new_date"]
    }
  ]
}

6. Use Cases

Use Case A: The Travel Agent Bot

• Problem (Legacy): A user asks a bot to cancel a flight. The bot calls GET /booking, sees a "Confirmed" status, and hallucinates that it can cancel. It tells the user "Done!", but the API call fails later.

• IntentIO Solution: The bot calls GET /booking/intent. IntentIO returns can_cancel: false with the reason "Non-refundable fare".

• Result: The bot correctly informs the user: "I cannot cancel this because it is a non-refundable fare, but I can help you reschedule."

Use Case B: The E-Commerce Compatibility Check

• Problem (Legacy): An AI recommends a phone case for a specific phone model based on keyword matching (SEO logic). The case doesn't actually fit.

• IntentIO Solution: The AI queries the product's Reasoning Surface: POST /compatibility/check with payload {"host_device": "iPhone 15"}.

• Result: IntentIO returns {"compatible": false, "reason": "dimensions_mismatch"}. The AI excludes the product from the recommendation.

7. Success Metrics (KPIs)

1. Reasoning Success Rate: The percentage of API interactions where the AI agent successfully navigated the flow without triggering a 4xx client error (indicating it understood the constraints beforehand).

2. Hallucination Rate: Frequency of the AI promising an action (in chat logs) that the API subsequently rejected.

3. Schema Legibility: Measured by how easily external LLMs (like GPT-4) can correctly predict the valid next action solely by reading the API documentation (Target: 100% prediction accuracy).

8. Roadmap

• Phase 1 (The Read Layer): Implement the intent_surface field on existing GET requests to expose "allowed actions" alongside data.

• Phase 2 (The Simulation Layer): Build the /simulate endpoint to allow agents to test actions without commitment.

• Phase 3 (The Governance Layer): Integrate with SafeState (Action Governor) to enforce state transitions during write operations.

AI Visibility ToolsFrancesca Tabor31 December 2025