Rakenna ensimmäinen tekoälyagenttisi n8n:llä: liidien luokittelutyönkulku alusta loppuun

n8n:n aliarvostetuin ominaisuus on agenttisolmu. Se muuttaa staattisen työnkulun (”kun X tapahtuu, tee Y”) joustavammaksi: työnkuluksi, jossa tekoälymalli päättää tilanteen perusteella suoritettavat toiminnot.

Tässä artikkelissa rakennamme alusta loppuun todellisen toimivan agentin: liidien luokittelujärjestelmän, joka vastaanottaa uusia liidejä, täydentää niiden tiedot, pisteyttää ne, luonnostelee yksilöllisen vastauksen ja reitittää ne oikeaan paikkaan. Lopuksi ymmärrät sekä n8n-agenttien toimintaperiaatteet että suunnittelumallit, jotka erottavat hyödyllisen agentin hauraasta esittelystä.

Oletamme, että n8n on asennettu joko omalle palvelimelle tai n8n.cloud-palveluun ja että käytössäsi on toimiva API-avain Claudelle tai OpenAI:lle. Jos n8n on sinulle uusi, käy ensin läpi sen perusopas.

Älä anna ensimmäisen version lähettää vastauksia automaattisesti todellisille liideille. Ohjaa luonnokset ihmisen tarkistettaviksi, kunnes käytössäsi on lokit, idempotenssi, pistekynnysarvot ja riittävästi tarkistettuja suorituksia osoittamaan, että työnkulku toimii myös epäsiisteillä syötteillä.

Mitä rakennamme

Työnkulku:

1. Uusi liidi saapuu webhook-kutsulla esimerkiksi lomakkeelta, tapahtumasta tai CRM-järjestelmästä.
2. Agentti täydentää liidin tietoja yritystiedoilla verkkohakua käyttäen.
3. Se pisteyttää liidin kolmella ulottuvuudella: sopivuus, ostoaikomus ja kiireellisyys.
4. Se luonnostelee yksilöllisen vastauksen.
5. Pisteiden perusteella se joko:
   • Vastaa automaattisesti ja luo CRM-tietueen, kun liidi sopii hyvin ja arvio on erittäin varma,
   • Laatii ihmisen tarkistettavaksi vastausluonnoksen ja lähettää Slack-ilmoituksen, kun liidi sijoittuu keskitasolle,
   • Tai vain kirjaa liidin ja lähettää ilmoituksen vastaamatta, kun liidi sopii huonosti.

Tätä mallia voi soveltaa laajasti. Korvaa ”liidien luokittelu” esimerkiksi tukipyyntöjen luokittelulla, hakijoiden seulonnalla, mediakyselyjen käsittelyllä tai asiakaspalautteen reitityksellä — rakenne säilyy samana.

Artikkeliin linkitetty JSON-skeema määrittelee vastaanotettavan tietosisällön. Vahvista sen avulla webhook-syöte ennen kuin agenttisolmu näkee sen.

Lisää agenttia edeltävä validointiportti

Käynnistin ei saa välittää mielivaltaisia lomaketietoja suoraan agentille. Lisää käynnistimen ja agentin väliin validointivaihe:

Portti suojaa työnkulkua virheellisiltä lähetyksiltä, webhookin toistoyritysten kaksoiskappaleilta ja lomakekenttiin piilotetulta kehotesyöttöhyökkäykseltä. Agentti voi edelleen lukea viestin, mutta työnkulku päättää, täyttääkö tietue käsittelyn kelpoisuusehdot.

Ajatusmalli: agentti = LLM + työkalut + silmukka

Ennen rakentamista käydään läpi perusajatus.

Vuonna 2026 ”agentti” tarkoittaa työkaluja käyttävää LLM:ää. Yhden vastauksen tuottamisen sijaan malli päättää, mitä ”työkaluiksi” kutsuttuja toimintoja se käyttää. Jokaisen työkalun palautettua tuloksen malli näkee sen ja päättää seuraavan toiminnon: uuden työkalun, uuden vaiheen tai lopullisen vastauksen.

