Құралдар

Бұл бет машиналық аудармамен жасалған және тексерілуде. Қателер болуы мүмкін - ағылшын нұсқасын қараңыз.

Оркестратор сайтыңыз туралы сіз берген құралдардан басқа ештеңе білмейді. Құрал — келушінің браузерінде орындалатын функция: каталогтан іздеу, брондауға бөлме қосу, пицца өлшемін орнату, тапсырысты ашу. Құралдарды WebMCP (document.modelContext) арқылы тіркейсіз; виджет оларды оқиды, ал оркестратор солар бойынша жоспар құрады.

Құралды тіркеу

await document.modelContext.registerTool({
  name: "search_products",
  description: "Search the shop catalog by free-text query.",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "What to look for" },
      maxPrice: { type: "number", description: "Upper price limit" },
    },
    required: ["query"],
  },
  async execute({ query, maxPrice }) {
    const items = await shop.search(query, { maxPrice });
    return {
      content: [{ type: "text", text: items.map((i) => `- ${i.name} - $${i.price}`).join("\n") }],
    };
  },
});
js
ӨрісМіндеттіЕскертпелер
nameиә^[a-zA-Z0-9_.-]{1,128}$ үлгісіне сай келеді. Бетте бірегей; атауды екі рет тіркеу қате шығарады.
descriptionиәБос емес жол.
inputSchemaжоқtype: "object", properties және міндетті емес required бар JSON Schema. JSON-ға сериализацияланатын болуы керек.
execute(args, options)иә, шақырылатын болу үшінАргументтер объектісін алады. Нәтиже қайтарады (төменде қараңыз).
annotationsжоқPolyfill сақтайды. Annotations бөлімін қараңыз.

registerTool екінші аргумент ретінде { signal } та қабылдайды; сигналды тоқтату құралды тіркеуден шығарады. Еркін тіркеңіз және тіркеуден шығарыңыз: беттің каталогы оның күйіне қарай өзгере алады (себет құралы тек себет бар кезде, төлем құралы тек төлем қадамында).

Нәтижелер

MCP стиліндегі объектіні, қарапайым жолды немесе кез келген JSON мәнін қайтарыңыз:

return { content: [{ type: "text", text: "Added 2 x Margherita to the order." }] };
return { content: [{ type: "text", text: "Size 'huge' does not exist. Try: small, medium, large." }], isError: true };
js

Оркестратор жауаптың мәтінін сақтайды (content[].text бөліктері, жол немесе соңғы амал ретінде JSON; 4000 таңбада қиылады) және оны кейінгі қадамдарда оқиды, мысалы іздеудің бірінші тауарын таңдау үшін. isError: true болғанда қадам сәтсіз саналады. Қате мәтінін кеңес ретінде жазыңыз: егер ол сіздің басқа құралыңыздың атын атаса («No store is open. Call choose_store first»), планировщик сол құралды іске қосып, қайталайды.

Оркестратор құралды қалай оқиды

Оркестратор құралды сайтқа тән кодтан емес, оның атауы мен схемасынан түсінеді.

  1. Панель ашылғанда виджет getTools() шақырады және каталогты тред үшін бір рет жібереді (бет toolchange іске қосып, каталог шынымен өзгерсе, оны қайта жібереді, 300 мс debounce-пен). Ол name, description және inputSchema (type, properties, required) жібереді.
  2. Оркестратор әр құралды жіктейді. Алдымен атау шешеді: add_to_cart, addToCart және add-to-cart сөздері бірдей. search_*, find_*, checkout, remove_*, get_* сияқты аталған құрал етістігі бойынша танылады. Егер атау ештеңе шешпесе, шағын шешім моделі атауы мен сипаттамасы бойынша таңдайды. Категориялардың бүгін қандай екенін Ниеттер бөлімінен қараңыз.
  3. Хабарлама үшін планировщик құралдарды және олардың ретін таңдайды. Бөлек шағын модель әр шақырудың аргументтерін сіздің схемаңыздан толтырады (enum мәндері, required, сипаттамалар).

Практикалық салдарлары:

  • Түсінікті verb_object атауларын қолданыңыз. Атаудағы қосымша анықтауыштар (add_to_cart қасындағы add_recipe_to_cart) мамандандырылған құралды белгілейді: ол келуші оның enum мәндерінің бірін атағанда қолданылады, әйтпесе қарапайым құрал жеңеді.
  • Келуші айта алатын таңдауларды схемада enum ретінде беріңіз. Әр параметрді description ішінде сипаттаңыз.
  • Атауында remove, delete, clear, empty немесе cancel бар құрал жою ретінде, ал checkout, pay, purchase немесе place + order — төлем ретінде қарастырылады. Бұл екеуін модель ешқашан таңдамайды, сондықтан мұндай құралдарды шынайы атаңыз.
  • Тек оқуға арналған құралдар (get_, list_, view_, check_, status, history) сайттың қазір нені ұстап тұрғанын планировщикке айтады, бұл «бәрі» туралы сұраныстар үшін маңызды.

Каталог шектеулері

Каталог — POST /v1/widget/tools ( Widget API ). Сериализацияланған webmcpTools массиві әдепкіде ең көбі 20 000 таңба болуы мүмкін (WIDGET_MAX_WEBMCP_TOOLS_CHARS); көп болса 413 қайтады. Сипаттамаларды қысқа ұстаңыз.

Әр түрлі салалардан мысалдар

Онлайн-дүкен

