Orodja agenta po meri

Dajte AI-ju neposreden dostop do vaših sistemov: definirajte orodja, ki jih LLM lahko pokliče med ustvarjanjem odgovora, da pridobi status naročila, poišče račune, preveri zalogo in več.

Hitre dejstvice#

Za konceptualni pregled glejte Navodila za orodja agenta. Ta stran je tehnična referenca.

Anatomija orodja#

Definicija orodja ima ta polja:

Delovni primer — get_order_status (SERVER_SIDE)#

Definicija orodja

Shema parametrov (JSON Schema)

{
  "type": "object",
  "properties": {
    "order_number": {
      "type": "string",
      "description": "The customer's order number, e.g. ORD-10432"
    }
  },
  "required": ["order_number"]
}

Zahteva, ki jo prejme vaša končna točka

Ob klicu orodja HelpStack pošlje argumente, ki jih je posredoval LLM, kot telo zahteve (za POST/PUT/PATCH), z vašimi konfiguriranimi glavami ter Content-Type: application/json:

POST /orders/status HTTP/1.1
Host: api.YOURCOMPANY.com
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{ "order_number": "ORD-10432" }

Pogodba o odzivu, ki jo mora spoštovati vaša končna točka

Vrnite JSON, ki ga model lahko prebere. Klic preteče po ~10s, odgovor pa je omejen na 128 KB.

Odgovor nad omejitvijo je zavrnjen in ne skrajšan — polovica dokumenta JSON se bodisi ne razčleni bodisi, še slabše, razčleni v drugačen pomen — zato klic ne uspe, AI pa dobi informacijo, da orodje ni na voljo. Enako se zgodi, če telo sploh ni JSON, kar je običajno stran z napako HTML izpred posredniškega strežnika.

Omejitev je varovalo pred končno točko, ki se ji iztrga nadzor (stran z razdeljenim seznamom brez velikosti strani, izpis za razhroščevanje), in ne cilj, h kateremu bi merili. Velikost vas stane tudi pod njo: kar vrnete, se v celoti razčleni, zapiše v dnevnik klicev in postavi pred model, zato se plača v žetonih pri vsakem odgovoru, ki to uporabi. Vrnite tistih nekaj polj, ki jih AI potrebuje za odgovor, ne celotnega zapisa — status naročila, predviden čas dostave in številko za sledenje, ne celotnega objekta naročila.

{
  "status": "shipped",
  "carrier": "DHL",
  "tracking_number": "JD0140...",
  "estimated_delivery": "2026-06-02"
}

AI prejme to koristno obremenitev kot rezultat orodja in jo vpleta v odgovor. Ni zahtevane ovojnice — vrnite katerakoli polja so koristna, vendar jih naredite samorazlagajoča, da jih model pravilno uporabi.

Preverjen e-poštni naslov stranke (vezani parametri)#

Na e-poštnem kanalu je naslov, s katerega je prišlo sporočilo, identiteta stranke. Orodje SERVER_SIDE lahko HelpStack prosi, naj enega od njegovih parametrov izpolni s tem naslovom. Orodje »poišči moja naročila« tako ne potrebuje številke naročila, in nihče ne more AI-ja pregovoriti, da bi poiskal naročila nekoga drugega, samo s tem, da vpiše njegov naslov.

Parametru dodajte "x-helpstack-bind": "conversation.senderEmail":

{
  "type": "object",
  "properties": {
    "customer_email": {
      "type": "string",
      "x-helpstack-bind": "conversation.senderEmail"
    },
    "status": {
      "type": "string",
      "enum": ["open", "shipped", "delivered"],
      "description": "Optional filter by order status"
    }
  },
  "required": ["customer_email"]
}

Kaj se zgodi:

• AI parametra nikoli ne vidi. Preden je orodje ponujeno, je odstranjen iz sheme in iz required.
• HelpStack ga izpolni ob vsakem klicu z naslovom pošiljatelja e-poštnega pogovora, z malimi črkami: v poizvedbenem nizu za GET, v telesu JSON za POST/PUT/PATCH ali v nadomestku {customer_email} v URL-ju. Če AI zanj vseeno pošlje vrednost, je ta zavržena.
• Orodje je ponujeno samo v e-poštnih pogovorih. Klepet na spletni strani, Messenger, Instagram, WhatsApp in drugi kanali nimajo preverjenega naslova, zato AI orodja tam ne vidi in stranko vpraša za podatke, ki jih potrebujejo vaša druga orodja, na primer številko naročila in e-poštni naslov.
• Vezati je mogoče samo orodja SERVER_SIDE in parametre na najvišji ravni, edina podprta vrednost pa je conversation.senderEmail. Vse drugo je ob shranjevanju zavrnjeno.

