Nákup cez AI agentov (UCP)

Universal Commerce Protocol (UCP) je otvorený protokol, cez ktorý AI agenti a obchodné platformy nájdu obchod, prečítajú si jeho katalóg a pripravia nákup za človeka. Obchod zverejní na pevnej adrese svojej domény strojovo čitateľný profil; agent si ho prečíta, zistí, aké schopnosti (capabilities) obchod ponúka, a potom komunikuje s REST API obchodu. Obchod na Monokaide, ktorému obchodník UCP zapol, odpovedá podľa tohto protokolu vo verzii 2026-04-08 na svojej vlastnej doméne.

Čo agent v obchode na Monokaide dokáže

• Nájsť obchod. GET https://shop.example.com/.well-known/ucp vráti profil obchodu: verziu protokolu, adresu REST API a ponúkané schopnosti. Netreba žiadnu hlavičku ani prístupový údaj.
• Čítať katalóg. Hľadať podľa textu (voliteľne s cenovým filtrom), naraz vyhľadať až 20 produktov alebo variantov podľa id, SKU alebo handle a prečítať jeden produkt podrobne aj s variantom, ktorý zodpovedá zvoleným možnostiam (Farba: Čierna, Veľkosť: M). Ceny, dostupnosť, obrázky aj popisy sú tie, ktoré ukazuje obchod, v jazykoch obchodu.
• Zostaviť košík. Ceny v ňom určí obchod podľa vlastných pravidiel: jeho ceny s DPH, jeho prirážky, jeho sklad a jeho zľavové kódy.
• Pripraviť checkout. Z košíka alebo priamo z položiek, s e-mailom kupujúceho, adresou doručenia a jedným zo spôsobov dopravy obchodu, každý aj s cenou.
• Odovzdať nákup kupujúcemu. Každý otvorený košík aj checkout nesie continue_url, ktoré kupujúcemu dáte, keď je checkout pripravený. Kupujúci ho otvorí v prehliadači, položky a uplatnený zľavový kód sa mu pridajú do košíka v obchode a otvorí sa pokladňa obchodu (pri košíku stránka košíka obchodu).
• Zistiť výsledok. Keď kupujúci objednávku dokončí, ďalšie čítanie checkoutu vráti completed s id objednávky, jej číslom a odkazom na potvrdenie.

Čo agent nedokáže

Ide o zámerné hranice implementácie. Navrhnite produkt s ohľadom na ne, aby ste ich neobjavili až v prevádzke.

• Cez UCP sa neplatí. Profil aj každý checkout nesú payment_handlers: {}. POST …/complete objednávku nevytvorí a nič nezmení. Kupujúci vždy platí na webe obchodu, spôsobmi platby, ktoré obchod ponúka.
• Nákup dokončí kupujúci v obchode. S continue_url putujú iba položky a uplatnený zľavový kód. E-mail kupujúceho, adresa a zvolená doprava zostávajú v relácii UCP; kupujúci ich v pokladni obchodu zadá znova a objednávku tam môže aj zmeniť.
• Žiadne notifikácie. Nie sú ani webhooky, ani schopnosť pre objednávky. Či objednávka vznikla, zistíte opakovaným čítaním checkoutu.
• Kupujúci sa neprihlasuje. Každá relácia je anonymná (bez prepojenia identity). Kupujúci, ktorý je v obchode prihlásený v tej istej karte prehliadača, dostane položky do svojho zákazníckeho košíka.
• Jeden zľavový kód na košík alebo checkout, jedna možnosť dopravy na checkout, bez výberu výdajného miesta (to kupujúci vyberie v obchode), bez filtra kategórií v katalógu (požiadavka, ktorá kategóriu uvedie, sa odmietne).
• Iba REST. Bez transportu MCP, A2A či embedded.
• Obchod v katalógovom režime ponúka iba vyhľadávanie a čítanie katalógu — bez košíka a bez checkoutu.

Celé porovnanie so špecifikáciou nájdete v kapitole Zhoda so špecifikáciou UCP.

Nákup v skratke

Agent nikdy nedrží peniaze ani kartu kupujúceho. Pripraví košík a údaje; rozhodnutie a platba zostávajú na kupujúcom, v obchode.

Kto čo číta

Obchodníci

• Zapnutie UCP v obchode — čo obchod potrebuje, kde je prepínač, ako overiť, že funguje, a čo sa zmení pre zákazníkov.
• Časté otázky k UCP — platby, objednávky, údaje a čo robiť, keď sa niečo nezobrazí.

Vývojári agenta alebo platformy

1. Rýchly štart pre vývojárov — celý nákup krok za krokom v curl, JavaScripte a Pythone.
2. Princípy a životný cyklus — profil, hlavička UCP-Agent, vyjednávanie schopností, košík a checkout, stavy, peniaze a jazyky.
3. Referencia API (OpenAPI) — každý endpoint, hlavička, pole a odpoveď.
4. Chyby a správy — každý kód a čo s ním má klient urobiť.
5. Idempotencia, súbežnosť a limity — opakovanie požiadaviek, súbežné zápisy, limity a platnosť.
6. Bezpečnosť a ochrana údajov — čo sa ukladá, ako dlho a čo to chráni.
7. Zhoda so špecifikáciou UCP — kde sa implementácia drží špecifikácie a kde sa od nej odchyľuje.
8. Časté otázky k UCP — krátke odpovede s odkazmi na podrobnosti.

