Hermese veebikonksud: sündmusepõhised agendid ilma ühe kõikehõlmava promptita

Ajastus küsib „kas on aeg?“, veebikonks aga teatab: „see juhtus praegu, tegutse“. Agendi töö jaoks on see eristus oluline. Postkasti ajastatud läbivaatamine erineb olukorrast, kus Stripe’is algatati vaidlus või põhihoidu suunatud tõmbetaotlus avati.

Hermes Agenti veebikonksud muudavad autenditud HTTP POST-sündmused agendikäitusteks, mille tulemused lähevad seadistatud edastussihtmärki. Hästi seadistatuna on need lukustatud uksed, millest igaüks viib ühe selge tööni. Halvasti seadistatuna on tulemuseks avalik port ja üks ülepaisutatud prompt, mis püüab töödelda kõiki internetist saabuvaid JSON-andmeid.

Artikkel käsitleb marsruudi kujundust, lähtepakkujale sobivat autentimist, dokumenteeritud tervisekontrolli ja praktilist suitsutesti. Enne teenuse avamist mujale kui localhost seo see esimese nädala turvalise seadistusega.

Millal on veebikonks õige käivitaja

Eelista veebikonkse, kui:

• Latentsus loeb (vaata PR üle, kuni autor on veel konteksti vahetamas).
• Lähteesüsteem juba väljastab sündmusi (GitHub, GitLab, Jira, Stripe või sisemised vormid).
• Iga sündmus peaks muutuma üheks keskendunud ülesandeks, mitte pikaks vestlussessiooniks.

Eelista ajastatud tööd, kui:

• Jälgid triivi korduvate päringutega („kas mõni sert aegub 14 päeva jooksul?“).
• Lähteesüsteem ei saa sündmust ise saata.
• Tahad vaikset perioodilist ülevaadet, mitte sündmuse-põhiseid katkestusi.

Hermese ametlik juhis järgib sama jaotust: ajastus sobib perioodilisteks kontrollideks ja veebikonksud sündmuse käivitatud töödeks.

Arhitektuur ühes pildis

Lähteesüsteem (GitHub / GitLab / n8n / oma rakendus)
        |  HTTPS POST + allikale sobiv autentimine
        v
Hermese veebikonksu adapter (vaikeport 8644)
        |  route: /webhooks/<name>
        v
Nimelise marsruudi seadistus (filtrid + prompt + edastus)
        v
Agendi käitus (oskused ja tööriistad sinu kinnitusreeglite alusel)
        v
Seadistatud edastus (vestluskanal, GitHubi kommentaar või logi)

n8n võib paikneda sisendi valideerimise ja koondamise kihis: kontrolli välju, eemalda tarbetu sisu ning saada alles seejärel minimeeritud päringukeha Hermesele. See on Hermese ja n8n-i võrdluses kirjeldatud näitlik arhitektuur, mitte dokumenteeritud valmislahendus. Kui n8n vajab agendi tulemust oma töövoogu tagasi, kutsu veebikonksu adapteri sünkroonseks tagasihelistuseks pidamise asemel eraldi Hermese API-serverit vaikepordil 8642 ja kasuta kandjaautentimist.

Seadistustee (kontrolli elavate dokumentide vastu)

Upstreami veebikonksu dokumentatsioon kirjeldab järgmist teed:

1. Luba veebikonksude tugi (hermes gateway setup või keskkonnamuutuja, näiteks WEBHOOK_ENABLED=true).
2. Seadista iga marsruudi jaoks saladus. Kasuta allikast olenevalt GitHubi HMAC-päist, GitLabi lihtteksti tokenipäist või üldist V2 ajatempliga HMAC-i.
3. Loo seadistuses või käsuga hermes webhook subscribe nimega marsruut; kontrolli käsku kehtivast dokumentatsioonist.
4. Tervisekontroll: curl http://localhost:8644/health
5. Suuna väline süsteem aadressile https://your-host/webhooks/<name>
6. Saada autenditud katsepäring ning kontrolli oodatud marsruuti, prompti, tööriistade ulatust ja edastussihtmärki.

