Termék eszközök

Áttekintés

Két eszköz fedi le egy márka termékkatalógusát: a manage_product_source beköti és karbantartja azokat a helyeket, ahonnan a termékek érkeznek, a manage_product_rules pedig megírja a szöveget, amit az AI-nak követnie kell, valahányszor említ egyet.

Szükséges jogosultság:ContentSources — a jogosultsági listában Tartalomforrások néven jelenik meg. A termékkatalógus közös tartalom: olvassa a Vex, a hangügyintézők, a beérkezettekben megjelenő válaszjavaslatok és az AI közösségimédia-posztolás egyaránt.

Ezek az eszközök ugyanabba a Vex AI eszközkategóriába tartoznak, mint a chatbot eszközök, tehát egy kategóriákat mutató MCP kliensben ott találod meg őket. Amit viszont szabályoz, az a Tartalomforrások jogosultság, nem a Vex AI.

Mindkét eszköz rajta van a Copilot jóváhagyási listáján. Az irányítópulti Copilotban mindkettő megerősítést kér, mielőtt lefutna — egy forrás törlése törli a termékeit, egy szabály jóváhagyása pedig megváltoztatja, mit mondhat az AI.

Hogy mindez mit jelent a termékben, arról az irányítópulti dokumentáció szól: termékszabályok és termékforrások.

manage_product_rules

Termékszabályokat hoz létre, szerkeszt, hagy jóvá és töröl. Egy szabály kulcsok listájából (a szavak, amik közösek a szabályban és a termékben, jellemzően egy összetevő neve) és a szövegből áll, amit az AI szó szerint elolvas.

Paraméterek

Paraméter	Típus	Kötelező	Leírás
`action`	string	Igen	`create`, `bulk_create`, `update`, `delete` vagy `approve`.
`brandId`	string	Feltételes	A `create` és a `bulk_create` esetén kötelező, valamint `approve`/`delete` esetén, ha `allDrafts` van megadva.
`id`	string	Feltételes	Szabályazonosító. Az `update` esetén kötelező; a `delete` is használhatja.
`ids`	string	Feltételes	Szabályazonosítók az `approve` vagy a `delete` művelethez. Legfeljebb 500.
`allDrafts`	boolean	Nem	A márka minden piszkozat szabályára hat. `brandId` szükséges hozzá.
`importId`	string	Nem	Az `allDrafts` mellett leszűkíti egyetlen dokumentumimport piszkozataira.
`keys`	string	Feltételes	Legfeljebb 100 kulcs, egyenként legfeljebb 200 karakter.
`text`	string	Feltételes	1–5000 karakter. Az AI szó szerint olvassa.
`note`	string	Nem	Legfeljebb 2000 karakter, csak embereknek. A `null` törli.
`mode`	string	Nem	`always` (alapértelmezett) vagy `when_relevant`.
`status`	string	Nem	`draft` (alapértelmezett) vagy `active`.
`rules`	object	Feltételes	Csak `bulk_create` esetén. Legfeljebb 200 elem `{ keys, text, note?, mode? }` formában.

Hogyan működik

Az illesztés pontos, soha nem közelítő. Egy szabály akkor vonatkozik egy termékre, ha közös kulcsuk van, normalizálás után összevetve — kisbetűsítve, ékezetek nélkül, összevont írásjelekkel. Tedd ugyanannak a dolognak minden írásmódját egyetlen szabály keys mezőjébe; a szinonimákat és a fordításokat nem illesztjük helyetted.

always kontra when_relevant. Egy always szabály minden egyes alkalommal átmegy, amikor egy illeszkedő termék szóba kerül — ezt használd feltételekre, korlátozásokra és kötelező figyelmeztetésekre. Egy when_relevant szabályt a látogató kérdéséhez mérten szűrünk — ezt használd az egyes engedélyezett állításokra, hogy egy hosszú lista ne érkezzen meg egyszerre.

Az új szabályok piszkozatok, és a piszkozatok soha nem jutnak el az AI-hoz. A status: "active" értéket csak akkor add meg, ha az, akinek dolgozol, elolvasta és jóváhagyta a pontos szöveget. Egyébként hagyd őket piszkozatként, jóváhagyásra.

Tömeges jóváhagyás és törlés. Az approve és a delete is elfogad vagy egy kifejezett ids listát, vagy az allDrafts: true értéket egy brandId mellé, opcionálisan importId-vel leszűkítve. Csak a piszkozat sorokat hagyjuk jóvá. Egy szabály nem aktiválható legalább egy kulcs nélkül — a kulcs nélküli szabályokat tartalmazó köteg hibára fut, és megnevezi őket.

A bulk_create mindent vagy semmit. Legfeljebb 200 szabály kerül be egyetlen utasításban; ha a szervezet 20 000 szabályos korlátja beleszól, semmi nem kerül be.