n8n:n AI Agent -solmu toteuttaa tämän silmukan. Annat mallille:

• Järjestelmäkehotteen eli ohjeet ja toimintatavan.
• Käyttäjäkehotteen eli tämän suorituksen syötteen.
• Joukon työkaluja eli muita n8n-solmuja tai alityönkulkuja, joita malli voi kutsua.

Malli päättää, mitä työkaluja se kutsuu, missä järjestyksessä ja millä argumenteilla. Jokaisen työkalun palattua malli arvioi tilanteen uudelleen. Kun se katsoo tehneensä riittävästi, se palauttaa lopullisen vastauksen.

Tämä eroaa perustavanlaatuisesti staattisesta työnkulusta, koska malli määrittää vaiheiden järjestyksen sinun sijastasi. Agenttisuunnittelun taito koostuu seuraavista asioista:

1. Anna mallille oikeat työkalut: ei liian vähän eikä liian paljon.
2. Kirjoita järjestelmäkehote, joka rajaa mallin toiminnan.
3. Lisää suojakaiteet, jotta toiminta ei poikkea hallitsemattomasti.
4. Suunnittele tuloste niin, että myöhemmät solmut voivat käyttää sitä luotettavasti.

Vaihe 1: käynnistin

Avaa n8n ja luo uusi työnkulku. Käynnistin:

• Solmu: Webhook
• HTTP-menetelmä: POST
• Vastaustila: ”When last node finishes”
• Polku: esimerkiksi /lead-triage

Tämä webhook vastaanottaa liidien lähetykset. n8n antaa URL-osoitteen, jonka voit määrittää lomakelähetysten tai CRM-järjestelmän lähtevän webhookin kohteeksi.

Tallenna työnkulku testausta varten kerran, jotta webhook-osoite aktivoituu, ja valmistele esimerkkisyöte. Tavallinen liidi-webhookin tietosisältö voi näyttää tältä:

{
  "name": "Anna Lehtinen",
  "email": "anna@somecompany.fi",
  "company": "Some Company OÜ",
  "role": "Head of Marketing",
  "message": "Interested in your AI consulting services. We have a team of 10 and need help with prompt engineering training.",
  "source": "website-form",
  "timestamp": "2026-05-15T14:30:00Z"
}

Napsauta ”Test step” ja lähetä testisyöte, jotta näet tietojen kulkevan työnkulkuun.

Vaihe 2: AI Agent -solmu

Lisää webhookin jälkeen AI Agent -solmu. Määritä se seuraavasti:

• Agenttityyppi: Conversational tai uudemmissa versioissa ”Tools Agent” — valitse työkalukutsuja tukeva vaihtoehto.
• Keskustelumalli: Claude (Anthropic) tai OpenAI. Agenttityönkulussa Claude Sonnet 4.5 tai GPT-5 ovat hyviä oletusvalintoja. Päättelymallit toimivat, mutta ovat agenttisilmukoissa hitaampia.
• Muisti: Ei muistia tilattomaan luokitteluun, sillä jokainen liidi on itsenäinen. Käytä monivaiheisiin agenttikeskusteluihin muistisolmua.
• Järjestelmäviesti: Agentin toiminta määritetään tässä. Käytä alla olevaa mallia.
• Käyttäjäviesti: Nouda liidin tiedot webhookista.

Järjestelmäviesti:

You are a lead-triage agent for [Your Company Name], an AI consulting firm.

Your job is to process incoming leads and produce a structured triage decision.

For each lead, you must:

1. Use the `enrich_lead` tool to gather context about the company.
2. Score the lead on three dimensions:
   - Fit: does the lead match our ideal customer profile?
     - Companies of 10-200 people in B2B, manufacturing, or professional services.
     - Roles in marketing, operations, engineering leadership, or executive.
   - Intent: how serious is the inquiry?
     - "Just curious" vs "actively evaluating" vs "ready to buy."
   - Urgency: is there a stated or implied timeline?
