Mukautetut HTTP-toiminnot

Mukautetuilla HTTP-toiminnoilla tekoälyagentti voi kutsua omaa HTTPS-rajapintaasi kesken keskustelun: esimerkiksi hakea tilauksen tilan tai luoda tukipyynnön omaan järjestelmääsi. Sinä määrität rajapinnan ja parametrit, agentti täydentää ne keskustelusta ja Aihion palvelin suorittaa kutsun. Oma rajapintasi vastaa pyynnön käyttöoikeuksista ja tietojen oikeellisuudesta.

• HTTP-toiminnot sisältävä tilaus ja oikeus muokata agentin asetuksia.
• HTTPS-rajapinta, jota agentti kutsuu. Vain https hyväksytään, ja kutsut suoritetaan palvelinpuolella SSRF-suojattuna (yksityiset ja sisäverkko-osoitteet estetään).
• Tarvittaessa rajapinnan tunnus (Bearer-token tai API-avain).

1. Avaa Toiminnot-välilehti

   Avaa Oma Aihio, valitse agentti ja avaa Asetukset → Toiminnot. Valitse Lisää toiminto.

2. Määrittele perustiedot

   • Tunniste on toiminnon koneluettava nimi (snake_case, esim. hae_tilaus). Tekoälyagentti viittaa toimintoon tällä nimellä.
   • Kuvaus kertoo tekoälyagentille, milloin toimintoa käytetään. Kirjoita se selkeästi, esimerkiksi “Hae asiakkaan tilauksen tila tilausnumerolla.”
   • URL ja HTTP-metodi (GET, POST, PUT, PATCH tai DELETE). URL:n on alettava merkeillä https://.

3. Lisää parametrit

   Parametrit ovat tietoja, jotka tekoälyagentti kerää keskustelusta ja täyttää kutsuun. Anna jokaiselle parametrille nimi (snake_case), näyttönimi ja tyyppi (teksti, sähköposti tai puhelin). Viittaa parametriin URL:ssä, otsikoissa tai rungossa kaksoisaaltosulkeilla, esimerkiksi https://api.esimerkki.fi/tilaukset/{{tilausnumero}}.

   Voit lisäksi antaa parametrille valinnaisen vihjeen tekoälylle (esimerkiksi “Asiakkaan tilausnumero, kuten ORD-123”). Vihje ohjaa kentän täyttämistä, mutta ei korvaa rajapintasi syötevalidointia.

   Pyynnössä käytetyn parametrin on oltava pakollinen, jotta kutsua ei suoriteta puuttuvilla tiedoilla.

4. Valitse todennus

   • Ei todennusta julkisille rajapinnoille.
   • Bearer-token tai API-avain: syötä tunnus kerran. Se tallennetaan salattuna (Supabase Vault), eikä sitä näytetä enää myöhemmin; vain viimeiset merkit jäävät näkyviin tunnistamista varten.

5. (Valinnainen) Välitä varmennetun käyttäjän tiedot

   Jos keskusteluikkuna varmentaa käyttäjän identiteetin (ks. Identiteetin varmennus ), voit välittää varmennetut tiedot kutsuun viittauksilla kuten {{identity.email}}. Tämä edellyttää, että toiminnossa on Vaadi varmennettu identiteetti käytössä.

   Tunnistetietojen välitys edellyttää JWT-varmennusta. Vain allekirjoitettu JWT tuo {{identity.*}}-kentät HTTP-toimintojen käyttöön. HMAC-tiivistemenetelmällä käyttäjä varmennetaan näyttöä varten, mutta tunnistetietojen viittaukset jäävät tyhjiksi ja kutsu epäonnistuu hallitusti. Käytä allekirjoitettua JWT:tä, jos toimintosi lähettää tunnistetietoja.

   Välitä vain toiminnon tarvitsema tieto ja rajaa sen käyttö vastaanottavassa järjestelmässä. Älä käytä pelkkää keskustelussa ilmoitettua tilausnumeroa todisteena oikeudesta toisen asiakkaan tietoihin.

6. Ota käyttöön ja testaa

   Voit testata toiminnon jo ennen tallennusta: syötä testiarvot lomakkeen Testaa toiminto -osiossa ja suorita kutsu. Näet rajapinnan vastauksen ja tilakoodin. Testi tekee oikean HTTP-kutsun, joten käytä kirjoittaviin toimintoihin testiympäristöä. Todennusta käyttävän toiminnon testaaminen edellyttää tunnuksen syöttämistä.

   Kun toiminto on valmis, kytke se päälle ja kokeile keskustelua, jossa sitä tarvitaan. Tarkista sekä agentin vastaus että oman järjestelmäsi todellinen tulos. Pelkkä onnistunut tilakoodi ei todista, että esimerkiksi oikea tilaus löytyi.

Agentti valitsee toiminnon kuvauksen ja keskustelun perusteella. Tämä ei ole täsmälliseen avainsanaan perustuva sääntö. Agentti täydentää parametrit, ja Aihion palvelin suorittaa HTTP-kutsun. Vastauksesta agentti muotoilee asiakkaalle vastauksen. Rajapintaan välitetään määrittämäsi pyyntö ja siinä käytetyt tiedot, ei automaattisesti koko keskustelua.

Toiminnot-sivun yläosassa on ominaisuuskirjasto: kortit valmiista ominaisuuksista, kuten tietopohjavastauksista, liidienkeruusta ja ihmistuesta. Kortti kertoo yhdellä silmäyksellä kolme asiaa:

• Tila: “Saatavilla” tarkoittaa, että ominaisuuden voi ottaa käyttöön heti; “Tulossa” tarkoittaa, että se on vasta kehitteillä.
• Tilaustaso: jos ominaisuus vaatii nykyistä korkeamman tilaustason, kortissa näkyy tason merkki (esimerkiksi Starter tai Pro). Merkki katoaa, kun taso riittää.
• Määritä: painike vie suoraan oikeaan asetusnäkymään, esimerkiksi tietopohjaan tai ihmistuen asetuksiin.

Ominaisuuskortin valmiustesti tarkistaa asetuksia. Se on eri asia kuin HTTP-toiminnon testikutsu, joka ottaa oikeasti yhteyttä omaan rajapintaasi. Varmenna lopullinen toiminta aina keskustelulla ja vastaanottavan järjestelmän tuloksella.

• Tallennettuja tunnuksia ei näytetä kokonaisina uudelleen. Älä sijoita niitä toiminnon kuvaukseen tai esimerkkiparametreihin.
• Kutsut suoritetaan palvelinpuolella: vain https, portti 443, ei uudelleenohjauksia, vastekoon raja ja aikakatkaisu.
• Yksityiset, sisäverkko- ja metadata-osoitteet estetään (SSRF-suoja).

• Toimintoa ei valita: tarkenna kuvausta ja testaa sekä sopiva että asiaan kuulumaton kysymys.
• Rajapinta hylkää kutsun: tarkista tilakoodi, tunnus ja pakolliset parametrit testiympäristössä.
• Identiteettitieto puuttuu: varmista voimassa oleva JWT ja toiminnon varmennusvaatimus.
• Kirjoitus toistuu: estä kaksoiskäsittely omassa rajapinnassasi. Älä oleta tekoälyn kutsuvan toimintoa vain kerran.

Poista toiminto käytöstä, jos se tuottaa väärän tuloksen. Korjaa ja testaa vastaanotin ennen uudelleenaktivointia. Käyttöönoton peruuttaminen ei peru rajapintaan jo tehtyjä muutoksia.