Paperclip

A Paperclip nyílt forráskódú vezérlősík ügynökcsapatokhoz: Node.js szerver és React felület, ami egy helyen tartja a feladatokat, az ügynökök futásait, a jóváhagyásokat és a költségeket. Felülnézetben feladatkezelőnek látszik, alatta viszont szervezeti felépítés, jogosultságok, költségvetés és ügynök-koordináció működik.

A Paperclip maga nem ügynökmotor, és nem futtat modellt. Az ő dolga, hogy eldöntse, melyik ügynök mikor kap munkát, mit lát belőle, és mennyit költhet. A tényleges munkát adapterek végzik, amelyek a futásidejű környezethez kapcsolódnak.

Hogyan épül fel?

• Vezérlősík. Cégek, ügynökök, feladatok, jóváhagyások, futások és költségek egy API mögött, és ugyanez a felületen is elérhető.
• Adapterek. Minden adapter ugyanazt a néhány dolgot végzi: elindítja vagy meghívja a futtató környezetet, átadja neki a cégre, a feladatra és az ébresztésre vonatkozó kontextust, majd összegyűjti az eredményt, a munkamenet állapotát és a használati adatokat. Indulás előtt ellenőrzi a környezetet.
• Szívverés. Az ügynökök nem futnak folyamatosan. Ütemezetten ébrednek, megnézik, van-e munkájuk, végeznek egy lépést, majd visszaalszanak.
• Cél és elszámoltathatóság. Minden feladat visszavezethető a cég céljához, a feladatok állapota és a hozzájuk tartozó futások naplója pedig megmarad.

Ez a felosztás teszi lehetővé, hogy ugyanabban a rendszerben egy Claude Code és egy Codex ügynök ugyanazon a táblán dolgozzon, emberi felügyelettel.

Melyik ügynököket kötjük be?

A beépített adapterek a telepítéssel együtt elérhetők. Amelyeket nálunk használunk:

• claude_local és codex_local: a helyi CLI-t indítják, munkamenet-folytatással és strukturált kimenet-feldolgozással.
• hermes_local: a Hermes Agent fut ugyanazon a gépen, tartós memóriával, saját eszközkészlettel és skill-szinkronizálással. Az adapter a Hermes egyszeri lekérdezéses módját indítja, és a kimenetét eszközhívásokra bontva jeleníti meg.
• hermes_gateway: távoli Hermes API szerverhez csatlakozik HTTP vagy HTTPS fölött. Futást indít, az eseményeket SSE folyamon keresztül streameli, szakadás esetén újracsatlakozik, és időtúllépéskor leállítja a futást. A munkamenet-kulcs stratégiája feladathoz, ügynökhöz vagy futáshoz köthető, így egy feladat kontextusa nem szivárog át a másikba.
• process és http: saját szkripthez vagy saját szolgáltatás webhookjához, amikor a futtató környezet nem CLI.

Külső adapter külön csomagként is telepíthető, ilyenkor a beépítettekkel azonos módon viselkedik, de önálló verzióval.

A szívverés: hogyan dolgozik egy ügynök

Az ébredés menete rögzített, és minden ügynök ugyanezt követi:

1. Lekéri a saját ügynökrekordját: azonosító, cég, szerep, költségvetés.
2. Ha egy nyitott jóváhagyásra ébredt, azt zárja le először.
3. Lekéri a rá váró feladatokat, fontossági sorrendben.
4. A munka megkezdése előtt kijelöli a feladatot magának. Ha azt már egy másik ügynök vitte el, a válasz ütközés, és ilyenkor nem próbálkozik újra, hanem másik feladatot választ.
5. Elvégzi a munkát, és a futás azonosítójával együtt frissíti az állapotot, kommentben hagyva, mi történt és mi a következő lépés.
6. Nagyobb munkát gyerekfeladatokra bont, és azokra bízza a további ébresztést ahelyett, hogy ő pörögne.

A futás kimenete külön metaadat: kész, előrelépett, csak terv készült, üres válasz, blokkolt, hibás vagy utánkövetést igényel. A feladat állapotát ez nem írja felül. Ha az automatikus folytatás kimerül, a rendszer audit-kommentet hagy, hogy ember dönthessen.

Üzemeltetés nálunk

Nálunk a Paperclip Docker Compose alatt fut, két konténerrel: az alkalmazás saját image-ből, mellette PostgreSQL 17 adatbázis külön köteten. A felületet a szerver szolgálja ki, a telepítési mód pedig hitelesítést kérő, privát üzem: bejelentkezés kell hozzá, és a nyilvános URL valamint az engedélyezett hosztnevek rögzítve vannak.

A dokumentáció három üzemmódot ír le: helyi, bejelentkezés nélküli üzem csak loopbacken; hitelesített, privát üzem belső hálózatra; és hitelesített, nyilvános üzem internet felé, szigorúbb ellenőrzésekkel. Az adatok - az adatbázis, a feltöltött fájlok, a titkok kulcsa és az ügynökök munkaterülete - a konténeren kívüli köteten maradnak meg.

Amire figyelni kell

• Az adapter mentés előtt környezetellenőrzést futtat. A helyi CLI-nek telepítve kell lennie, különben az adapter hiányzó előfeltételt jelez.
• Távoli, nem loopback címre a sima HTTP alapértelmezésben tiltott. HTTPS vagy privát hálózat kell hozzá.
• A költségvetés havi keret. Ha elfogy, az ügynök megáll, ezért a költségeket nézni kell, nem csak a kimenetet.
• Az ütközés nem hiba, hanem jelzés: a feladat másé. Az újrapróbálkozás csak zajt csinál.
• A jogosultságokat és a titkokat szűken kell adni, a külső hatású lépéseket pedig jóváhagyáshoz kötni.

Nálunk a Paperclip akkor hasznos, ha több ügynök dolgozik egy közös célon, és látni akarjuk, ki mit csinált, mennyibe került, és hol kell emberi döntés.

Tovább olvasás

• Paperclip a GitHubon
• Adapterek áttekintése
• Hermes adapter a dokumentációban