Iskanje na svoji strani omejite: vrnite podatke te stranke in nič drugega. Vsak odgovor gre na isti naslov, s katerim je bilo orodje poklicano, zato to, kar vrne, prejme lastnik tega poštnega predala.

Pisanje dobrih opisov#

Opis je najpomembnejše polje — to je edina stvar, ki jo LLM uporabi za odločitev, ali in kdaj poklicati orodje.

• Navedite kaj orodje vrne in kdaj ga poklicati ("Pokliči, ko stranka vpraša ...").
• Omenite sprožilne fraze, ki jih stranke dejansko uporabljajo.
• Jasno opišite vsak parameter v description sheme.
• Ostanite pod omejitvijo ~2000 znakov (pogovorno okno za shranjevanje to preverja in prikaže napake).

Varnost in zaščita pred SSRF#

• Samo HTTPS. Navadni HTTP URL-ji so zavrnjeni.
• Seznam blokiranih za SSRF. Notranje/zasebne omrežne cilje (povratna zanka, zasebni obsegi RFC1918, lokalna povezava, končne točke metapodatkov) so blokirani, da orodje ne more biti usmerjeno na notranjo infrastrukturo.
• Skrivne glave. Dajte API ključe/žetone v Glave, ki so lahko šifrirane/zamaskirane namesto shranjene v navadnem besedilu.
• Obravnavajte končno točko orodja kot javno dosegljivo — avtenticirajte zahteve (npr. žeton za prenos v Glavah) in preverjajte vhodne vrednosti pri sebi.

Časovne omejitve in omejitveni parametri#

Napake se postopno razrešijo — pokvarjeno ali počasno orodje nikoli ne blokira odgovora; AI preprosto nadaljuje brez teh podatkov.

Orodja organizacije vs. kanala in semantično filtriranje#

• Orodja se lahko definirajo na ravni organizacije in na ravni kanala.
• Za dani pogovor se orodja na ravni organizacije in kanala združijo, orodje kanala pa prepiše orodje organizacije z enakim imenom.
• Združeni nabor se semantično filtrira glede na ustreznost poizvedbi stranke, tako da velik katalog orodij ne napiha vsakega klica LLM — ponujena so samo relevantna orodja.
• Izbrana orodja se pretvorijo v definicije funkcij OpenAI/Anthropic in ponudijo med ustvarjanjem odgovora.

Uvoz OpenAPI#

Orodja lahko bootstrapirate iz obstoječega API-ja: prilepite ali naložite specifikacijo OpenAPI 3.0, in HelpStack iz nje izvleče operacije v definicije orodij, ki jih pregledate in shranite. To je najhitrejši način za izpostavitev obstoječega REST API-ja AI-ju. Razširitev x-helpstack-bind na parametru ali na shemi lastnosti v specifikaciji se ohrani (glejte razdelek o vezanih parametrih zgoraj).

Beleženje#

Vsak klic orodja se zabeleži v ToolCallLog. Oglejte si zgodovino klicev orodja (argumente, izid, čas) prek:

GET /api/agent-tools/[id]/logs

Uporabite dnevnike za odpravljanje napak, zakaj orodje je ali ni bilo poklicano, in za prepoznavanje prekoračitev časa/napak.

Ponovitve se ne beležijo. Ko HelpStack ponovno predvaja preteklo konverzacijo, da izmeri kakovost odgovorov, se orodje z metodo GET (ali HEAD) pokliče natanko tako kot pri živem odgovoru, zato lahko vaša končna točka prejme poizvedbo za starejše sporočilo. Orodje s katero koli drugo metodo se med ponovitvijo nikoli ne pokliče, klici med ponovitvijo pa se ne pojavijo v ToolCallLog.

Orodja na strani odjemalca (napredno)#

Orodja CLIENT_SIDE so deklarirana enako (ime, opis, shema parametrov), vendar se izvajajo v brskalniku obiskovalca spletnega mesta, posredovano prek vtičnice widgeta:

1. AI odda klic orodja za orodje CLIENT_SIDE.
2. Strežnik pošlje tool:execute widgetu.
3. Widget ga izvede in odgovori z tool:result (ali tool:error).
4. Časovna omejitev je ~5s; ob prekoračitvi se klic postopno razreši (orodje ni na voljo).

Registracija rokovalnika

Skripta pripomočka izpostavi window.HelpStack. Rokovalnik registrirajte po imenu in poklican bo vsakič, ko UI uporabi to orodje:

