n8n → Hermes: vali API-kutse või sündmuse veebikonks

n8n sobib ennustatavaks automatiseerimiseks: võta sündmus vastu, valideeri väljad, kutsu API-sid, oota inimese kinnitust ja kirjuta tulemused. Hermes Agent on kasulik etapiks, kus tuleb teksti tõlgendada, näiteks määrata triaaži raskusaste, koostada vastuse mustand, uurida tööriistade abil või otsustada, mida „kiireloomuline“ konkreetses kontekstis tähendab.

On kaks selget mustrit ja neil on erinevad lepingud. Kui n8n vajab agendi tulemust selle valideerimiseks, salvestamiseks, kinnitamiseks või saatmiseks, kutsu Hermese API-serverit. Kui n8n väljastab sündmuse ja Hermes peab tulemuse edastama seadistatud Slacki, Telegrami, GitHubi, e-posti või muusse toetatud sihtmärki, kutsu veebikonksu adapterit.

Kasuta Hermese API-serveri ametlikku dokumentatsiooni, veebikonksu ametlikku dokumentatsiooni ja NousResearchi lähtekoodihoidlat. Siin ei ole dokumenteeritud esimese osapoole Hermese-põhist n8n-i sõlme; n8n kasutab üldist HTTP Requesti sõlme.

Üldine n8n-i saatja peaks kasutama Hermese V2 HMAC-i lepingut. Teistel teenusepakkujatel võib olla adapteripõhine autentimine, näiteks GitHubi allkiri või GitLabi token. Iga marsruut vajab dokumenteeritud saladust. INSECURE_NO_AUTH on mõeldud ainult loopback-testimiseks; praegune Hermes keeldub sellega mitte-loopback-aadressil käivitumast.

Millal üle anda (ja millal mitte)

Hoia n8n-is

• Skeemi valideerimine ja redigeerimine
• Idempotentsusvõtmed ja dedupe (idempotentsus ja inimväravad)
• CRM-i, e-posti ja Slacki integratsioonid selgete pääsuandmetega
• Inimkinnitusjärjekorrad enne välist saatmist
• Ajastuse ja veebikonksu käivitajad

Anna Hermesele

• Mitmeti tõlgendatav klassifikatsioon, mis vajab dokumendi või lähtekoodihoidla konteksti
• Mitmeastmeline uurimine Hermese käituskeskkonna tööriistadega aktsepteeritud võimekuspoliitika alusel
• Mustandamine, mis vajab püsivat mälu või korduskasutatavaid oskusi
• Uurimine privaatsete korpuste üle, milleni agent juba ulatub

Ära anna üle

• Puhas if/then marsruutimine, mida saad väljendada Switch-sõlmedes
• Kõrge mahuga genereerimissilmused, mis kuuluvad kõigepealt odavama klassifikaatori taha
• Saladused, mida n8n ei tohiks kunagi edasi saata (kleebi tokenid Hermese „mugavuse pärast“)

Kui kogu töö on agendikeskne ja käivitub vestlusest, võib sobida paremini sõnumivärava kasutajaliides; vaata OpenClawi ja Hermese tööpõhist võrdlust. Esimese n8n-i agendi loomiseks ilma Hermeseta vaata juhendit esimene AI-agent n8n-is.

Vali leping enne ehitamist

n8n vajab tulemust:
Sündmus → n8n valideerib + hõivab püsiva võtme
         → HTTP Request (Bearer) → Hermes :8642/v1/responses või /v1/runs
         → n8n valideerib tulemuse → inimvärav → ühendus

Hermes edastab sündmuse tulemuse:
Sündmus → n8n valideerib + hõivab püsiva võtme
         → HTTP Request (V2 HMAC) → Hermes :8644/webhooks/<name>
         → Hermese agendikäitus → seadistatud Hermese edastussihtmärk

API-server kasutab vaikimisi aadressi 127.0.0.1:8642, nõuab API_SERVER_KEY väärtust ja avaldab OpenAI-ga ühilduvad marsruudid /v1/chat/completions, /v1/responses ning Runs API. Selle võti annab juurdepääsu Hermese agendi kogu tööriistakomplektile, sealhulgas terminali- ja failitoimingutele, seega hoia sidumine privaatne ja piira helistajat rangelt.

Veebikonksu adapter kasutab vaikimisi porti 8644; selle tervisekontroll on http://localhost:8644/health ja marsruudid asuvad tee /webhooks/<name> all. Veebikonksu käitus saadab tulemuse marsruudi seadistatud deliver sihtmärki. Dokumenteeritud sihtmärkide hulka kuuluvad vestlusplatvormid, GitHubi kommentaarid, e-post, Home Assistant ja log. Üldist HTTP-tagasikutse sihtmärki ei ole määratletud.

