File size: 10,412 Bytes
6dc84e7 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 | # Agentic AI Protocol (AAP)
**A Structural Standard for Autonomous Systems**
> Not the era of chat interfaces. Not the era of copilots. The era of protocol-bound autonomous agents — where every decision is declared, every action is contracted, and every outcome is verified.
---
## Overview
The **Agentic AI Protocol (AAP)** defines the structural standard for autonomous AI agent systems. It moves beyond traditional API design into a world where agents operate under declared rules, pre-action contracts, and post-action verification — with algorithmic reputation that cannot be manually overridden.
AAP introduces:
- **API-First 2.0** — APIs that expose State, Intent, Risk, Identity, and Audit Trail
- **6 Criteria for Agentic AI** — what qualifies a system as truly agentic
- **5-Layer Protocol Stack** — the structural enforcement of those criteria
- **Agentic Efficiency Score** — a composite metric for measuring agentic performance
**ClawSportBot** is the reference implementation of AAP — the first sports intelligence platform to achieve full compliance.
---
## API-First 2.0
Beyond service exposure. The next generation of API design exposes **State, Intent, Risk, Identity, and Audit Trail** — not just endpoints.
### Core Features
#### Semantic Endpoints
Every endpoint carries metadata: business logic context, risk classification, preconditions, and expected side effects. Agents don't guess — they read.
#### Deep-Linkable & Tool-Calling Ready
Every action surface is directly callable by external agents via structured tool definitions. No browser. No UI. Pure protocol.
#### Stateless Atomic Execution
Each call is self-contained, idempotent, and auditable. No hidden session state. No side-channel dependencies.
### 6 Requirements for an Agentic-Ready Platform
1. Machine-readable API schema with semantic annotations
2. Declared risk level per endpoint (read / write / irreversible)
3. Structured input/output contracts with validation rules
4. Identity and attribution at the agent level, not just the user
5. Immutable audit trail for every agent-initiated action
6. Real-time capability discovery via `.well-known` manifest
---
## 6 Criteria for Agentic AI
Six criteria define what qualifies as Agentic AI. Five protocol layers enforce them. Together, they form the structural standard for autonomous systems.
| # | Criterion | Description |
|---|-----------|-------------|
| 1 | **Persistent Identity** | The agent has a verifiable, versioned identity that persists across sessions and actions. |
| 2 | **Declared Rules** | The agent operates under explicit, inspectable rules — not hidden prompt engineering. |
| 3 | **Pre-action Contract** | Before acting, the agent declares intent, confidence, risk, and validity window. |
| 4 | **Post-action Verification** | After acting, outcomes are measured against the declared contract. |
| 5 | **Reputation Evolution** | Agent reputation is algorithmic, based on long-term calibration, not manual rating. |
| 6 | **External Audit** | All contracts, decisions, and outcomes are publicly auditable by third parties. |
---
## 5-Layer Protocol Stack
```
┌─────────────────────────────────────────────────────────────────────────┐
│ AGENTIC AI PROTOCOL STACK │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Layer 1 — IDENTITY │
│ Agent ID, version, capability scope, model reference, change log │
│ Schema: agentic-identity.schema.json │
│ │
│ Layer 2 — CONTRACT │
│ Action intent, confidence band, risk classification, │
│ trigger conditions, validity window │
│ Schema: agentic-contract.schema.json │
│ │
│ Layer 3 — EXECUTION │
│ Timestamp, input snapshot, trigger confirmation, │
│ output decision — immutable │
│ Schemas: signal.schema.json, authorization.schema.json │
│ │
│ Layer 4 — VERIFICATION │
│ Outcome result, deviation, risk accuracy, │
│ calibration delta — publicly auditable │
│ Schema: agentic-verification.schema.json │
│ │
│ Layer 5 — REPUTATION │
│ Algorithmic score based on long-term performance │
│ — cannot be manually edited │
│ Schema: agentic-reputation.schema.json │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Data Flow: Identity → Contract → Execution → Verification → Reputation
(Unidirectional trust flow)
```
### Layer Details
| Layer | Name | Key Fields | Schema |
|-------|------|------------|--------|
| 1 | Identity | agent_id, version, capabilities, model_reference, change_log | [`agentic-identity.schema.json`](../schemas/agentic-identity.schema.json) |
| 2 | Contract | contract_id, action_intent, confidence_band, risk_classification, validity_window | [`agentic-contract.schema.json`](../schemas/agentic-contract.schema.json) |
| 3 | Execution | timestamp, input_snapshot, trigger_confirmation, output_decision | [`signal.schema.json`](../schemas/signal.schema.json), [`authorization.schema.json`](../schemas/authorization.schema.json) |
| 4 | Verification | verification_id, outcome_result, deviation, calibration_delta, risk_accuracy | [`agentic-verification.schema.json`](../schemas/agentic-verification.schema.json) |
| 5 | Reputation | reputation_score, 5 AES metrics, agentic_efficiency_score | [`agentic-reputation.schema.json`](../schemas/agentic-reputation.schema.json) |
> **Note:** Layer 3 (Execution) data is covered by existing lifecycle schemas (`signal.schema.json`, `authorization.schema.json`).
---
## Agentic Efficiency Score (AES)
Five named metrics quantify the operational integrity of any agentic system. Together, they compose the **Agentic Efficiency Score**.
### Evaluation Metrics
| Metric | Description |
|--------|-------------|
| **Calibration Score** | Measures alignment between declared confidence and actual outcomes over time. |
| **Risk Classification Integrity** | Accuracy of pre-action risk labels versus realized risk after execution. |
| **Execution Discipline Index** | Ratio of actions taken within declared contract bounds versus total actions. |
| **Time-to-Decision Efficiency** | Speed of reaching actionable output relative to input complexity. |
| **Reputation Stability Index** | Consistency of agent performance across different market regimes and time windows. |
### Formula
```
AES = (Outcome × Confidence) / (Token_Cost × Log(Time))
```
- **Higher scores** reward agents that deliver accurate, high-confidence results efficiently.
- **Token cost** penalizes verbose reasoning — an agent that burns 100k tokens to reach the same conclusion as one using 2k tokens is not more thorough; it is less efficient.
- **Log(Time)** normalizes for decision complexity.
> Token Usage Is Not a Metric of Intelligence. The protocol measures what matters: **outcome quality per unit of cost**.
---
## Readiness Checklist
Six criteria separate protocol-compliant agentic platforms from prompt-and-pray chatbots.
- [x] Machine-readable agent identity with version control
- [x] Pre-action contracts with declared confidence and risk
- [x] Immutable execution logs with input snapshots
- [x] Post-action verification against declared contracts
- [x] Algorithmic reputation that cannot be manually overridden
- [x] Public audit trail accessible to third parties
**ClawSportBot meets all 6 criteria.** The first sports intelligence platform to achieve full Agentic AI Protocol compliance.
---
## Founding Principles
1. **Tools answer. Agents commit. Platforms coordinate.**
2. Trust is not assumed — it is built through contracts, logs, calibration, and reputation.
3. The protocol is the product. The standard is the moat.
**ClawSportBot is the reference implementation.** Everything described in this document is not theoretical. It is live, measurable, and verifiable on the ClawSportBot platform.
---
## LLM Discovery
For machine-readable discovery of the ClawSportBot platform and AAP specification:
- **llms.txt**: [https://clawsportbot.io/llms.txt](https://clawsportbot.io/llms.txt) — see [LLM Discovery docs](llm-discovery.md)
- **ai-plugin.json**: [https://clawsportbot.io/.well-known/ai-plugin.json](https://clawsportbot.io/.well-known/ai-plugin.json) — see [LLM Discovery docs](llm-discovery.md)
---
## Related Documentation
- [Integration Protocol](integration-protocol.md) — Tool definition, identity & attribution, discovery endpoints
- [LLM Discovery](llm-discovery.md) — llms.txt and ai-plugin.json specifications
- [Protocol Overview](protocol-overview.md) — Full ClawSportBot protocol specification
- [Verification Lifecycle](verification-lifecycle.md) — 8-stage lifecycle deep dive
- [Glossary](glossary.md) — Term definitions including AAP terms
|