Vaikimisi dokumenteeritud port on 8644. Dokumenteeritud vaikeväärtused piiravad marsruudi ka 30 päringuni minutis ja lükkavad tagasi üle 1 MB päringukehad. Kui muutsid neid väärtusi, testi vaikeväärtustele toetumise asemel seadistatud piiranguid.

Staatilised seadistusmuudatused võivad nõuda paigaldatud versiooni dokumentatsioonis kirjeldatud värava elutsüklit. Käsuga hermes webhook subscribe loodud dünaamilised marsruudid laaditakse kuumalt ilma taaskäivituseta ja saavad automaatselt loodud saladuse. Mõlemal juhul kontrolli, et väravaprotsess näeb õiget profiili ja keskkonda; interaktiivses käsukestas õnnestunud käsk ei tõenda, et taustateenusel on sama seadistus.

Marsruudi autentimine ei ole valikuline

Iga marsruut peab saladuse pärima või ise määrama, vastasel juhul ei käivitu adapter. Autentimine sõltub teenusepakkujast: GitHub kasutab päist X-Hub-Signature-256, GitLab täpselt sobivat päist X-Gitlab-Token ja üldised kohandatud saatjad V2 ajatempliga HMAC-i. Saatja autentimine tõendab, milline saladuse valdaja päringu saatis, kuid ei muuda päringukeha juhiseid usaldusväärseks.

Reeglid, mis peavad tootmises vastu:

• Loo pikk juhuslik saladus ning hoia seda saladuste halduris või piiratud õigustega keskkonnafailis, mitte oskuse Markdown-failis, mida agent võib lugeda.
• Eelista marsruudipõhiseid saladusi, kui süsteemidel on erinev usaldustase, näiteks GitHubi rakendusel, sisemisel vormil ja partneri veebikonksul.
• Lükka allkirjata või kehtetud allkirjad servas tagasi; ära „logi ja jätka.“
• Kasuta INSECURE_NO_AUTH ainult ajutiseks loopback-testimiseks. Adapter keeldub käivitumast, kui see väärtus on seotud mitte-loopback-aadressiga, näiteks 0.0.0.0 või LAN-aadressiga.

Kasuta uute saatjate jaoks Hermese kehtivat generic V2 skeemi: X-Webhook-Timestamp sisaldab Unixi aega sekundites ning X-Webhook-Signature-V2 on sõne <timestamp>.<raw-body> väiketähtedes HMAC-SHA256 räsi. Hermes lükkab tagasi ajatemplid, mis jäävad lubatud ±300 sekundi vahemikust välja. V1 allkirjastab ainult päringukeha ega kaitse taasesitusründe eest, seega ära ehita sellele uusi saatjaid; vaata ametlikku veebikonksu turbelepingut.

Taasesitatav allkirjastatud suitsutest

Pärast marsruudi support-triage loomist pane mittetundlik sisu faili payload.json. Seadista WEBHOOK_SECRET heakskiidetud saladuste sisestusmehhanismi abil enne käsukesta käivitamist; ära sisesta tootmissaladust käsurea ajalukku. Allolev Node’i käsk loeb võtme keskkonnast, ei lisa seda protsessi argumentidesse ja allkirjastab faili täpsed baidid:

: "${WEBHOOK_SECRET:?inject a disposable route secret before running this test}"
timestamp="$(date +%s)"
signature="$(TIMESTAMP="$timestamp" node -e '
  const { createHmac } = require("node:crypto");
  const { readFileSync } = require("node:fs");
  const hmac = createHmac("sha256", process.env.WEBHOOK_SECRET);
  hmac.update(`${process.env.TIMESTAMP}.`, "utf8");
  hmac.update(readFileSync("payload.json"));
  process.stdout.write(hmac.digest("hex"));
')"

curl --fail-with-body \
  -H 'Content-Type: application/json' \
  -H "X-Webhook-Timestamp: $timestamp" \
  -H "X-Webhook-Signature-V2: $signature" \
  --data-binary @payload.json \
  http://127.0.0.1:8644/webhooks/support-triage

Seejärel korda ilma mõlema allkirja päiseta ja vanema kui 300 sekundi ajatempliga. Mõlemad peavad tagasi lükkama. Ära kleepa reaalset saladust ekraanipiltidesse, piletitesse ega shelli ajalukku; kasuta dokumentatsioonitestideks ühekordset marsruudi saladust ja muuda see pärast seda uueks.