<script src="https://helpstack.eu/widget.js?id=CHANNEL_ID" async></script>
<script>
  window.HelpStack = window.HelpStack || function () {
    (window.HelpStack.q = window.HelpStack.q || []).push(arguments);
  };

  window.HelpStack('registerTool', 'highlight', async ({ section }) => {
    document.querySelector(`#${section}`)?.scrollIntoView({ behavior: 'smooth' });
    return { highlighted: section };
  });
</script>

Vmesnik čakalne vrste na sredini pomeni, da lahko registrirate preden se widget.js naloži; skripta ob zagonu vrsto izprazni. Kar rokovalnik vrne, je tisto, kar prebere UI, če pa vrže napako, se UI sporoči, da orodje ni uspelo. Ista funkcija je po nalaganju skripte na voljo tudi kot ChatWidget.registerTool(name, fn).

Primeri rokovalnikov

Štirje vzorci, v vrstnem redu, po katerem jih ekipe običajno gradijo. Vsak prikazuje definicijo orodja, ki jo vnesete v nadzorno ploščo, in rokovalnik, ki ga registrirate na svoji strani. Namenoma so majhni: orodje na strani odjemalca naj naredi eno stvar in vrne kratek, preprost objekt.

1. Preberite, kje je obiskovalec (brez parametrov)

Najbolj uporabno prvo orodje. Nič ne stane in prepreči, da bi UI ugibala, kaj obiskovalec gleda.

Definicija

{ "type": "object", "properties": {}, "required": [] }

Rokovalnik

window.HelpStack('registerTool', 'where_is_the_user', async () => ({
  page: location.pathname,
  title: document.title,
  // Whatever "where they are" means in your UI: an open tab, a wizard step, a route.
  section: document.querySelector('[data-active-section]')?.dataset.activeSection ?? null,
}));

2. Pokažite na nekaj na strani

Definicija

{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "description": "What to highlight, in the customer's own words: a button label, a section name, or a menu item."
    }
  },
  "required": ["target"]
}

Rokovalnik

window.HelpStack('registerTool', 'highlight', async ({ target }) => {
  const el = document.querySelector(`[data-tour="${CSS.escape(target)}"]`);
  if (!el) {
    // Not found is a normal outcome, not a failure. Say so and let the AI recover.
    return { found: false, target };
  }
  el.scrollIntoView({ behavior: 'smooth', block: 'center' });
  el.classList.add('hs-highlight');
  setTimeout(() => el.classList.remove('hs-highlight'), 3000);
  return { found: true, target };
});

3. Preberite vsebino nazaj UI

Definicija

{
  "type": "object",
  "properties": {
    "section": { "type": "string", "description": "Section name as the customer would say it." }
  },
  "required": ["section"]
}

Rokovalnik

window.HelpStack('registerTool', 'read_section', async ({ section }) => {
  const root = document.querySelector(`[data-section="${CSS.escape(section)}"]`);
  if (!root) return { found: false, section };

  const fields = {};
  root.querySelectorAll('[data-field]').forEach((el) => {
    // Keep it small — the result goes into the AI's context on every call.
    fields[el.dataset.field] = (el.value ?? el.textContent ?? '').trim().slice(0, 500);
  });
  return { found: true, section, fields };
});

Vrnite ključe polj, ki jih UI lahko citira nazaj. Prav to omogoča orodje za pisanje, kakršno je naslednje.

4. Napišite nekaj za obiskovalca

Najbolj dragocen vzorec in tisti, pri katerem je potrebna največja previdnost: UI zdaj spreminja zaslon obiskovalca.

Definicija

{
  "type": "object",
  "properties": {
    "section": { "type": "string", "description": "Section name, as returned by read_section." },
    "field":   { "type": "string", "description": "Field key exactly as read_section returned it." },
    "text":    { "type": "string", "description": "The complete new contents of that field." }
  },
  "required": ["section", "field", "text"]
}

Rokovalnik

window.HelpStack('registerTool', 'fill_field', async ({ section, field, text }) => {
  const el = document.querySelector(
    `[data-section="${CSS.escape(section)}"] [data-field="${CSS.escape(field)}"]`
  );
  if (!el) return { written: false, reason: 'field not found', section, field };

  el.value = text;
  // Frameworks that track their own state need to be told.
  el.dispatchEvent(new Event('input', { bubbles: true }));
  el.scrollIntoView({ behavior: 'smooth', block: 'center' });
  return { written: true, section, field };
});

