{
"markdown": "# Agenticfeed Standard\n\n[](https://github.com/bluestratus/agenticfeed/releases/tag/v0.2.0)\n[](LICENSE)\n[](https://agenticfeed.ai)\n\n**An open specification for making ecommerce product catalogues readable by AI shopping agents.**\n\nAI assistants like ChatGPT, Claude, Perplexity, and Gemini are already recommending products to millions of shoppers. They do not browse category pages or read banner ads. They consume structured data and reason about which products best match the buyer's intent. Most merchant websites are invisible to them.\n\nThis standard defines a lightweight, discoverable format that gives AI agents exactly what they need.\n\n---\n\n## Quick start\n\nAdd one line to the `` of every page on your website:\n\n```html\n\n```\n\nThat tag tells any AI agent or crawler where your structured product feed lives. The rest of this document describes what that feed should contain.\n\n---\n\n## Contents\n\n- [What is an agentic feed?](#what-is-an-agentic-feed)\n- [Why does this standard exist?](#why-does-this-standard-exist)\n- [How is it different from a Google Merchant Center feed?](#how-is-it-different-from-a-google-merchant-center-feed)\n- [How do AI agents discover it?](#how-do-ai-agents-discover-it)\n- [How do I add it to my website?](#how-do-i-add-it-to-my-website)\n- [Specification](#specification)\n - [1. Discovery tag](#1-discovery-tag)\n - [2. Feed index](#2-feed-index)\n - [3. Intent endpoints](#3-intent-endpoints)\n - [4. Product detail](#4-product-detail)\n - [5. UTM attribution](#5-utm-attribution)\n - [6. Link validation](#6-link-validation)\n- [Agent Query API](#agent-query-api)\n - [Authentication](#authentication)\n - [Request](#request)\n - [Response](#response)\n - [Agent Card](#agent-card)\n- [Examples](#examples)\n- [Reference implementation](#reference-implementation)\n- [Contributing](#contributing)\n- [Licence](#licence)\n\n---\n\n## What is an agentic feed?\n\nAn agentic feed is a structured product data feed built for AI agents rather than search engine crawlers or human browsers.\n\nA traditional product page is designed to be rendered and read by a person. A Google Merchant Center feed is designed to be parsed by a price comparison engine. An agentic feed is designed to be reasoned about by an AI.\n\nThe key difference is intent data. Where a merchant feed tells an agent \"here is a cordless drill, it costs £29.99 and it is in stock,\" an agentic feed tells it \"here is a cordless drill that answers the question *what drill do I need for assembling flat-pack furniture*, solves the problem *I keep stripping screws with my old drill*, and fits the use case *home DIY for a first-time homeowner*.\"\n\nThat is the layer of context an AI agent needs to make a confident recommendation to a specific buyer.\n\n---\n\n## Why does this standard exist?\n\nAI shopping is already happening. The tooling to serve it well does not yet exist as an open, portable standard.\n\nSearch engines standardised web content discovery through sitemaps, robots.txt, and canonical tags. RSS standardised content syndication through a single autodiscovery tag. Neither was designed for the kind of structured reasoning that AI agents perform when they decide what to recommend.\n\nThis specification fills that gap. It defines:\n\n- How a website signals to AI agents that a structured product feed exists\n- What format that feed takes\n- How intent data (questions, problems, use cases) is structured alongside standard product data\n- How AI agents navigate from a buyer's query to a specific product recommendation\n\nThe format is intentionally minimal. It builds on schema.org types that crawlers already understand. It adds the intent layer that makes AI recommendation possible.\n\n---\n\n## How is it different from a Google Merchant Center feed?\n\n| | Google Merchant Center feed | Agenticfeed |\n|---|---|---|\n| Format | XML (RSS-like) | JSON-LD |\n| Schema | Google's proprietary spec | schema.org + agenticfeed namespace |\n| Primary consumer | Price comparison, Shopping ads | AI agents, LLMs, shopping assistants |\n| Discovery | Manual URL submission | Autodiscovery via `` |\n| Intent data | None | Questions, problems, use cases per product |\n| Product context | Price, title, image, availability | Price, title, image + buyer intent layer |\n| Attribution | None built in | UTM parameters on every product URL |\n\nA Google Merchant Center feed tells a machine *what* a product is. An agentic feed tells it *why a specific buyer should choose it*.\n\nThe two are complementary. Many merchants use a GMC feed as the data source for generating an agentic feed.\n\n---\n\n## How do AI agents discover it?\n\nThe discovery mechanism follows the same autodiscovery pattern the web has used for decades:\n\n```\nrel=\"stylesheet\" tells browsers where to find CSS\nrel=\"icon\" tells browsers where to find the favicon\nrel=\"alternate\" tells crawlers where to find RSS feeds\nrel=\"agenticfeed\" tells AI agents where to find structured product data\n```\n\nWhen an AI agent or crawler visits a merchant's website, it reads the page ``. If it finds a `rel=\"agenticfeed\"` tag, it knows exactly where to fetch structured product data without being told the URL in advance.\n\nThis means:\n\n1. No manual registration with each AI platform\n2. No API keys or access agreements required\n3. Any AI agent that implements this standard can discover your feed automatically\n4. The merchant controls the data at their own URL\n\n---\n\n## How do I add it to my website?\n\n**Step 1.** Add the discovery tag to every page ``:\n\n```html\n\n```\n\n**Step 2.** Serve a JSON-LD feed index at that URL (see [examples/feed.json](examples/feed.json)):\n\n```json\n{\n \"@context\": \"https://schema.org\",\n \"@type\": \"DataFeed\",\n \"name\": \"Your Store Name\",\n \"url\": \"https://yourdomain.com/feed.json\",\n \"provider\": {\n \"@type\": \"Organization\",\n \"name\": \"Agenticfeed\",\n \"url\": \"https://agenticfeed.ai\"\n },\n \"dataFeedElement\": [\n {\n \"@type\": \"DataFeedItem\",\n \"name\": \"Questions\",\n \"url\": \"https://yourdomain.com/questions.json\"\n },\n {\n \"@type\": \"DataFeedItem\",\n \"name\": \"Problems\",\n \"url\": \"https://yourdomain.com/problems.json\"\n },\n {\n \"@type\": \"DataFeedItem\",\n \"name\": \"Use Cases\",\n \"url\": \"https://yourdomain.com/use-cases.json\"\n }\n ]\n}\n```\n\n**Step 3.** Serve intent endpoints for each category (see [examples/questions.json](examples/questions.json)).\n\n**Step 4.** Serve product detail documents for each product (see [examples/product.json](examples/product.json)).\n\nFor Shopify merchants, [agenticfeed.ai](https://agenticfeed.ai) handles all of this automatically including injecting the discovery tag into your theme.\n\n---\n\n## Specification\n\n### 1. Discovery tag\n\n```html\n\n```\n\n| Attribute | Value |\n|---|---|\n| `rel` | `agenticfeed` |\n| `type` | `application/json` |\n| `href` | Absolute URL to the feed index document |\n\nPlace this tag in the `` of every page. It must appear in the server-rendered HTML, not injected by JavaScript, so crawlers can find it without executing scripts.\n\n---\n\n### 2. Feed index\n\n**Content-Type:** `application/ld+json`\n**Schema.org type:** `DataFeed`\n\nThe feed index is the entry point for any agent reading your feed. It identifies the merchant, lists intent endpoints, and provides the URL template for resolving individual products.\n\nSee [examples/feed.json](examples/feed.json) for a complete example.\n\n**Agent workflow:**\n\n1. Find the discovery tag in the page ``\n2. Fetch the feed index\n3. Read `dataFeedElement` to find intent endpoints\n4. Fetch the relevant endpoint based on the buyer's query type\n5. Match intent entries to the buyer's need and extract product IDs\n6. Resolve each product ID using the `agenticfeed.resolution.product.url` template\n7. Fetch the product detail document\n\n---\n\n### 3. Intent endpoints\n\nIntent endpoints are JSON-LD `ItemList` documents grouped by product category. There are three intent types:\n\n**Questions** — natural language questions a buyer asks before purchasing.\nSchema.org type: `Question` with `suggestedAnswer` pointing to the product URL.\nSee [examples/questions.json](examples/questions.json)\n\n**Problems** — pain points or needs the product addresses.\nSchema.org type: `ListItem` with `name` (the problem) and `url` (the product).\nSee [examples/problems.json](examples/problems.json)\n\n**Use cases** — specific scenarios or goals the product fits.\nSchema.org type: `ListItem` with `name` (the use case) and `url` (the product).\nSee [examples/use-cases.json](examples/use-cases.json)\n\n---\n\n### 4. Product detail\n\n**Content-Type:** `application/ld+json`\n**Schema.org type:** `Product`\n\nEach product has its own document at a stable URL. It combines standard schema.org `Product` data with the intent content under an `agenticfeed` namespace.\n\nSee [examples/product.json](examples/product.json) for a complete example.\n\n| Field | Type | Description |\n|---|---|---|\n| `@context` | string | `https://schema.org` |\n| `@type` | string | `Product` |\n| `name` | string | Product title |\n| `url` | string | Merchant product page URL (UTM-tagged) |\n| `image` | string | Primary product image URL |\n| `category` | string | Product category |\n| `offers` | Object | schema.org `Offer` — price, currency, availability |\n| `agenticfeed.questions` | Array | Questions this product answers |\n| `agenticfeed.problems` | Array | Problems this product solves |\n| `agenticfeed.use_cases` | Array | Use cases this product fits |\n\n---\n\n### 5. UTM attribution\n\nAll product URLs in an agentic feed should carry UTM parameters so merchants can measure AI agent traffic in their analytics:\n\n```\nutm_source=agenticfeed&utm_medium=ai-agent\n```\n\nThis lets merchants filter and report on sessions and orders that originated from an AI agent recommendation in Google Analytics, Shopify Analytics, or any platform that reads UTM parameters.\n\n---\n\n### 6. Link validation\n\nThe discovery tag in the merchant's `` serves as proof of domain ownership before a feed goes live. A validator fetches the merchant's homepage, parses the ``, and confirms:\n\n- A `rel=\"agenticfeed\"` tag is present\n- Its `href` matches the expected feed URL for that merchant\n\nThis prevents one merchant from claiming another merchant's domain in a feed.\n\n---\n\n## Agent Query API\n\nThe passive feed endpoints let AI agents crawl product data at their own pace. The Agent Query API is the active layer — an AI agent or application can send a natural language buyer intent and receive back a ranked list of matched products with reasons.\n\nThis is agent-to-agent communication. Instead of a human typing into a search box, one AI asks another AI to find the best matching products.\n\n**Endpoint**\n\n```\nPOST https://agenticfeed.ai/agent/query\nContent-Type: application/json\nAuthorization: Bearer af_your_api_key\n```\n\n---\n\n### Authentication\n\nOne API key is required:\n\n**Agenticfeed API key** — passed as a `Bearer` token in the `Authorization` header. This identifies who is making the request and controls access to the feed data. Generate one in **Dashboard › API Keys** for any paid plan (Growth and above). No approval needed — keys are available instantly.\n\n---\n\n### Request\n\n```json\n{\n \"query\": \"ergonomic chair for someone with lower back pain, works from home 10 hours a day, small home office, budget under £300\",\n \"customer_guid\": \"a9a8378c94\",\n \"limit\": 5\n}\n```\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `query` | string | Yes | Natural language description of what the buyer needs |\n| `customer_guid` | string | No | The merchant feed to query. Defaults to the feed linked to your API key |\n| `limit` | integer | No | Maximum results to return (1–10, default 5) |\n\n---\n\n### Response\n\nReturns a schema.org `ItemList` of matched `Product` entries, each with a `match_reason` explaining why that product fits the buyer's need.\n\n**Content-Type:** `application/ld+json`\n\n```json\n{\n \"@context\": \"https://schema.org\",\n \"@type\": \"ItemList\",\n \"query\": \"ergonomic chair for back pain...\",\n \"numberOfItems\": 3,\n \"itemListElement\": [\n {\n \"@type\": \"Product\",\n \"position\": 1,\n \"name\": \"HM Seating Contessa Chair\",\n \"url\": \"https://merchant.com/contessa?utm_source=agenticfeed&utm_medium=ai-agent\",\n \"image\": \"https://merchant.com/images/contessa.jpg\",\n \"category\": \"office chairs\",\n \"offers\": {\n \"@type\": \"Offer\",\n \"price\": \"249.00\",\n \"priceCurrency\": \"GBP\",\n \"availability\": \"https://schema.org/InStock\"\n },\n \"agenticfeed\": {\n \"product_id\": \"b3f1e29a4c\",\n \"match_reason\": \"Matches adjustable lumbar support, compact footprint for small spaces, and falls within the stated budget.\"\n }\n }\n ]\n}\n```\n\nThe `match_reason` field is designed to be passed directly to the end buyer by the calling agent. It explains the recommendation in plain language without requiring the agent to do any additional reasoning.\n\n---\n\n### Agent Card\n\nThe reference implementation publishes an A2A-compatible Agent Card at:\n\n```\nGET https://agenticfeed.ai/.well-known/agent.json\n```\n\nThis file describes the agent's capabilities, accepted inputs, output format, and authentication requirements in a machine-readable format. AI platforms that implement Google's Agent-to-Agent (A2A) protocol can discover and call the query endpoint automatically using this card.\n\n---\n\n## Examples\n\nAll examples are in the [examples/](examples/) directory:\n\n| File | Description |\n|---|---|\n| [examples/feed.json](examples/feed.json) | Complete feed index |\n| [examples/product.json](examples/product.json) | Product detail with intent data |\n| [examples/questions.json](examples/questions.json) | Questions endpoint |\n| [examples/problems.json](examples/problems.json) | Problems endpoint |\n| [examples/use-cases.json](examples/use-cases.json) | Use cases endpoint |\n| [examples/link-tag.html](examples/link-tag.html) | Discovery tag snippet |\n\n---\n\n## Reference implementation\n\n[agenticfeed.ai](https://agenticfeed.ai) is the hosted reference implementation of this standard.\n\nIt provides:\n\n- Automatic product catalogue import from Shopify, WooCommerce, Google Merchant Center, and website crawling\n- AI-generated intent data (questions, problems, use cases) per product\n- Daily stock and price synchronisation\n- Automatic discovery tag injection into Shopify themes via OAuth\n- UTM-tagged product URLs for attribution tracking\n- A merchant dashboard for managing feeds and subscriptions\n- Agent Query API at `/agent/query` for natural language product matching (included with paid plans)\n- A2A-compatible Agent Card at `/.well-known/agent.json`\n\nMerchants who use agenticfeed.ai get a fully conformant agentic feed without writing any code. Developers building AI agents can query product data by buyer intent using the Agent Query API, included with all paid merchant plans.\n\n---\n\n## Contributing\n\nIssues and pull requests are welcome at [github.com/bluestratus/agenticfeed](https://github.com/bluestratus/agenticfeed).\n\nThe goal of this standard is to be minimal and stable. Proposals that add complexity without clear benefit to AI agents or merchants will not be merged. The best contributions are real-world implementation experience, edge cases, and corrections.\n\n---\n\n## Licence\n\nPublished under the [MIT Licence](LICENSE). Anyone is free to implement compatible agentic feeds using this standard without restriction.\n",
"bytes": 15906,
"sha": "001f74ced87bbd8af4590aa90ead4f958ada3908deb899745a72476fe4bc8b7e",
"repo_slug": "bluestratus/agenticfeed",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_bluestratus_agenticfeed_07824742/readme"
}