Avalik veebikonks, mis võib anda ründaja juhitud teksti terminalivõimelisele agendile, loob tööriistade kaugkäivitamise riski. Autentimine piirab sündmuste saatjaid, kuid autenditud päringukeha tekst võib siiski olla vaenulik. Kasuta TLS-i ja võrgupiiranguid, minimeeri päringukeha, piira või keela terminali-, faili- ja väljundtoimingute tööriistad ning isoleeri käivitus hostist. Kinnitusküsimused kaitsevad operaatori kavatsust, mitte ei isoleeri vaenulikku sisendit.

Mida päringukehasse panna

Saada agendile leping, mitte toore tulekahjuvoog:

{
  "event_type": "github.pull_request.opened",
  "repo": "acme/api",
  "pr_number": 1842,
  "title": "Add billing retry worker",
  "author": "ada",
  "base_ref": "main",
  "html_url": "https://github.example.invalid/acme/agent-service/pull/1842",
  "task": "Summarize risk for main. List missing tests. Do not approve or merge."
}

Eemalda kasutamata väljad. Mahukad töövoo andmeväljavõtted raiskavad konteksti ja soodustavad segast tööriistakasutust. „Väike, selge ülesandega päringukeha“ on selle artikli kujundussoovitus, mitte väide ametliku n8n-i integratsiooni kohta.

Marsruudi disain: palju väikseid uksi

Ära ehita /webhooks/everything. Ehita nimetatud marsruudid filtrite ja promptidega:

Iga marsruut peaks vastama:

1. Milliseid sündmusi võetakse vastu?
2. Mis on üks oodatav väljund?
3. Millised tööriistad on selle marsruudi agendiprofiilile lubatud?
4. Kuhu tulemus läheb?
5. Mis juhtub tõrke korral: kas tehakse korduskatse, lisatakse töö nurjunud sõnumite järjekorda või teavitatakse inimest?

Veebikonksu päringukeha sisaldab sageli e-posti aadresse, konto ID-sid või sõnumitekste. Vähenda väljade hulka enne, kui andmed Hermesesse jõuavad. Marsruudiskeem ei dokumenteeri marsruudipõhist mälukirjutuse lülitit. Kasuta eraldi profiili, milles mälu on keelatud või memory.write_approval lubatud, ja testi, mis säilib. Kui agendi arutluskäiku pole vaja, kasuta agendi käivitamise asemel dokumenteeritud režiimi deliver_only.

Tervisekontrollid ja opereeritavus

Dokumenteeritud tervisekontrolli lõpp-punkt on http://localhost:8644/health või sinu seadistatud server ja port. Kasuta seda:

• Kohalikeks suitsutestideks pärast funktsiooni lubamist
• Dockeri või Kubernetese valmisolekukontrollideks
• Välisteks tööolekukontrollideks privaatse tervise-URL-i kaudu, mitte autentimata veebikonksu marsruudi kaudu

Logi ka:

• Allkirja ebaõnnestumised (võimalik rünnak või valesti seadistatud saladus)
• Päringukeha valideerimise tõrked
• Agendijooksu kestus ja tööriistakinnituste keeldumised
• Tulemuse edastamise tõrked, näiteks vestlus-API katkestus

Ilma nende signaalideta on „agent tundus kõikuv“ sinu ainus intsidentide raport. Need kirjed parandavad jälgitavust, kuid ei moodusta automaatselt täielikku ja manipuleerimiskindlat auditijälge.

Näide: GitHub PR avatud → keskendunud jooks

Eesmärk: Kui PR avaneb main vastu, mustandab Hermes inimestele riskimärkme. See ei merge’i, ei kinnita ega kommenteeri, kuni sa hiljem lisad üle vaadatud edastustee.