⚠️ Izpolnite, ne pošljite. Pustite obiskovalcu, da spremembo prebere in sam pritisne shrani. Orodje, ki objavi namesto njega, iz koristnega predloga naredi nepovrnljivo dejanje, UI pa rezultata ne vidi.

Pisanje rokovalnikov, ki se lepo obnašajo

• Vračajte majhne, preproste objekte. Rezultat se ob vsakem klicu vključi v kontekst UI. Vrnite { found: true, section, fields }, nikoli vozlišča DOM, komponente ali 50 KB velikega bloba.
• »Ni najdeno« je rezultat, ne napaka. Vrnite { found: false } in pustite UI, da pove kaj smiselnega. Vržena napaka pomeni odpoved orodja in UI izve le, da se je nekaj pokvarilo.
• Ostanite krepko pod ~5-sekundno časovno omejitvijo. Nobenih omrežnih klicev, na katere bi moral obiskovalec čakati. Če potrebujete svoj zaledni sistem, naredite raje orodje SERVER_SIDE.
• Nikoli ne razkrijte ničesar, česar obiskovalec ne vidi že sam. Orodje na strani odjemalca teče na javni strani brez lastnega overjanja. Ne berite žetonov za overjanje, podatkov drugih strank ali česar koli za vašimi preverjanji dovoljenj.
• Parametre poimenujte v jeziku stranke, ne v jeziku svoje sheme. UI jih zapolni iz tega, kar je stranka napisala. target: "gumb za shranjevanje" deluje; elementId: "btn-save-primary" ne.

Osnovni protokol

registerTool je tanka ovojnica okoli postMessage in sporočila lahko odgovorite tudi sami — uporabno, če že imate usmerjevalnik sporočil ali če želite streči orodju, ki ga pripomoček ne pozna.

⚠️ Če rokovalnik registrirate prek window.HelpStack, istega orodja ne odgovarjajte še z lastnim poslušalcem. Iframe upošteva prvi odgovor na posamezno callId, zato se dva odgovora poženeta v tekmo. Pripomoček ostane tiho pri orodjih, za katera nima rokovalnika, prav zato, da obstoječi lastni poslušalec deluje naprej.

Iframe pripomočka vsak klic na strani odjemalca pošlje nadrejenemu oknu:

{ type: 'TOOL_EXECUTE', callId: '…', toolName: 'highlight', parameters: { … } }

Nato čaka na enega od teh odgovorov, ujetega po callId:

{ type: 'TOOL_RESULT', callId: '…', result: { … } }   // whatever the AI should read
{ type: 'TOOL_ERROR',  callId: '…', error: 'why it failed' }

Torej zadostuje rokovalnik na vaši strani:

window.addEventListener('message', (event) => {
  // Required. Without this check any page in an iframe could drive your tools.
  if (event.origin !== 'https://helpstack.eu') return;
  const { type, callId, toolName, parameters } = event.data ?? {};
  if (type !== 'TOOL_EXECUTE') return;

  const reply = (result) =>
    event.source.postMessage({ type: 'TOOL_RESULT', callId, result }, event.origin);
  const fail = (error) =>
    event.source.postMessage({ type: 'TOOL_ERROR', callId, error }, event.origin);

  if (toolName === 'highlight') {
    const el = document.querySelector(parameters.selector);
    if (!el) return fail('No element matches that selector.');
    el.scrollIntoView({ behavior: 'smooth', block: 'center' });
    el.classList.add('my-highlight');
    reply({ ok: true, message: 'Highlighted it. Tell the customer to look at the ring.' });
  }
});

Tri stvari, ki jih velja vedeti, preden na tem gradite:

• Odgovorite znotraj 5-sekundne omejitve in odgovorite iskreno. Ob poteku časa se klic razreši v { success: false, error: 'timeout' } in UI nadaljuje brez njega. Ne odgovarjajte, preden veste, da je dejanje uspelo — UI, ki ji rečete »označeno«, čeprav ni bilo označeno nič, bo stranko poslala iskat nekaj, česar na njenem zaslonu ni, in to je slabše od nobenega orodja.
• Kar zapišete v result, je tisto, kar prebere UI. Stavek, ki pojasni, kaj se je zgodilo, vam prinese boljši odgovor kot { ok: true }.
• Obiskovalec morda ni na strani, ki to zmore. Vrnite rezultat, ki to pove, namesto da tiho odpoveste, da lahko UI to pojasni.

To združite z window.ChatWidget.identify(identity, metadata), da UI ve, kateremu računu pomaga, preden karkoli pokliče.

Gumbi za dejanja (CLIENT_ACTION)#