n8n jääb SaaS-i ühenduste ja inimese kinnitusetappide püsiva oleku omanikuks. Hermes täidab piiritletud tõlgendamissammu.

Veebikonksu sündmuse leping: väike ja selge

Ära saada kogu n8n-i kirjeobjekti muutmata kujul. Saada selge ülesandeobjekt, millega agent saab tegutseda oletusi tegemata.

Illustratiivne leping:

{
  "application_key": "ticket-18422",
  "task": "Classify severity and draft a support reply. Do not send email.",
  "customer": {
    "name": "Example GmbH",
    "plan": "business"
  },
  "message": "VPN drops every morning around 09:00.",
  "constraints": {
    "output": "json",
    "fields": ["severity", "rationale", "draft_reply"],
    "language": "en"
  }
}

Reeglid:

1. Üks oodatav tulemus marsruudi kohta või üks selge enum tulemustest.
2. Hoia püsiv rakendusevõti n8n-is või ärisüsteemis. Päringukeha väli võib logisid seostada, kuid Hermes ei käsitle seda oma veebikonksu deduplitseerimisvõtmena.
3. Saada sama üleandmise korduskatsetel stabiilne X-Request-ID. Hermes hoiab veebikonksu edastuse ID-sid tund aega vahemälus ning jätab selle akna sees korduva käituse või edastuse vahele.
4. Ütle, mida agent ei tohi teha, näiteks saata, tagasimaksta või kustutada.
5. Eelista tervikmanustele vajalikke katkendeid. Hoia mahukad objektid mujal ja edasta ainult viited, mida Hermes tohib laadida.

Loo igale töövooperele eraldi Hermese veebikonksu marsruut (support-triage, ops-alert) koos oma prompti, filtrite, saladuse, oskuste ja edastusseadistusega. Käsitle iga päringukeha välja ebausaldusväärse sisuna. Kasuta käituseks liivakasti, piira promptimalli, eemalda tarbetud tööriistad ning säilita hävitavate või väljaminevate toimingute kinnitused.

Täpne Hermese V2 HMAC leping

Üldise n8n-i saatja jaoks määravad praegused Hermese dokumendid V2:

• päis X-Webhook-Timestamp: Unixi sekundid;
• päis X-Webhook-Signature-V2: väiketähtedega hex-koodiga HMAC-SHA256;
• allkirjastatud baidid: <timestamp>.<raw-request-body>;
• taasesituse aken: ajatempel peab olema Hermese kellaaegadest ±300 sekundi piires.

V1 päis X-Webhook-Signature on endiselt ühilduv, kuid ei kaitse taasesitusründe eest. Ära kasuta seda uutes töövoogudes. Vaata algset turvalepingut.

Ise majutatud n8n-i allkirjastussõlm

Hoia HERMES_WEBHOOK_SECRET ainult n8n-i protsessi saladuste või keskkonnamuutujate mehhanismis. Ära pane seda Set-sõlme ega kinnitatud töövoo JSON-i. Kasuta Code-sõlmes Node’i sisseehitatud crypto moodulit ainult siis, kui sinu n8n-i konfiguratsioon lubab seda moodulit ja sõlme juurdepääsu keskkonnale:

const { createHmac } = require('crypto');

const timestamp = Math.floor(Date.now() / 1000).toString();
const body = JSON.stringify($json.hermes_payload);
const secret = $env.HERMES_WEBHOOK_SECRET;

if (!secret) throw new Error('HERMES_WEBHOOK_SECRET is not configured');

const signature = createHmac('sha256', secret)
  .update(`${timestamp}.${body}`, 'utf8')
  .digest('hex');

return [{ json: { body, timestamp, signature } }];

Isehostitud n8n-i puhul luba ainult vajalik sisseehitatud moodul, järgides kehtivat Code-sõlme moodulite konfiguratsiooni; ära luba suvalisi väliseid mooduleid. Väliste Task Runnerite puhul seadista NODE_FUNCTION_ALLOW_BUILTIN=crypto väärtusena env-override failis /etc/n8n-task-runners.json, mitte ainult peamises n8n-i konteineris. $env juurdepääs sõltub ka sättest N8N_BLOCK_ENV_ACCESS_IN_NODE. Kui turbepoliitika seda blokeerib, kasuta organisatsioonis heaks kiidetud allkirjastusteenust või saladusega kohandatud sõlme. Ära kleebi saladust töövoogu.

Seadista järgmine HTTP Requesti sõlm:

Ära vali pärast allkirjastamist HTTP-sõlme struktureeritud JSON-redaktorit, sest uuesti serialiseerimine võib baite muuta. Mitte-2xx vastuse korral katkesta töö turvaliselt. Vastus 200 võib marsruudist ja edastuse ID-st olenevalt tähendada edastamist või duplikaati; see ei ole n8n-i jaoks struktureeritud agenditulemus. Ära märgi püsivat n8n-i võtit olekusse completed pelgalt seetõttu, et Hermes sündmuse vastu võttis või edastas.

Kasuta ka ainult LAN-is olevate Hermese veebikonksude puhul dokumenteeritud autentimist. Võrgu lähedus ei ole autentimine. Praegused vaikeväärtused piiravad iga veebikonksu marsruudi 30 päringuni minutis, lükkavad tagasi üle 1 MB päringukehad ning hoiavad päiste X-Request-ID või X-GitHub-Delivery väärtusi tund aega vahemälus. Need on piiratud transpordikontrollid, mitte püsivad ärigarantiid.

Veebikonksu keha sisaldab sageli kliendisõnumeid. Hoia Hermes ja n8n privaatvõrgus või kontrollitud krüpteeritud pealisvõrgus. Kui sisu peab jääma sinu heakskiidetud turvapiiri sisse, eelista Hermese jaoks kohaliku OpenAI-ga ühilduva mudeli baas-URL-i; vaata n8n-i kohalike lõpp-punktide juhendit. HMAC autendib saatjat, mitte päringukeha äriväljade autoreid.

Mis tagasi tuleb ja kes saadab

Liides määrab, kes tulemuse saab.

A. Veebikonksu sündmus Hermese hallatud edastusega

Marsruut käitab agendi ja saadab vastuse seadistatud Hermese edastussihtmärki. n8n saab adapteri oleku, mitte agendi struktureeritud vastuse. Kasuta seda siis, kui sihtkoht on Slack, Telegram, GitHub, e-post või muu dokumenteeritud sihtmärk ning ükski hilisem n8n-i samm ei vaja sisu.

B. API-tulemus tagastatakse n8n-ile

Kutsu POST http://127.0.0.1:8642/v1/responses koos päisega Authorization: Bearer <API_SERVER_KEY>, kui n8n peab vastuse saama. Kasuta /v1/runs, kui agendisamm tuleb esitada ja seda tuleb käitusena jälgida, mitte hoida ühe sünkroonse HTTP-päringuna. API kasutab vaikimisi loopback-aadressi ja nõuab kandjavõtit ka seal.

{
  "model": "hermes-agent",
  "input": "Classify severity and draft a reply. Return the agreed JSON fields."
}

Pärast kutset valideerib n8n vastuseskeemi, seob selle püsiva rakendusevõtmega ja avab inimvärava. Hermese API viieminutiline Idempotency-Key vastusevahemälu võib muuta vahetud korduskatsed turvalisemaks. See ei asenda n8n-i püsivat hõivamist, unikaalsuspiirangut ega ärioleku üleminekut.

Ebaõnnestumismustrid

Kasuta Hermese MCP-d ainult siis, kui Hermes peab tõesti n8n-i liidest vaatlema või käitama. HTTP API-kutse või sündmuse veebikonks on lihtsam, kui see on tegelik leping.

Näide: toe vorm → Hermese API → inimvärav

Illustratiivne õnnelik tee, ilma juurutus- või jõudlusväiteta:

1. Veebisaidi vorm saadab POST-päringu n8n-i veebikonksule /support-intake.
2. n8n valideerib e-posti aadressi, sõnumi pikkuse ja allika enumi ning hõivab võtme ticket-<uuid> püsivalt.
3. n8n redigeerib välju, kui poliitika nõuab, ja ehitab piiritletud ülesande.
4. HTTP Request kutsub Hermese marsruuti /v1/responses pordil 8642 koos kandjapääsutunnuse ja lühiajalise Idempotency-Key väärtusega.
5. Hermes tagastab agenditulemuse n8n-ile.
6. n8n valideerib nõutud väljad ja salvestab mustandi püsiva piletivõtme alla.
7. Kinnitaja aktsepteerib või lükkab salvestatud mustandi tagasi.
8. Ainult aktsepteeritud mustand jõuab n8n-i e-posti- või CRM-ühenduseni.

Hermes ei tohiks selle tee jaoks saada saatmisvõimelisi tööriistu. Prompt võib öelda „ära saada“, kuid võimekuse eemaldamine ja n8n-i väravaga ühendus peavad vastu ka siis, kui ebausaldusväärne sisu püüab agenti ümber suunata.

Sisemise Slacki kokkuvõtte jaoks, mis ei naase n8n-i, kasuta selle asemel veebikonksu liidest: seadista deliver: slack, allkirjasta sündmus, saada stabiilne X-Request-ID ning käsitle adapteri vastust ainult edastusolekuna.