AI agenti

Pre AI agentov — pravidlá, podľa ktorých sa má agent v obchode správať, a definície nástrojov pripravené na function calling.

Strojovo čitateľné zdroje

Všetko z týchto stránok je dostupné aj v podobe, ktorú si nástroj alebo jazykový model prečíta priamo.

• OpenAPI 3.1 (JSON)

  Celé UCP API na import do Swagger Editora, Postmana, Insomnie alebo openapi-generatora — podľa adresy alebo ako súbor.

  https://help.monokaido.com/ucp/openapi.json

• OpenAPI 3.1 (YAML)

  Ten istý dokument vo formáte YAML, pre nástroje a revízie, ktoré ho uprednostňujú.

  https://help.monokaido.com/ucp/openapi.yaml

• Definície nástrojov pre agenta

  Nástroje (tools) pre function calling jazykového modelu, mapované na operácie UCP.

  https://help.monokaido.com/ucp/tools.json

• Celý návod pre LLM

  Celý návod pre vývojárov UCP ako jeden súbor Markdown do kontextu jazykového modelu.

  https://help.monokaido.com/ucp/llms-full.txt

• llms.txt

  Obsah celého manuálu pre jazykové modely vo formáte llms.txt.

  https://help.monokaido.com/llms.txt

Verzia protokolu

Monokaido implementuje UCP 2026-04-08 a iba túto verziu. Obchod si prečíta profil vašej platformy (a uloží si ho do cache) a vyžaduje, aby jeho ucp.version bola presne 2026-04-08; každý iný dátum, starší aj novší, odmietne s 422 version_unsupported (pri hodnote, ktorá nie je dátumom, je profil profile_malformed). Schopnosť, ktorú váš profil uvádza iba v inej verzii, sa nevyjedná. Schopnosti, ktoré obchod môže ponúknuť, sú dev.ucp.shopping.catalog.search, dev.ucp.shopping.catalog.lookup, dev.ucp.shopping.cart, dev.ucp.shopping.checkout a rozšírenia dev.ucp.shopping.fulfillment (doprava v checkoute) a dev.ucp.shopping.discount (kódy v košíku a checkoute). Ktoré z nich obchod práve ponúka, vždy povie jeho vlastný profil.

Ochutnávka za 30 sekúnd

Profil obchodu je verejný a nepotrebuje žiadnu hlavičku. Opýtajte sa ktoréhokoľvek obchodu so zapnutým UCP:

curl -s https://shop.example.com/.well-known/ucp

const res = await fetch('https://shop.example.com/.well-known/ucp');
const profile = await res.json();
const [rest] = profile.ucp.services['dev.ucp.shopping'];
console.log(rest.endpoint, Object.keys(profile.ucp.capabilities));

import requests

profile = requests.get("https://shop.example.com/.well-known/ucp", timeout=10).json()
rest = profile["ucp"]["services"]["dev.ucp.shopping"][0]
print(rest["endpoint"], list(profile["ucp"]["capabilities"]))

Obchod, ktorý prijíma objednávky, odpovie 200 s Cache-Control: public, max-age=300 a týmto telom:

{
  "ucp": {
    "version": "2026-04-08",
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/overview",
          "transport": "rest",
          "endpoint": "https://shop.example.com/ucp/v1",
          "schema": "https://ucp.dev/2026-04-08/services/shopping/rest.openapi.json"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/catalog/search",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_search.json"
        }
      ],
      "dev.ucp.shopping.catalog.lookup": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/catalog/lookup",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_lookup.json"
        }
      ],
      "dev.ucp.shopping.cart": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/cart",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json"
        }
      ],
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/checkout",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
        }
      ],
      "dev.ucp.shopping.fulfillment": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/fulfillment",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/fulfillment.json",
          "extends": "dev.ucp.shopping.checkout"
        }
      ],
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-04-08",
          "spec": "https://ucp.dev/2026-04-08/specification/discount",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/discount.json",
          "extends": [
            "dev.ucp.shopping.checkout",
            "dev.ucp.shopping.cart"
          ]
        }
      ]
    },
    "payment_handlers": {}
  }
}

Ako základ každého ďalšieho volania použite endpoint, ktorý profil zverejňuje. Uvádza primárnu doménu obchodu, ktorá sa môže líšiť od domény, ktorú ste volali. Host bez UCP odpovie 404 s {"code":"not_found","content":"No UCP business on this host"} — z akéhokoľvek dôvodu. Obchod, ktorého firma je deaktivovaná alebo zablokovaná pre nezaplatené predplatné, odpovie 503 s {"code":"service_unavailable","content":"This shop is temporarily unavailable"} a Retry-After: 60.

Každé volanie pod /ucp/v1 potom potrebuje hlavičku UCP-Agent s adresou profilu vašej platformy. Ďalej pokračujte kapitolou Rýchly štart pre vývojárov.