Orodje CLIENT_SIDE se zažene v trenutku, ko ga UI pokliče. To je prav za branje strani in narobe za vse, kar mora obiskovalec videti: na telefonu odprt klepet prekrije celo stran, zato se stran spremeni za njim in obiskovalec tega ne opazi. Še huje, odgovor nato pravi »Odprla sem vam Mojo ekipo« o nečem, česar obiskovalec sploh ni videl.

Orodje CLIENT_ACTION deklarirate enako (ime, opis, shema parametrov), vendar ga HelpStack nikoli ne zažene, ko ga UI pokliče:

1. UI pokliče orodje. HelpStack preveri argumente glede na vašo shemo (argumenti, ki jih niste deklarirali, se zavržejo) in odgovoru pripne gumb. UI izve, da je bil gumb le ponujen, zato napiše »tapnite Pokaži mi«, nikoli »odprla sem«.
2. Obiskovalec vidi odgovor z gumbom pod njim.
3. Ko ga tapne, se pripomoček umakne, če prekriva stran (privzeto na telefonih), in na dnu zaslona pusti majhen gumb Nazaj v klepet.
4. Zažene se rokovalnik vaše strani. Ob uspehu gumb Nazaj v klepet ostane, dokler ga obiskovalec ne tapne. Ob neuspehu se klepet vrne z vašim sporočilom pod odgovorom.

Odgovor ima največ 2 gumba. Gumbi obstajajo samo v spletnem klepetu: na e-pošti, WhatsAppu in drugih kanalih UI teh orodij sploh ne dobi na voljo.

Registracija rokovalnika dejanja

<script>
  window.HelpStack = window.HelpStack || function () {
    (window.HelpStack.q = window.HelpStack.q || []).push(arguments);
  };

  window.HelpStack('registerAction', 'show_element', async ({ element }) => {
    const el = document.querySelector(`[data-help="${element}"]`);
    if (!el) return { ok: false, message: 'That part of the page is not here.' };
    el.scrollIntoView({ behavior: 'smooth', block: 'center' });
    el.classList.add('help-highlight');
    return { ok: true };
  });
</script>

• Za poročanje o neuspehu vrnite { ok: false, message }. Obiskovalec vidi message v klepetu, UI pa ga prebere v naslednjem koraku. Če vrnete karkoli drugega ali nič, to šteje kot uspeh. Vržena napaka je neuspeh.
• Rokovalnik ima na voljo 10 sekund. Navigacija in čakanje na element običajno trajata manj kot 3.
• Obstoječe orodje CLIENT_SIDE lahko v obrazcu za urejanje ali z update_agent_tool preklopite na CLIENT_ACTION (in nazaj); ohrani ime, parametre in zgodovino klicev. Drugih sprememb tipa ni mogoče narediti.
• Isto ime lahko registrirate z registerTool in z registerAction. Katerega dobi UI, odloča tip orodja v HelpStacku.
• Če stran rokovalnika ni registrirala (stara stran, drugo spletno mesto), je gumb prikazan kot onemogočen.
• Gumbi ostanejo v pogovoru in po ponovnem nalaganju spet delujejo, če stran rokovalnik znova registrira.

Besedilo gumba

HelpStack vsakemu orodju CLIENT_ACTION, ki ga vidi UI, doda neobvezen parameter label, da lahko gumb ubesedi v jeziku odgovora (največ 24 znakov). Vaš rokovalnik label nikoli ne prejme. Brez njega na gumbu v jeziku pogovora piše »Pokaži mi« (»Show me«, »Ukáž mi«, »Zeig es mir« ...).

Kaj pripomoček naredi ob tapu

Nastavite za vsak kanal posebej v Kanali → Videz → Ko obiskovalec tapne gumb »Pokaži mi«:

»Cel zaslon« pomeni tisto, kar obiskovalec vidi v tem trenutku, ne ugibanja na podlagi imena brskalnika.

API pripomočka

Ti klici delujejo na vsaki strani z widget.js, z gumbi ali brez njih:

Dnevniki

Vsak gumb zapiše do štiri vrstice ToolCallLog: OFFERED, ko ga je UI pripela, TAPPED, ko ga je obiskovalec tapnil, nato SUCCESS ali FAILED s sporočilom vašega rokovalnika. Klic, ki ga je HelpStack zavrnil (neveljavni argumenti, tretji gumb), se zabeleži kot FAILED skupaj z razlogom.

Sorodne teme#

• Navodila za orodja agenta
• Referenca API
• Vgraditev widgeta
• Slovar