manage_product_source

Beköti és kezeli a katalógusokat, ahonnan a termékek érkeznek.

Paraméterek

Paraméter	Típus	Kötelező	Leírás
`action`	string	Igen	`create`, `update`, `delete` vagy `fetch_now`.
`id`	string	Feltételes	Az `update`, a `delete` és a `fetch_now` esetén kötelező.
`brandId`	string	Feltételes	A `create` esetén kötelező.
`kind`	string	Nem	`api` (alapértelmezett) vagy `csv`. Csak létrehozáskor — utólag nem módosítható.
`name`	string	Feltételes	1–200 karakter. A `create` esetén kötelező.
`url`	string	Feltételes	Legfeljebb 2048 karakter. `api` esetén kizárólag `https`. Egy csak küldésre használt API forrásnak nem kell; egy CSV forrásnak mindig kell.
`secret`	string	Nem	16–256 karakter, csak API forrásoknál. Ha létrehozáskor kihagyod, generálunk egyet. Frissítéskor megadva lecseréli.
`headers`	object	Nem	Legfeljebb 20 `{ key, value }` pár, amit minden beolvasással elküldünk.
`keyFields`	string	Nem	Legfeljebb 20 mezőnév, amelyek értékeiből a termékek kulcsai lesznek.
`intervalDays`	number	Nem	1–30. Alapértelmezés: 1.
`scheduleEnabled`	boolean	Nem	A `false` azt jelenti: csak küldés — soha nem olvasunk be ütemezetten.
`onFailure`	string	Nem	`keep` (alapértelmezett) vagy `hide` — mi történjen a termékekkel, ha a forrás lekapcsol.

Hogyan működik

Egyedül a create válasza mutatja meg a titkot. Visszaadja a forrást, a secret értékét, a push_url címet, ahová a webshopod postázhat, és egy emlékeztetőt arról, hogy a webshop a szervezet API kulcsával hitelesít a Y-API-Key fejlécben. Minden más válasz elhagyja a titkot, és csak a has_secret értéket, valamint az egyedi fejlécek nevét adja vissza.

Csak az api forrás hordozhat szabályokat. A CSV folyam egy Google Shopping fájl — nincs kulcsa, nincs szabálya, nincs küldési végpontja, és megengedett hozzá a http.

A keyFields azonnal életbe lép. A módosítása újraszámolja a forrás minden termékének kulcsait, újbóli beolvasás és újraindexelés nélkül.

A fetch_now forrásonként ötperces várakozási időt tart. Ezen belül az eszköz { started: false } választ ad a hátralévő idővel — ez válasz, nem hiba. Egyébként run_id értéket ad vissza; a befejeződést a product_sources erőforráson futtatott get_record hívással követheted.

Egy forrás törlése törli a termékeit, mindennel együtt, amit az AI megtanult róluk. Az eszköz visszautasítja, amíg beolvasás vagy küldés fut.

Termékek, források és szabályok olvasása

Három erőforrás érhető el az Adathozzáférési eszközökön keresztül, ugyanazzal a Tartalomforrások jogosultsággal:

Erőforrás	Mit tartalmaz
`product_sources`	A katalógusok, ahonnan a termékek érkeznek, az ütemezésükkel és a legutóbbi futásukkal.
`product_rules`	A kötelező érvényű szöveg, a kulcsaival, az állapotával és a módjával.
`products`	Maga a katalógus, minden termék kulcsaival és saját szabálymondataival.

Mindhárom elfogadja a brandId paramétert. A products emellett a sourceId, a product_rules pedig a ruleStatus, a ruleMode és az importId paramétert is. A product_rules és a products egyaránt elfogadja a key paramétert — ez a normalizált kulcs, amin a kettő illeszkedik, tehát az ékezetek és az írásjelek nem számítanak —, valamint a search paramétert, ami a szabály szövegére vagy a termék címére illeszkedik.

A get_record hívásnál egy szabály ezen felül jelenti a matched_products_count értéket (hány termékhez jut el ma), egy termék pedig a matched_rules mezőt (minden rá vonatkozó szabályt, a piszkozatokkal együtt) — a kettő együtt a leggyorsabb módja annak, hogy jóváhagyás előtt ellenőrizz egy szabálykészletet.

Példa utasítások

Create a product API source called "Shop feed" on brand <id>, reading https://shop.example.com/yaplet/products every day, and turn the Ingredients field into keys.

Bulk-create these permitted claims as draft rules on brand <id>, one Always rule per substance — consolidate all of that substance's permitted claims into one rule — keyed on the substance name and its common synonyms.

Show me every product on brand <id> that has no keys, so I know which ones no rule can reach.

How many products does the rule with id <id> currently apply to?