Allkirjastamine ja kellade erinevus

Veebikonksu tee jaoks:

• Jadasta JSON üks kord, allkirjasta täpselt need baidid ja saada täpselt need baidid.
• Hoia n8n ja Hermese kellad sünkroonis; muidu korrektne allkiri lükatakse tagasi, kui see on väljaspool 300-sekundilist akent.
• Praegune esimese osapoole dokumentatsioon ei kirjelda praeguse ja eelmise veebikonksu saladuse samaaegset kasutamist. Kasuta kontrollitud üleminekut või oma juurutatud versiooni dokumenteeritud rotatsiooniprotseduuri.
• Logi allkirja ebaõnnestumised koos marsruudi nime ja mittesalajase korrelatsiooniidentifikaatoriga. Ära kunagi logi saladust.

Kui n8n töötab Dockeris ja Hermes hostil, kasuta stabiilset aadressi, mis on n8n-i protsessi võrgunimeruumist marsruuditav. localhost viitab sellises topoloogias eri nimeruumidele.

Kohandatud tagasikutsed on eraldi integratsioon

Praegune Hermese veebikonksu dokumentatsioon ei loetle üldist HTTP-tagasikutset edastussihtmärgina. Kui sinu juurutus lisab selle kohandatud koodi või tööriistaga, kirjelda seda eraldi integratsioonina ning anna sellele oma fikseeritud sihtkoha lubaloend, autentimine, skeemi valideerimine, SSRF-i piir, püsiv idempotentsus ja vastuvõtutestid. Ära vihja, et sissetuleva veebikonksu keha väli callback aktiveerib Hermese sisseehitatud funktsiooni.

Otsustus-spikker

Minimaalne ehitusjärjekord

API-tulemuse tee jaoks:

1. Luba API-server loopback- või privaatliidesel ja määra API_SERVER_KEY.
2. Kontrolli n8n-i käituskeskkonna võrgust autenditud /v1/models marsruuti ja üht mängulist /v1/responses kutset.
3. Lisa vastuseskeemi valideerimine ja püsiv n8n-i rakendusevõti.
4. Lisa inimvärav enne iga kliendile nähtavat ühendust.
5. Testi korduskatseid viieminutilise API-vahemälu sees ja väljaspool seda.

Sündmuse veebikonksu tee jaoks:

1. Luba veebikonksu adapter ning seadista üks marsruut, saladus, kitsas prompt, piiritletud võimekused ja edastussihtmärk.
2. Kontrolli n8n-i käituskeskkonna võrgust /health marsruuti ja üht V2-allkirjaga mängulist sündmust.
3. Saada stabiilne X-Request-ID ning vaata üle edastatud ja duplikaatvastused.
4. Asenda mänguline käivitaja tegeliku valideeritud sündmuse ja püsiva n8n-i võtmega.
5. Testi päringusageduse, päringukeha suuruse, allkirja, kella, edastuse ning peatatud teenuse tõrkeid.

Vastuvõtutestid enne tootmisliiklust

Säilita API-liidese kohta tõendid, et puuduv või vale kandjavõti lükatakse tagasi, mänguline päring tagastab oodatud skeemi, vahetu korduskatse sama Idempotency-Key väärtusega ei loo teist agendikäitust, viieminutilise vahemälu järel korduva päringu blokeerib või lepitab endiselt püsiv rakendusevõti, peatatud Hermes tekitab nähtava pargitud oleku ning tagasilükatud mustand ei jõua kunagi saatmisühenduseni.

Säilita veebikonksu liidese kohta tõendid, et allkirjastamata päring, muudetud allkirjastatud keha ja 300-sekundilisest aknast väljas olev ajatempel lükatakse tagasi. Kinnita, et allkirjastatud mänguline sündmus jõuab seadistatud edastussihtmärki. Korda seda ühe tunni jooksul sama X-Request-ID väärtusega ning kontrolli duplikaatolekut ilma teise agendikäituse või edastuseta. Seejärel kinnita, et päringusageduse piirangu, liiga suure päringukeha, kättesaamatu sihtmärgi ja peatatud Hermese tõrked on n8n-ile nähtavad.

Integratsioon on piloodiks valmis alles siis, kui asjakohase liidese vastuvõtutestid on läbitud ja vastutus selge. Kandjaautentimine ja HMAC kinnitavad helistaja identiteedi ainult oma dokumenteeritud lepingute piires. Viieminutiline API-vahemälu ja ühetunnine veebikonksu edastuse ID vahemälu on piiratud korduskatsete abivahendid. Püsiv rakenduse idempotentsus, autoriseerimine, kinnituse olek ja äritaaste jäävad n8n-i või ärisüsteemi vastutuseks.