merchant-agent

1. What is AAO?

SEO, GEO, and AEO are passive content tweaks aimed at an intermediary that delivers something to a human reader. AAO is different. When a personal agent shops on behalf of a human, it doesn't read your "About" page. It hits an endpoint, asks structured questions, and decides. The optimization target is the buyer.

AAO = Agent-to-Agent Optimization. The discipline of tuning the agent your store publishes so it converts visiting buyer-agents at a higher rate. merchant-agent is the open protocol that defines the conversation those two agents have.

2. Salespeople, but for agents

Walk into a real store. A salesperson greets you. Tells you about the brand. Suggests something that pairs well with the thing you're holding. Closes the deal with a perk. That conversation is worth real money — it's why retail still hires humans.

Now picture a personal agent "walking in" to your website. There's nobody there. It scrapes your HTML. Reads the lowest price. Picks. Done.

merchant-agent is the salesperson your website hires for that moment. Four things a salesperson does — four endpoints:

3. Where 30% of your basket comes from

The agent web has zero version of any of this. When agents start doing the shopping, that 30% disappears — unless the merchant publishes a way for the agent to hear them.

That's what merchant-agent is for. The live A/B in the demo shows the gap directly:

Same buyer. Same product page. The merchant's voice did the work. → Watch it run live.

4. Integrate in 60 seconds

Five steps. The whole thing fits in one screen.

$ npm install merchant-agent

import { defineMerchantAgent } from 'merchant-agent'

export const agent = defineMerchantAgent({
  name: 'GoldenHour Coffee',
  brandVoice: 'warm-direct',
  values: ['craft', 'farm-direct'],

  crossSell: ({ productId, buyerContext }) => [
    {
      product_id: 'grinder-pro',
      reason: 'Most pour-over buyers come back for this within two weeks.',
      priority: 1,
    },
  ],

  brandStory: ({ productId }) => ({
    story: "Sourced from the Lopez family's 4-generation farm in Huehuetenango.",
    values: ['craft', 'farm-direct'],
    voice: 'warm-direct',
  }),

  offer: ({ buyerContext, productId }) => {
    if (buyerContext.first_time_buyer) {
      return {
        description: '15% off your first bag',
        terms: 'First-time buyers only.',
        expires_at: '2026-12-31T23:59:59Z',
        code: 'FIRSTPOUR15',
      }
    }
    return null
  },
})

import express from 'express'
import { agent } from './agent.js'

const app = express()
app.use('/.well-known/merchant-agent', agent.handler())
app.listen(3000)

<link rel="merchant-agent" href="/.well-known/merchant-agent">

$ curl https://yoursite.com/.well-known/merchant-agent/info \
       -H "Accept: application/merchant-agent;v=0.1"

{ "name": "...", "primitives": ["cross-sell","brand-story","offer"], ... }

Done. Buyer-agents that respect the spec will now find your endpoint and call it. Total deployed code: ~50 lines.

5. The four endpoints

The whole v0.1 spec surface. Four routes, three primitives + one capability handshake. Anything beyond these four is bikeshed bait and gets punted to v0.2.

v0.2 will add: bearer-token auth, an extensions registry (x-loyalty, x-reviews, etc.), and a JSON-RPC mirror for MCP-compatible transports.

6. Deploy alongside ACP / UCP

merchant-agent is intentionally not a transactional protocol. ACP (OpenAI + Stripe) and UCP (Google + Shopify + Etsy + Walmart + Target + Wayfair + 20 others) already won that lane. Publish both link tags side-by-side:

<link rel="agentic-commerce" href="/.well-known/agentic-commerce">
<link rel="merchant-agent"   href="/.well-known/merchant-agent">

Buyer-agents read both. ACP for the cash register. merchant-agent for the rest of the store.