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. Ohranite ga majhnega — odgovori so omejeni na ~10 KB in klic preteče po ~10s.

{
  "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.

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.

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.

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).

Danes ni javnega JS API-ja za registracijo upravljalnikov orodij na strani odjemalca v nalagalniku widgeta. Izvajanje na strani odjemalca je posredovano prek strežnika/iframea — obravnavajte ga kot napredno zmogljivost in ne pričakujte odrezka v slogu registerTool() na vaši strani. Glejte Vgraditev widgeta.

Sorodne teme#

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