Agent Spec Protocol
Work in Progress — The spec is stable enough to build on, but several open issues (attribute type grammar, parallel error model, stability declarations) are not yet resolved. Expect breaking changes before v1.0. See Open Issues.
AP is an open standard for HTML documents that serve two audiences simultaneously: humans reading in a browser, and AI agents navigating a pipeline.
One XPath query. One section. Nothing else in context.
//ap-gate[@agent='idea-trends'][@status='pending']
That's the entire interface for an agent finding its work in a 10-stage document. No full-document reads. No markdown scanning. No reasoning about where things are.
The Problem
AI agents today navigate documents the same way a human speed-reads — by loading everything into context and scanning for what's relevant. A 10-stage pipeline document costs 3,500 tokens every time any agent runs, regardless of whether that agent owns one section or ten.
Markdown has no stable addressing. There is no md next --agent=my-name. An agent cannot navigate to its section — it can only read until it finds it. Every stage pays the full document cost. YAML and JSON pipelines have the opposite problem: machine-readable but completely opaque to humans, and always in a separate file from the content they process.
AP is the surgical option.
What AP Is
AP uses HTML custom elements — hyphenated tags (<ap-gate>, <ap-source>, <ap-gen>) defined by the W3C since 2016 — to encode which agents own which sections, what pipeline state each section is in, and how control flows through the document.
Open an AP document in a browser: a readable page showing every stage, its status, and whatever agents have written. Query it with XPath: a precise graph with stable addresses, routing declarations, and state encoded in attributes. Same file. Two audiences. No compromise.
By the numbers
| |
|---|
| 5× | fewer tokens than full markdown reads |
| ~1ms | XPath query against a 100-section document |
| 0 | new infrastructure required |
Every language already has an HTML parser. Python has lxml. Ruby has Nokogiri. JavaScript has the native DOM. Go has golang.org/x/net/html. AP builds on 30 years of browser infrastructure that happens to be exactly what agent navigation needs.
Two Layers. Start With Either.
AP operates at two independent layers. You can adopt either without the other.
Reading Layer
Add topic and kind to any element in any existing HTML. No workflow. No custom elements required. No restructuring.
<!-- any existing HTML — zero restructuring needed -->
<section topic="authentication" kind="overview">
<h2>How Auth Works</h2>
<p>Tokens are issued at login and expire after 24 hours...</p>
</section>
<aside topic="authentication" kind="reference">
<h3>Token Endpoints</h3>
<code>POST /auth/token, GET /auth/refresh</code>
</aside>
<p topic="authentication" kind="key-point">
Tokens are not stored server-side. Revocation is via expiry only.
</p>
An agent querying authentication content reads exactly what it needs, nothing else:
//*[@topic='authentication'][@kind='summary'] <!-- one-line answer -->
//*[@topic='authentication'][@kind='reference'] <!-- full details -->
topic is user-defined and open — any string that makes sense for your domain.
kind is a closed vocabulary: summary · overview · reference · key-point · definition · example · instruction
Closed vocabulary means an agent querying kind='reference' gets the same semantic result on any AP document, any domain. Topic is your namespace. Kind is the shared signal.
Pipeline Layer
Custom elements turn a document into a stateful, agent-navigable workflow. Each element declares its owner, its current state, and where control routes when it finishes.
<ap-gate
id="trends"
agent="idea-trends"
status="pending"
gate="required"
context="raw-idea"
on-pass="competitive"
on-fail="human-triage"
>
<ap-placeholder>Trends analysis pending.</ap-placeholder>
</ap-gate>
<ap-gate
id="competitive"
agent="idea-competitive"
status="blocked"
depends-on="trends"
context="raw-idea trends"
on-pass="phase-3"
on-fail="human-triage"
>
<ap-placeholder>Blocked — waiting for trends to pass.</ap-placeholder>
</ap-gate>
When idea-trends finishes, it sets status="passed". The orchestrator follows on-pass="competitive", which unblocks idea-competitive. The routing is in the document. The orchestrator never needs to know the business logic.
Install
go install agentspecprotocol.com/ap@latest
Requires Go 1.21+. The ap binary is the CLI reference implementation for reading, writing, and validating AP documents.
CLI