3. Use the `score_lead` tool to record the scores.
4. Use the `draft_response` tool to produce a personalised reply.
5. Use the `route_lead` tool with one of: "auto_reply", "human_review", "log_only".

Routing rules:
- "auto_reply" if Fit >= 7/10 AND Intent >= 7/10. The reply will be sent automatically.
- "human_review" if Fit >= 5/10 OR Intent >= 5/10. A human will check before sending.
- "log_only" if Fit < 5/10 AND Intent < 5/10. We just track and move on.

Never invent information. If something is unclear, mark [unclear] in your scoring rationale.

Always end by returning a JSON object with:
{
  "fit_score": <1-10>,
  "intent_score": <1-10>,
  "urgency_score": <1-10>,
  "reasoning": "<2-3 sentences>",
  "drafted_response": "<the email body>",
  "routing": "<auto_reply|human_review|log_only>"
}

Huomaa rakenne. Se sisältää:

• Selkeän tehtävänkuvauksen.
• Täsmällisen prosessin (vaiheet 1-5).
• Täsmälliset pisteytysperusteet.
• Täsmällisen reitityslogiikan.
• Vaaditun tulostusmuodon.

Agentti ei aina noudata rakennetta täydellisesti. Mitä konkreettisempi järjestelmäviesti on, sitä luotettavammin se kuitenkin toteuttaa saman rakenteen jokaisella suorituksella.

Pelkkä JSON-objekti ei riitä. Lisää agenttisolmun jälkeen validointivaihe ja hylkää suoritukset, joista puuttuvat pisteet, joiden reititys ei kuulu sallittuun luetteloon tai joiden vastausluonnos on tyhjä.

Vaihe 3: työkalut

Agentti tarvitsee kutsuttavia työkaluja. n8n:ssä työkalut määritetään agenttisolmun alle, ja niitä voivat olla:

• Alityönkulut.
• HTTP-pyynnöt.
• Sisäänrakennetut työkalusolmut.

Rakennetaan agentille neljä työkalua.

Työkalu 1: enrich_lead

Alityönkulku, joka:

1. Ottaa syötteenä yrityksen nimen ja sähköpostin verkkotunnuksen.
2. Kutsuu HTTP-solmulla verkkohaku-API:a (Perplexity, Serper, Brave Search tai Tavily) yritystä koskevaa hakua varten.
3. Palauttaa 3 virkkeen tiivistelmän yrityksen toiminnasta, likimääräisestä koosta ja mahdollisista merkittävistä tuoreista uutisista.

Työkalun kuvaus, jonka perusteella agentti päättää sen käyttämisestä:

Täydentää liidin tietoja hakemalla yrityksen tiedot. Syöte: yrityksen nimi ja sähköpostin verkkotunnus. Tuloste: lyhyt tiivistelmä yrityksen toiminnasta, likimääräisestä koosta ja mahdollisesta merkittävästä viimeaikaisesta kontekstista.

Työkalu 2: score_lead

Yksinkertainen työkalu, joka vastaanottaa agentin antamat pisteet ja tallentaa ne. Kohde voi olla:

• Google Sheets -rivi.
• Tietokantaan lisättävä tietue.
• CRM:n API-kutsu.

Testauksessa helpoin vaihtoehto on rivin lisääminen Google Sheetsiin. Työkalun kuvaus:

Tallentaa liidin pisteet. Syöte: fit_score, intent_score, urgency_score, reasoning. Tuloste: vahvistus.

Työkalu 3: draft_response

Alityönkulku, joka vastaanottaa liidin taustatiedot ja pisteet ja tuottaa yksilöllisen sähköpostiluonnoksen. Alityönkulku kutsuu sisäisesti toista tekoälysolmua täsmällisellä luonnostelukehotteella:

Laadi yksilöllinen vastaus B2B-tiedusteluun. Syötteet: liidin alkuperäinen viesti, yrityksen tietojen täydennystiivistelmä sekä sopivuus-, ostoaikomus- ja kiireellisyyspisteet.

Tyyli: lämmin, suora, ei yritysjargonia. Huomioi täsmällinen pyyntö. Viittaa johonkin yrityksen täydennetyistä tiedoista, älä yleisluontoisesti. Päätä konkreettiseen seuraavaan vaiheeseen, esimerkiksi ”sopisiko ensi viikolla 15 minuutin keskustelu?”

Pituus: 80-120 sanaa.

Työkalun kuvaus:

Laatii liidille yksilöllisen sähköpostivastauksen. Syöte: liidin viesti, tietojen täydennystiivistelmä ja pisteet. Tuloste: sähköpostiluonnos.

Työkalu 4: route_lead

Viimeinen reititystoiminto. Reititysargumentin perusteella työkalu joko:

• Lähettää sähköpostin ja luo CRM-tietueen (auto_reply).
• Tallentaa luonnoksen ja lähettää Slack-ilmoituksen (human_review).
• Vain kirjaa tapahtuman ja luo CRM-tietueen (log_only).

Tämä toteutetaan alityönkulkuna, jonka switch-solmu reitittää argumentin perusteella kolmelle eri haaralle.

Työkalun kuvaus:

Reitittää liidin luokittelupäätöksen perusteella. Syöte: reitityspäätös (”auto_reply”, ”human_review”, ”log_only”) ja vastausluonnos. Tuloste: vahvistus.

Vaihe 4: testaa agentti

Kun agentti on määritetty ja neljä työkalua on liitetty siihen, suorita testi esimerkkisyötteellä.

n8n:n suoritusnäkymässä pitäisi näkyä seuraavaa:

1. Webhook vastaanottaa tietosisällön.
2. AI Agent käynnistyy.
3. Agentti kutsuu enrich_lead-työkalua — näet työkalun suorituksen ja palautuksen.
4. Agentti valitsee seuraavan vaiheen; mallin ja asetusten mukaan välivaiheiden jäljet saattavat näkyä tai jäädä piiloon.
5. Agentti kutsuu score_lead-työkalua.
6. Agentti kutsuu draft_response-työkalua.
7. Agentti kutsuu route_lead-työkalua yhdellä kolmesta reititysvaihtoehdosta.
8. Agentti palauttaa lopullisen JSON-objektin.

Jos jokin epäonnistuu, n8n:n virheenkorjauspaneeli näyttää agentin ja sen työkalujen väliset viestit. Tavallisimmat ongelmat:

• Työkalun kuvaus ei ole riittävän täsmällinen. Malli ei pysty päättelemään, milloin työkalu sopii tilanteeseen. Tee kuvauksista konkreettisempia.
• Työkalun syöte- ja tulosteskeemat eivät vastaa toisiaan. Agentti ei pysty välittämään oikeita argumentteja. Määritä skeema täsmällisesti.
• Agentti jää ikuiseen silmukkaan. Se kutsuu työkaluja jatkuvasti pääsemättä ratkaisuun. Lisää iteraatioiden enimmäismäärä ja tarkista järjestelmäkehote uudelleen.

Vaihe 5: lisää suojakaiteet

Pelkkä agentti ei ole tuotantokäytössä turvallinen. Lisää kuusi suojakaidetta ennen kuin annat sille todellista liikennettä:

1. Iteraatioiden enimmäismäärä. Aseta agentin iteraatioiden enimmäismääräksi kohtuullinen luku (10-20). Tämä estää hallitsemattomat silmukat, joissa agentti kutsuu työkaluja pääsemättä loppuun.

2. Hyväksyntäportti auto_reply-toiminnolle. Vaikka agentti valitsisi ”auto_reply”, ohjaa se ensimmäisten viikkojen ajan ihmisen hyväksyntäjonon kautta. Varmista agentin automaattisten vastauspäätösten laatu ennen kuin annat niiden lähteä asiakkaille tarkistamatta.