document.modelContext.registerTool({
  name: "add_to_cart",
  description: "Add a product to the cart.",
  inputSchema: {
    type: "object",
    properties: {
      productId: { type: "string" },
      quantity: { type: "number", description: "Defaults to 1" },
    },
    required: ["productId"],
  },
  async execute({ productId, quantity = 1 }) {
    await cart.add(productId, quantity);
    return { content: [{ type: "text", text: `Added ${quantity} x ${productId}.` }] };
  },
});
js

Азық-түлік дүкені, электроника дүкені немесе киім дүкені үшін бірдей жұмыс істейді; тек атаулар мен сипаттамалар өзгереді.

Қонақүйді брондау

document.modelContext.registerTool({
  name: "search_rooms",
  description: "Find available rooms for a stay.",
  inputSchema: {
    type: "object",
    properties: {
      checkIn: { type: "string", description: "Date, YYYY-MM-DD" },
      checkOut: { type: "string", description: "Date, YYYY-MM-DD" },
      guests: { type: "number" },
      roomType: { type: "string", enum: ["single", "double", "suite"] },
    },
    required: ["checkIn", "checkOut", "guests"],
  },
  async execute(args) {
    const rooms = await hotel.availability(args);
    if (rooms.length === 0) {
      return { isError: true, content: [{ type: "text", text: "No rooms free on those dates. Try other dates." }] };
    }
    return { content: [{ type: "text", text: rooms.map((r) => `- ${r.id}: ${r.type}, $${r.rate}/night`).join("\n") }] };
  },
});

document.modelContext.registerTool({
  name: "book_room",
  description: "Reserve a room found by search_rooms.",
  inputSchema: {
    type: "object",
    properties: { roomId: { type: "string" }, guestName: { type: "string" } },
    required: ["roomId", "guestName"],
  },
  async execute(args) { /* ... */ },
});
js
Expand code

Пицца конструкторы

document.modelContext.registerTool({
  name: "set_pizza_size",
  description: "Set the size of the pizza being built.",
  inputSchema: {
    type: "object",
    properties: { size: { type: "string", enum: ["small", "medium", "large"] } },
    required: ["size"],
  },
  async execute({ size }) {
    builder.setSize(size);
    return { content: [{ type: "text", text: `Size is now ${size}.` }] };
  },
});

document.modelContext.registerTool({
  name: "add_topping",
  description: "Add a topping to the pizza.",
  inputSchema: {
    type: "object",
    properties: { topping: { type: "string", enum: ["mushrooms", "olives", "pepperoni", "basil"] } },
    required: ["topping"],
  },
  async execute({ topping }) { builder.addTopping(topping); return "ok"; },
});
js

Декларативті форма

Форма JavaScript-сіз де құрал бола алады. Polyfill toolname, tooldescription және toolparamdescription атрибуттарын оқиды және схеманы форма өрістерінен құрады (required өрістер required болады; <select> enum болады):

<form toolname="request_callback" tooldescription="Ask the clinic to call the visitor back." toolautosubmit>
  <input name="phone" required toolparamdescription="Phone number to call" />
  <select name="topic" toolparamdescription="What the call is about">
    <option>appointment</option>
    <option>results</option>
  </select>
  <button type="submit">Send</button>
</form>
html

toolautosubmit болмаса, polyfill өрістерді толтырады да, келушінің жіберуін күтеді.

Құрал қателері

Құрал екі жолмен сәтсіз бола алады.

  • Оны нәтиже ретінде хабарлау. { isError: true, content: [{ type: "text", text: "..." }] } қайтарыңыз. Жұмыс жалғасады: қадам сәтсіз болады, ал мәтін сайттың жауабы ретінде сақталады. Егер жұмыс мақсатқа жете алмаса, ағын error / task_failed арқылы аяқталады, ал сайттың соңғы жауабы hint ретінде беріледі (ең көбі 400 таңба), оны виджет келушіге көрсетеді.
  • Қате лақтыру. Polyfill-де сандық status (100-599) және міндетті емес retryAfter (секундтар, сан немесе сандық жол) бар лақтырылған қате шақыру терезелер арасынан өткенде екеуін де сақтайды (WEBMCP_EXECUTE_TOOL_RESPONSE); сұраушы терезе оларды қайта тексереді және сол өрістері бар қатені қайта лақтырады. Мұны жылдамдық шектеуін білдіру үшін қолданыңыз:
async execute(args) {
  const res = await fetch("/api/search?q=" + encodeURIComponent(args.query));
  if (res.status === 429) {
    throw Object.assign(new Error("Search is rate limited"), {
      status: 429,
      retryAfter: Number(res.headers.get("retry-after") ?? 30),
    });
  }
  // ...
}
js

Annotations

annotations (мысалы, WebMCP ұсынысындағы { readOnlyHint: true }) registerTool арқылы қабылданады, polyfill сақтайды және құралдарыңызды тізімдейтін басқа терезелерге беріледі. Виджет annotations мәндерін оркестраторға жібермейді: ол тек name, description және inputSchema жібереді, ал сервердің сұраныс схемасы басқа өрістерді алып тастайды. Бүгін annotations жоспарлауға әсер етпейді.

Басқа терезелердегі құралдар

Әдепкіде polyfill құралдарыңызды басқа терезелерге ашпайды. Ендірілген бетке, opener-ге немесе iframe-ге осы беттің құралдарын postMessage арқылы тізімдеуге және іске қосуға рұқсат беру үшін, олардың origin-дерін виджетте көрсетіңіз:

<pleiades-chat agent-url="..." publishable-key="pk_..." expose-tools-to="https://shop.example,https://pay.example"></pleiades-chat>
html

Жауаптар әрқашан сұраушының origin-іне жолданады, ешқашан *-ге емес. Бұл тек құралдарды хостайтын бетке керек. <iframe allow="tools" src="..."> ішінен құралдарды тұтынатын бетке керек емес.