1. Loo marsruut gh-pr-opened. Seadista GitHubi otseedastuse korral päise X-Hub-Signature-256 kontrollimiseks jagatud saladus; üldise n8n-i vahendaja korral rakenda selle asemel V2 ajatempliga HMAC-i leping.
2. Filtreeri pull_request / opened / base main.
3. Promptileping: võta kokku eesmärk, muudatuse mõjuala, puuduvad testid ja juurutusrisk; märgi ebaselge teave; ära anna ühendamisjuhiseid.
4. Tööriistad: vajaduse korral kirjutamisõiguseta GitHubi päring; käsukest on keelatud või nõuab kinnitust.
5. Edastus: postita Markdowni-vormingus märge sisekanalisse; järgmised sammud otsustab inimene.

Hea agendi väljundi kuju (illustratiivne struktuur; sinu mudeli sõnastus varieerub):

PR #1842: Lisa arvelduse taaskatse töötaja (ada harust main-harusse)

Faktid
- Puudutab arveldustöötajat ja järjekorra seadistust (esitatud pealkirja/faililoendi põhjal).
- Lingitud URL: `https://github.example.invalid/acme/agent-service/pull/1842` (näitlik)

Riskid
- Taaskatsete torm, kui tagasivõtu viivitus puudub [inference; verify in diff]
- Pealkiri ei maini idempotentsusvõtmeid [unclear]

Puuduvad testid, mida tuleb kinnitada
- Duplikaattarne / vigase sõnumi käitumine
- Hoiatus, kui taaskatse eelarve saab otsa

Ära ühenda koodimuudatust selle märkme põhjal. Inimene peab muudatuse ise üle vaatama.

See on sündmusepõhine agendijooks stoppreegliga. See ei ole autonoomne koodiomanik.

Harjutus: kujunda kolm marsruuti enne, kui ühe lubad

Kirjuta paberile või oma käitusjuhendisse kolm tarkvarapinule sobivat veebikonksu marsruuti. Määra igaühe kohta järgmine:

• Nimi
• Allikas + sündmusefilter
• Autentimismeetod ja saladuse omanik
• Päringukeha väljad: alusta teadlikult väikese mahu ehk kuni kümne väljaga
• Prompt: alusta maksimaalselt 8 reaga, lisa siis ainult see, mida marsruudi evalid nõuavad
• Lubatud tööriistad
• Edastuse sihtmärk
• Ebaõnnestumise käitumine

Juuruta esmalt kõige väiksema riskiga marsruut, tavaliselt sisehoiatus või ainult mustandit koostav tõmbetaotluse kokkuvõte. Tee curl-päring lõpp-punkti /health, seejärel autenditud POST-katsepäring ja vigase autentimisega katse ning lõpuks üks tegelik sündmus mittetootmiskasutuses lähtekoodihoidlas või proovikeskkonnas.

Oodatavad ebaõnnestumismustrid

• Saladuse mittesobivus pärast rotatsiooni: autentimine ebaõnnestub; paranda väravaprotsessi kasutatavat keskkonda, mitte ainult oma sülearvuti shelli.
• Liiga lai prompt: agent improviseerib tööriistu; jaga marsruut.
• Korduskatsete torm: allikas kordab POST-päringuid. Hermes hoiab edastuse ID-sid tund aega vahemälus, kuid sisuline deduplitseerimine nõuab stabiilset päist X-GitHub-Delivery või X-Request-ID. Kliendinähtavad toimingud vajavad endiselt püsivat äri-idempotentsust, mille säilitusaeg vastab taasesitusaknale.
• Mälu saastumine: suure mahuga hoiatused jõuavad püsivasse mällu; kasuta eraldi profiili ja selgeid mälusätteid.
• Avalik port: terviseseire ja veebikonksud on ligipääsetavad ilma kavandatud TLS-i ja võrgupiiranguteta; paranda võrk enne tööriistade lisamist.

Viited, mida hoida avatuna

• Hermese veebikonksu adapter
• Hermese API-server
• Hermese turbemudel
• Hermese dokumentatsioon
• Sisemine: /articles/first-ai-agent-in-n8n, /articles/hermes-vs-n8n-choose-by-job

Sündmusepõhised agendid õigustavad end, kui iga marsruut on kitsas, autenditud ja jälgitav ning sellel on seadistatud edastussihtmärk. Veebikonksu adapter on sündmuste sisenemise välisuks, mitte kandjaautentimisega päringu-vastuse API. Kujunda ja testi seda vastavalt.