3. Lähtevien toimintojen sallittujen arvojen luettelo. Määritä CRM- ja sähköpostityökalut toimimaan vain tietueille, jotka vastaavat odotettua mallia. Tämä estää agenttia lähettämästä sähköpostia väärään osoitteeseen tai luomasta tietueita muille kuin liideille.

4. Lokitus. Kirjaa jokainen agentin suoritus: syöte, kaikki työkalukutsut ja lopullinen tuloste. Käytä n8n:n sisäisiä suorituslokeja tai lähetä tiedot erilliseen lokipalveluun. Kun jokin epäonnistuu, selvität syyn lokien avulla.

5. Kustannusrajat. Aseta päivittäinen tokenbudjetti. Tekoälyagentti voi karata hallinnasta — väärin määritetty silmukka voi käyttää yhdessä epäonnistuneessa suorituksessa $50 API-kutsuihin. n8n-pilvipalvelussa tämä on sisäänrakennettu; omassa ympäristössä seuraa API-avaimen käyttöä.

6. Päätösvastuu. Malli voi suositella reittiä auto_reply, human_review tai log_only, mutta työnkulun pitää toimeenpanna lopullinen sääntö. Pidä reitityksen sallittu arvojoukko, pistekynnysarvot ja hyväksyntävaatimukset kehotteen ulkopuolella, jotta ne ovat testattavissa ja näkyvissä.

Vaihe 6: vahvista tuotantovalmius

Seuraavat mallit muuttavat toimivan prototyypin ratkaisuksi, johon voit luottaa:

Idempotenssi. Varmista, ettei saman liidin käsitteleminen kahdesti webhookin toistoyrityksen tai käsin tehdyn uuden suorituksen vuoksi luo kaksoiskappaleita. Lisää työnkulun alkuun tarkistus: ”onko tämä liidi käsitelty aiemmin?”

Virheenkäsittely. Ympäröi jokainen työkalukutsu virheenkäsittelyllä. Jos tietojen täydennyksen API ei ole käytettävissä, agentti ei saa kaatua, vaan sen pitää jatkaa vähemmillä tiedoilla ja merkitä puuttuvat tiedot.

Havainnoitavuus. Seuraa tärkeimpiä mittareita: keskimääräistä suoritusaikaa, työkalukutsujen yleisyyttä ja kullekin reitille ohjattujen tapausten osuutta. Poikkeamat ovat signaaleja.

Suoritusten tarkistus. Tarkista ensimmäisten 50 todellisen liidin jokainen suoritus alkuperäistä liidiä vasten. Seuraa väärää yritystietojen täydennystä, virheellisiä pisteitä ja reittejä, huomaamatta jääneitä määräaikoja sekä vastausluonnosten heikkoa laatua. Älä vähennä ihmisen tekemää tarkistusta, ennen kuin nämä virhetilanteet ovat harvinaisia ja ymmärrettyjä.

”Hätäkatkaisin”. Järjestä tapa sammuttaa agentti ilman uutta käyttöönottoa. Yksinkertainen ympäristömuuttuja tai työnkulun alussa tarkistettava valitsin riittää. Se on hyödyllinen, kun huomaat tuotannossa huonon päätöksen ja haluat keskeyttää toiminnan.

Tärkein suunnittelupäätös: agentille annettavat työkalut

Agentin laatu riippuu eniten työkaluvalikoimasta. Virhetilanteita on kaksi:

Liian vähän työkaluja. Agentti ei pysty tekemään työtään. Se yrittää kiertää puuttuvia kyvykkyyksiä, usein sepittämällä tietoja.

Liian paljon työkaluja. Agentti hämmentyy, valitsee väärän työkalun tai tuhlaa iteraatioita vaihtoehtojen tutkimiseen. Laatu heikkenee.

