Agent Deep Link Protocol

An open standard for AI agents to discover, construct, and retrofit deep links — built for the agentic web.

---

What Is This?

The Agent Deep Link Protocol is a lightweight open standard that gives AI agents a machine-readable map of a website's supported URL patterns — so they can navigate precisely instead of guessing.

It works in two modes:

1. Author Mode — Build Agent-Native from Day One

Web developers ship a /.well-known/deep-links.json manifest alongside their site. URLs, state, navigation, and deep links are designed from the start to be agent-consumable — just as sitemap.xml shaped SEO-friendly structure, and robots.txt shaped crawl behavior.

2. Agent Mode — Retrofit Any Existing Site

Agents crawl an existing website, analyze its routes, query params, fragments, and state patterns, then generate a deep-links.json manifest. No site owner required. Any site becomes agent-navigable.

---

Why It Matters

Current agent protocols solve tools, discovery, and communication:

Protocol	What It Solves
MCP	Tools & data access
A2A	Agent-to-agent coordination
WebMCP	Browser-native tool exposure
Agent Deep Link Protocol	Precise URL construction & navigation

None of the above tell an agent: "Here's the exact URL template for a pre-filled invoice, a specific dashboard tab, or a Notion block." This protocol does.

---

The Manifest

Place a static JSON file at:

https://yourdomain.com/.well-known/deep-links.json

Minimal Example

{
  "version": "1.0",
  "agent_generated": false,
  "templates": [
    {
      "name": "invoice-view",
      "description": "Open a specific invoice with optional tab and line item highlight",
      "template": "/invoices/{invoiceId}?tab={tab}&highlight={lineItemId}",
      "parameters": {
        "invoiceId": { "type": "string", "required": true, "example": "INV-48721" },
        "tab": { "type": "enum", "values": ["details", "payments", "notes"], "default": "details" },
        "lineItemId": { "type": "string", "required": false }
      },
      "examples": [
        "/invoices/INV-48721?tab=payments",
        "/invoices/INV-48721?tab=notes&highlight=L3"
      ],
      "mobile_fallback": "myapp://invoice/INV-48721"
    }
  ],
  "common_params": {
    "utm_source": { "type": "string", "description": "Agent attribution tracking" }
  }
}

---

Adoption Path

For new sites:

1. Design your URL architecture with agent use in mind (clear params, stable paths, state in URLs)
2. Ship /.well-known/deep-links.json at launch
3. Update it alongside your routes as the product evolves

For existing sites:

1. Run an agent-powered retrofit (tooling coming in tools/) to auto-generate a manifest
2. Review and publish the generated manifest
3. Optionally submit it as a PR to this repo's registry/ for community indexing

For agent builders:

1. Check /.well-known/deep-links.json before constructing any URL for a known domain
2. Fall back to agent-generated manifests for unregistered sites
3. Prefer deep links over browser automation whenever possible

---

Repo Structure

.
├── .well-known/
│   └── deep-links.json       # Example/reference manifest
├── spec/                     # Formal specification drafts
├── registry/                 # Community-submitted manifests for major sites
├── tools/                    # Agent retrofit tooling (coming soon)
├── CONTRIBUTING.md
└── LICENSE

---

Status

This is an early draft. The spec is open for community input.

• v0.1 schema finalized
• Reference implementations (Node, Python, Next.js)
• Agent retrofit tooling
• Registry of major site manifests (GitHub, Stripe, Notion, Linear, Shopify)
• Submission to standards body (W3C / Agentic AI Foundation)

---

Contributing

See CONTRIBUTING.md. Issues and PRs welcome.

---

License

MIT — use freely, build on it, help shape the agentic web.