Hyvä sääntö: aloita pienimmästä toimivasta työkaluvalikoimasta ja lisää työkaluja vain, kun agentti osoitettavasti tarvitsee niitä.

Valitsemamme neljä työkalua ovat suunnilleen oikea määrä liidien luokitteluun. Voisit lisätä esimerkiksi:

• ”lookup_existing_customer”-työkalun sen tarkistamiseen, onko liidi jo asiakas.
• Kalenteriisi integroituvan ”schedule_meeting”-työkalun.
• ”translate”-työkalun, jos liidejä saapuu useilla kielillä.

Jokainen uusi työkalu on kuitenkin agentille uusi päätös. Jokaisen on todella ansaittava paikkansa.

Yleiskäyttöiset mallit

Liidien luokitteluun rakentamasi ratkaisu toimii monessa muussa käyttötapauksessa:

Tukipyyntöjen luokittelu. Korvaa tietojen täydentäminen ”lookup_customer_history”-toiminnolla ja reititys vaihtoehdoilla ”auto_solve / escalate / categorise”.

Työnhakijoiden seulonta. Korvaa tietojen täydentäminen ”parse_cv”-toiminnolla, pisteytys rooliin sopivuuden perusteilla ja reititys vaihtoehdoilla ”interview / reject / flag for human review”.

Mediakyselyjen käsittely. Korvaa tietojen täydentäminen ”lookup_publication”-toiminnolla ja reititys tärkeysjärjestykseen perustuvalla vastauksella.

Asiakaspalautteen reititys. Korvaa tietojen täydentäminen tunneanalyysillä ja tuoteluokittelulla.

Hankintapyynnöt. Korvaa tietojen täydentäminen toimittajahauilla, pisteytys käytäntöjen noudattamisella ja reititys hyväksyntätyönkuluilla.

Perusmalli on aina sama: saapuva tapahtuma → täydennä tiedot → pisteytä tai luokittele → luonnostele vastaus → reititä. Agentti tekee päätökset, työkalut toteuttavat ne.

Milloin agenttia EI pidä käyttää

Agentista ei ole hyötyä kaikissa työnkuluissa. Jos logiikka on täysin deterministinen — ”tee aina A, sitten B ja sitten C” — tavallinen n8n-työnkulku ilman agenttia on nopeampi, edullisempi ja luotettavampi.

Agentti ansaitsee paikkansa, kun:

• Mahdollisia reittejä on paljon.
• Oikea reitti riippuu harkinnasta eikä tiukoista säännöistä.
• Joissakin päätöksissä on yhdistettävä tietoja useista lähteistä.

Jos päätöspuusi koostuu muutamasta if-then-else-lauseesta, käytä vain if-then-else-solmuja. Säästä agentti tilanteisiin, joissa if-then-else-rakenne muuttuu hallitsemattomaksi.

Rakenna se kerran todellista työtä varten

n8n:n tekoälyagentti on työnkulku, jossa malli päättää työkaluvalikoiman perusteella, mitä toimintoja suoritetaan ja missä järjestyksessä. Hyvin rakennettuna se käsittelee harkintaa vaativaa monivaiheista työtä, joka edellytti aiemmin ihmisen osallistumista.

Rakentamamme liidien luokittelutyönkulku vaatii n8n-agentteihin vasta tutustuvalta noin kaksi tuntia työtä sekä muutaman viikon hienosäätöä todellisilla tiedoilla. Vastineeksi jokaisen saapuvan liidin tiedot täydennetään, se pisteytetään, sille laaditaan vastausluonnos ja se reititetään muutamassa minuutissa. Ihminen tarkistaa vain tilanteet, joissa tarkistuksesta syntyy todellista lisäarvoa.

Rakenna malli kerran sinulle tärkeään todelliseen työnkulkuun. Agenttisuunnittelun malli on yksi vuoden 2026 tekoälytyön vaikuttavimmista taidoista.